From 9b8b14fe12b2a1751ce7c58ba6f8d49bf38e3d1d Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Thu, 30 Jul 2026 10:33:59 -0700 Subject: [PATCH] fix(codex): event-driven waiting instead of short polls 60-78% of wait_agent calls timed out across every measured corpus; waits are event subscriptions, so one long wait replaces dozens of polls at identical wake latency. --- .../references/codex-tools.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.md index 415638f6..cf2b70ee 100644 --- a/skills/using-superpowers/references/codex-tools.md +++ b/skills/using-superpowers/references/codex-tools.md @@ -36,6 +36,25 @@ disagree. spawn allowlist — V2 accepts only V2-capable presets and hard-errors on the rest. +## Waiting on children + +`wait_agent` is an event subscription, not a poll: a long wait wakes +the moment a child produces mailbox activity, with the same latency as +a short one. Short-timeout polling buys nothing and costs a tool call — +and a context rebill — per poll. In measured sessions, roughly +two-thirds of all wait calls were short polls that timed out. + +- While you still have local work, do not wait at all. A completed + child's final answer is pushed into your mailbox and arrives with + your next turn. +- When you are genuinely idle with children outstanding, issue ONE + `wait_agent` with a long `timeout_ms` — 900000 (15 minutes) or more — + and let the event wake you. +- Completion mail cannot wake an idle controller (it is delivered + without triggering a turn); covering that idle window is + `wait_agent`'s only job. If a long wait times out, check + `list_agents` for stuck children — do not fall back to short polls. + ## Environment Detection Skills that create worktrees or finish branches should detect their