feat(workflow): checkpoint GSD before five-hour quota exhaustion
This commit is contained in:
1 parent
73954e675d
commit
c9b9f2eba9
9 files changed
+758
-1
No files matched your search
@@ -0,0 +1,85 @@
|
||||
# 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.
|
||||
@@ -1,5 +1,13 @@
|
||||
# Compatibility and validation
|
||||
|
||||
## Workflow quota guard — 2026-11-13
|
||||
|
||||
Local Codex0.169.0 Linux Unix-WebSocket quota read and watcher verified; five
|
||||
project hooks discovered, awaiting user trust. Targeted simulated quota, policy,
|
||||
transport and recovery tests pass. Real exhaustion/active-turn pause is not
|
||||
induced; pause remains cooperative. Windows hook override is a no-op. No game
|
||||
build, package or original/native Windows acceptance claim changes.
|
||||
|
||||
## Phase 1 wave 2 bounded observer evidence
|
||||
|
||||
Full authorized wave2 `scripts/test.sh` exits0:462 Python+2 HUD checks,
|
||||
|
||||
@@ -1,5 +1,13 @@
|
||||
# Decisions
|
||||
|
||||
## Quota reserve — 2026-11-13
|
||||
|
||||
Use actual300-minute account quota and server reset time. Reserve20% for
|
||||
existing workers and15% for handoff. Poll locally without model turns; preserve
|
||||
a private independent recovery snapshot and request cooperative GSD pause.
|
||||
Never auto-resume, commit partial source, restart Codex, or bypass hook trust.
|
||||
See [guard contract](codex-quota-guard.md).
|
||||
|
||||
## Passive evidence observation — phase 1 wave 2
|
||||
|
||||
Keep one optional application-owned clock across Run continuations. Record raw,
|
||||
|
||||
@@ -1,5 +1,14 @@
|
||||
# Progress — 2026-11-07
|
||||
|
||||
## Local quota guard — 2026-11-13
|
||||
|
||||
Installed Linux quota watcher and five project hooks; real local account quota
|
||||
read succeeds, watcher runs, and targeted policy/recovery tests pass. Hook trust
|
||||
remains a user `/hooks` action. At20% remaining new workers are denied; at15%
|
||||
remaining recovery is saved and registered active turns receive a cooperative
|
||||
GSD pause request. See [setup and limits](codex-quota-guard.md). Phase01-05 task2
|
||||
partial edits remain untouched; no gameplay or acceptance status changed.
|
||||
|
||||
## Phase 1 wave 2 — review, ledger and passive observation
|
||||
|
||||
Full authorized wave2 `scripts/test.sh` exits0:462 Python+2 HUD checks,
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# Tasks
|
||||
|
||||
## Quota-aware GSD continuation — 2026-11-13
|
||||
|
||||
- [x] Install/test local60-second quota watcher,20% dispatch gate,15% pause request.
|
||||
- [ ] User review/trust the five project quota hooks via `/hooks`.
|
||||
- [ ] Resume `$gsd-resume-work` when desired; retain01-05 task2 partial edits.
|
||||
|
||||
## Phase 1 execution — wave 2
|
||||
|
||||
- [x]01-02 paired local review:21 Python/27 Node checks and real Chromium
|
||||
|
||||
Reference in new issue
Block a user