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.

README.md

@@ -3,12 +3,6 @@
 Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them.
 
 
-## We're Hiring!
-
-We're hiring someone to help out full time with Superpowers community and code work. 
-You can read about the job at https://primeradiant.com/jobs/superpowers-community-engineer/
-If this sounds like someone you know, definitely send them our way.
-
 ## Quickstart
 
 Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).

docs/releasing-to-codex.md

@@ -1,85 +0,0 @@
-# Releasing to the Codex portal
-
-How to package a Superpowers release as the zip artifact OpenAI's Codex
-plugin portal expects, and what to check before handing it over.
-
-This is distinct from the older flow of syncing files into a fork of
-`openai/plugins` and opening a PR, which
-`scripts/sync-to-codex-plugin.sh` still implements — see the distribution
-table in [porting-to-a-new-harness.md](porting-to-a-new-harness.md). The portal
-artifact is a standalone, rootless archive: `.codex-plugin/`, `assets/`,
-`skills/`, `README.md`, `LICENSE`, and `CODE_OF_CONDUCT.md` sit at the
-archive root. Hooks, tests, docs, scripts, and other harnesses' manifests
-are deliberately not shipped.
-
-## Prerequisite: the OpenAI metadata source
-
-Each packaged skill must carry `skills/<name>/agents/openai.yaml`. That
-metadata is OpenAI-owned — it does not live in this repo — so the packaging
-script seeds it from a prior official package. By default it looks for, in
-order:
-
-1. `../_tmp/sup-codex-packaging/superpowers/` (an unpacked package)
-2. `../_tmp/sup-codex-packaging/superpowers.zip`
-3. `../_tmp/sup-codex-packaging/superpowers.tar.gz`
-
-or pass `--metadata-source <dir|.zip|.tar.gz>` explicitly.
-
-If you have no prior package on disk, extract one from `openai/plugins`
-(the upstream repo still carries the plugin, including the metadata):
-
-```bash
-# from a clone with an `upstream` remote pointing at github.com/openai/plugins
-git fetch upstream
-mkdir -p ../_tmp/sup-codex-packaging/superpowers
-git archive upstream/main -- plugins/superpowers |
-  tar -x --strip-components 2 -C ../_tmp/sup-codex-packaging/superpowers
-```
-
-**New skills fail the build.** The script requires one `openai.yaml` per
-skill directory; otherwise it prints `Missing OpenAI agent metadata for
-skill: <name>` for each gap and dies with `metadata source is incomplete`.
-If a release adds a skill, there is no metadata for it yet;
-you need an updated official package (or metadata added upstream in
-`openai/plugins`) before you can package. Don't hand-invent the yaml.
-
-## Build the archive
-
-From a clean working tree, package the release tag:
-
-```bash
-scripts/package-codex-plugin.sh --ref vX.X.X
-```
-
-The script reads the version from `.codex-plugin/plugin.json` (bumped by
-`scripts/bump-version.sh`, so it matches the release tag), stages the tree
-from the git ref — never from the working copy — and writes
-`../_tmp/sup-codex-packaging/superpowers-VERSION.zip`, printing entry
-count, skill count, and a SHA-256. Timestamps and file order are pinned so
-rebuilding the same ref reproduces the same archive.
-
-Useful flags: `--output PATH`, `--format zip|tar.gz`, `--allow-dirty`
-(archive still comes from `--ref`), `--keep-stage` (inspect the staging
-dir). `--help` has the full list.
-
-## Verify
-
-The script already refuses archives containing source-only paths and
-mismatched metadata counts. Sanity-check the result anyway:
-
-```bash
-unzip -Z1 ../_tmp/sup-codex-packaging/superpowers-X.X.X.zip | head
-unzip -Z1 ../_tmp/sup-codex-packaging/superpowers-X.X.X.zip | grep -c 'agents/openai.yaml'
-unzip -p  ../_tmp/sup-codex-packaging/superpowers-X.X.X.zip .codex-plugin/plugin.json | jq -r .version
-```
-
-Expect: rootless top-level entries (`.codex-plugin/`, `assets/`,
-`skills/`), one `openai.yaml` per skill, and the release version.
-
-The script itself is covered by `tests/codex/test-package-codex-plugin.sh`.
-
-## Upload
-
-Upload the zip through OpenAI's Codex plugin portal. This is a manual step
-outside this repo; record the SHA-256 the script printed so the uploaded
-artifact can be matched to the build.

skills/subagent-driven-development/SKILL.md

@@ -197,6 +197,17 @@ 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, 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
 
 Record BASE (`git rev-parse HEAD`) before dispatching — the review package

skills/using-superpowers/references/codex-tools.md

@@ -7,7 +7,57 @@ Add to your Codex config (`~/.codex/config.toml`):
 multi_agent = true
 ```
 
-This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. When using subagent-driven-development, close reviewer subagents when their review returns. Keep each implementer subagent open until its task's review passes — the fix loop resumes the implementer — then close it. If your harness cannot send another message to a spawned agent, dispatch each fix round as a fresh implementer carrying the brief, the report file, and the findings.
+This enables the multi-agent tools that skills like
+`dispatching-parallel-agents` and `subagent-driven-development` use.
+Which tools you get depends on the multi-agent version your model
+preset selects (current presets run V2; older ones run V1). Trust your
+actual tool list over any table — including this one — when they
+disagree.
+
+- **Spawning:** give children a clean context with
+  `spawn_agent {fork_turns: "none"}`; the default `"all"` copies your
+  entire transcript into the child. On Codex 0.145+, role files under
+  `~/.codex/agents/` attach to isolated forks via `agent_type`.
+  Full-history forks accept `model` and `reasoning_effort` overrides
+  (only `agent_type` is refused there) — isolated forks are the SDD
+  default for context hygiene, not because overrides require them.
+- **Fix rounds:** resume the implementer with `followup_task` — it
+  delivers your message, triggers a turn, and transparently reloads a
+  child the harness evicted. Never dispatch a fresh implementer on the
+  theory that a spawned agent cannot be messaged again; on V2 it
+  always can.
+- **Lifecycle:** V2 has no `close_agent`. Finished children are
+  evicted automatically when slots are needed; leaving them unclosed
+  costs nothing. Only V1 sessions have `close_agent` — there, close
+  reviewers when their review returns, and close each implementer
+  after its task's review passes.
+- **Model names:** never copy a model name from a skill, table, or old
+  session into `spawn_agent` without checking it against your current
+  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, 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. A stretch that times out with no activity
+  is your cue to reconcile, not to shorten the next stretch.
 
 ## Environment Detection