From 9b8b14fe12b2a1751ce7c58ba6f8d49bf38e3d1d Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Thu, 30 Jul 2026 10:33:59 -0700 Subject: [PATCH 1/3] 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 From db4538fcb849be0273c792064355546388410f12 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Thu, 30 Jul 2026 12:50:42 -0700 Subject: [PATCH 2/3] fix(sdd): controllers wait long or not at all Docs-only wait guidance in the platform reference changed nothing (65.1% vs 67.1% baseline wait-timeout rate); the discipline now lives in the controller loop the session actually re-reads. --- skills/subagent-driven-development/SKILL.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 6c0b8349..cc4ad113 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -197,6 +197,14 @@ Everything you paste into a dispatch prompt — and everything a subagent prints back — stays resident in your context for the rest of the session and is re-read on every later turn. Hand artifacts over as files. +**Waiting on dispatched subagents:** never poll a wait interface with +short timeouts. While you have local work — ledger updates, packaging +the next review, reading reports — keep working; child results arrive +on their own. Wait only when you are genuinely idle, and then issue one +long wait (fifteen minutes or more, where your platform allows it) +instead of many short ones: a long wait wakes just as fast and costs +one call instead of dozens. + ### 1. Dispatch the implementer Record BASE (`git rev-parse HEAD`) before dispatching — the review package From d8189d1587ed29cbf7b01ed4138edc8799164898 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Thu, 30 Jul 2026 15:57:32 -0700 Subject: [PATCH 3/3] fix(sdd,codex): bounded wait stretches with reconciliation Round 2 proved the long-wait mechanism (65.1%->0.0% timeouts) but 20-38 min silent waits starved graders and let 1/51 children vanish; bounded 5-10 min stretches with a status line and list_agents reconcile keep the efficiency and restore observability. --- skills/subagent-driven-development/SKILL.md | 15 +++++++++------ .../using-superpowers/references/codex-tools.md | 14 +++++++++----- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index cc4ad113..5a7da97b 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -198,12 +198,15 @@ prints back — stays resident in your context for the rest of the session and is re-read on every later turn. Hand artifacts over as files. **Waiting on dispatched subagents:** never poll a wait interface with -short timeouts. While you have local work — ledger updates, packaging -the next review, reading reports — keep working; child results arrive -on their own. Wait only when you are genuinely idle, and then issue one -long wait (fifteen minutes or more, where your platform allows it) -instead of many short ones: a long wait wakes just as fast and costs -one call instead of dozens. +short timeouts, and never sit in one silent, open-ended wait either. +While you have local work — ledger updates, packaging the next review, +reading reports — keep working; child results arrive on their own. +When you are genuinely idle, wait in bounded stretches (five to ten +minutes, where your platform allows), and between stretches post one +line of status and reconcile your live children: list them, and chase +any that finished without reporting. A bounded stretch keeps nearly +all of a long wait's efficiency while guaranteeing a stuck or lost +child is noticed within minutes, not at the end of the session. ### 1. Dispatch the implementer diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.md index cf2b70ee..077550e0 100644 --- a/skills/using-superpowers/references/codex-tools.md +++ b/skills/using-superpowers/references/codex-tools.md @@ -47,13 +47,17 @@ 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. +- When you are genuinely idle with children outstanding, wait in + bounded stretches: `wait_agent` with `timeout_ms` 300000-600000 + (5-10 minutes). After each stretch — wake or timeout — post one + status line, run `list_agents`, and chase any child that finished + without reporting. Never stack polls shorter than five minutes; the + event subscription wakes a bounded stretch just as fast as a short + one. - 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. + `wait_agent`'s only job. A stretch that times out with no activity + is your cue to reconcile, not to shorten the next stretch. ## Environment Detection