# 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-/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).