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

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, 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. 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.