0.5.0 — wait tool for codex push notifications

[wenqingyu]

Summary

Adds a single new MCP tool wait that replaces the dispatcher's poll-based ScheduleWakeup loop. The dispatcher calls wait once after spawning a batch of codex agents; the call hangs until any agent terminates, then returns a batched list of all agents that transitioned within a short coalescing window. No more 5-min polls, no more prompt-cache misses on every wake.

Why

The old pattern: dispatcher spawns N agents → ScheduleWakeup every ~5 min → wake → call status → most still running → sleep again. Each wake re-reads the full conversation context (cache TTL is 5 min) and waiting agents are reacted to ~5 min after they actually finish.

With this PR: dispatcher calls wait once, the connection stays open, Claude wakes exactly when an event happens. For a 5-agent fan-out where all complete near-simultaneously, that's 1 wake instead of 5-10 polls.

Tool surface

wait({
  timeout_seconds?: number,        // default 1500 (25 min)
  since?: string,                  // ISO; replay events with ended_at > since
  agent_ids?: string[],            // optional scope
  terminal_only?: boolean,         // default true
  batch_window_ms?: number,        // default 100; coalesces fan-out tails
}) → {
  events: AgentSummary[],
  observed_at: string,             // pass as `since` next call
  agents_still_running: number,
  agents_running_ids: string[],
  timed_out: boolean,
}

Design + plan docs

• Design: docs/plans/2026-04-27-codex-worker-notifications-design.md
• Plan: docs/plans/2026-04-27-wait-tool-implementation.md (executed by a magic-codex implementer agent in this same release cycle — meta)

Test plan

• npm run typecheck — clean
• npm test — 117 passing (was 108); 9 new tests
  • Registry: emits change on update; zombie sweep does NOT emit
  • wait replay: returns historical events without blocking
  • wait replay: filters by agent_ids and since
  • wait live: resolves when agent reaches terminal
  • wait live: coalesces multiple terminations within batch window
  • wait live: clean timeout with no listener leak
  • wait live: agents_still_running honors agent_ids scope
• npm run build — version-drift guard validates all 5 literals match 0.5.0
• Manual: dispatch a fan-out batch, call wait, confirm one wake delivers all completions

🤖 Generated with Claude Code