86 lines
4.7 KiB
Markdown
86 lines
4.7 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).
|
|
|
|
Source-control note: guard changes are committed locally. Push is deferred until
|
|
the earlier unfinished plan01-05 task2 RED checkpoint is green; pushing this
|
|
branch now would also publish that unverified ancestor.
|