Files
Neutron/docs/codex-quota-guard.md

82 lines
4.5 KiB
Markdown

# Codex quota guard
This repository has a local Linux watcher and project hooks for the user's
requested GSD quota policy. The watcher polls the existing Codex app-server every
60 seconds; it does not start model turns or read credentials. It uses the
300-minute account window and its actual reset timestamp, preferring the general
`codex` bucket over specialty-model buckets.
- At **20% remaining or less**, `PreToolUse` denies new `Agent`, `spawn_agent`,
and `followup_task` calls. Existing workers may finish their safe checkpoint.
- At **15% remaining or less**, the watcher saves a separate recovery snapshot
and sends each registered active turn one request to checkpoint with
`$gsd-pause-work` and end. Tool hooks also supply that instruction once per turn.
- Missing, expired, or older-than-180-second quota data blocks new worker dispatch
until a fresh reading arrives. Checkpoint tools remain available.
- The watcher never starts a turn, interrupts a process, commits unfinished work,
pushes code, or automatically resumes after reset.
## One-time activation
The source is `tools/workflow/codex_quota_guard.py`; project configuration is
`.codex/hooks.json`. Existing global GSD hooks are preserved and additive.
Open **`/hooks`** in Codex, review and trust the five hooks from this project's
`.codex/hooks.json`. New definitions remain skipped until reviewed; see the
[official hook trust instructions](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks).
The watcher has been started for this host, but thread registration and tool
blocking require trusted hooks. A later session's `SessionStart` hook starts
another watcher only if one is not already running.
The guard targets this Linux Codex host, not the Windows original-game test
machine. Windows uses a no-op command override. It does not restart Codex or
change provider/model/account settings.
## Commands
From the repository root:
```sh
python3 tools/workflow/codex_quota_guard.py status
python3 tools/workflow/codex_quota_guard.py refresh
python3 tools/workflow/codex_quota_guard.py start
python3 tools/workflow/codex_quota_guard.py stop
```
`status` includes the lock-verified `running` flag, current reading, reset epoch,
and any last poll error type. `refresh` uses the existing local daemon socket and
may need execution outside the agent sandbox. It neither starts a daemon nor a
model turn. `stop` requests termination within a second after any in-flight RPC
finishes; hooks start the watcher again, so disable the project hooks in `/hooks`
when turning the guard off permanently. `start` clears the stop marker when its
singleton watcher starts. No service or cron entry is installed.
After quota resets, send **`$gsd-resume-work`**. The current saved continuation is
phase 01, plan 01-05, task 2; preserve its partial edits and do not repeat task 1.
Resumption remains a user action even after the account has recovered.
## Recovery and limits
Ignored private state is under `artifacts/gsd-quota/`. `quota.json` stores only
counters/timestamps. Per-thread registration stores thread/turn identifiers, not
conversation contents. At low quota, `recovery-<reset>/record.json` saves the Git
HEAD, status, tracked patch (capped at 2 MiB), and existing GSD state/handoff text
(capped at 256 KiB each). It supplements and never replaces the canonical GSD
handoff. Untracked file contents remain in the working tree; this is not a full
backup. Source changes after that one-per-window snapshot rely on the working
tree and the model's final handoff. Files are private to the local account.
The pause is **cooperative**. Polling may lag usage by a minute, a long active
model request may consume the reserve, and no model can guarantee writing a
handoff after the provider exhausts quota. The independent recovery record still
runs without model tokens. Tool hooks cover supported local tool paths; launching
workers through unrelated shell scripts or other clients bypasses this specific
dispatch policy. Weekly and specialty-model limits are not guarded. Inactive or
mismatched turns are never restarted by the watcher.
Verified against local Codex 0.169.0: real Unix WebSocket quota read, project hook
discovery (five hooks awaiting trust), singleton background watcher, and 24 targeted
unit tests. Simulated low-quota tests verify pause steering and snapshot behavior;
no real quota depletion or active gameplay work was induced to test the threshold.
See the [official app-server protocol](https://learn.chatgpt.com/docs/app-server)
and [hook contracts](https://learn.chatgpt.com/docs/hooks).