4.5 KiB
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,
PreToolUsedenies newAgent,spawn_agent, andfollowup_taskcalls. 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-workand 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.
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:
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 and hook contracts.