ap-wait-fanin

Wait For Sessions To Finish (Fan-In)

When to use

You've spawned one or more agentproto sessions (see ap-spawn-agent) and need to know the moment any — or all — of them finish a turn, hit awaiting-input, or exit. This is the fan-in step: block cheaply instead of burning your own context re-checking output by hand.

Gotchas — read this before you wait on anything

• Never write a shell/terminal polling loop (for i in ...; do check; sleep; done) to wait on children. A watchdog killing you mid-loop permanently corrupts the underlying session into an "already has an in-flight prompt" error that survives a restart — this happened in production on 2026-09-01 and the session never recovered. If you spawn a supervisor sub-agent that will itself wait on children, brief it explicitly: session_monitor is THE fan-in mechanism, shell poll loops are forbidden.
• session_monitor can miss ultra-fast children. If a trivial child finishes before you attach the watch, the watch never fires for it. Parry by taking a session_events_poll cursor BEFORE spawning children, or by confirming completion via agent_output once a timeout elapses.
• Arm the watch at spawn time. Wakeup timers / scheduled re-checks are a safety net only — the primary mechanism is the long-poll itself, not a cron that happens to fire later.

MCP: session_monitor

Multiplexed long-poll across N sessions. Returns on the FIRST watched session to fire the requested event — you decide whether to keep waiting on the rest.

{
  "tool": "session_monitor",
  "args": {
    "sessionIds": ["sess_abc123", "sess_def456"],
    "event": "turn-end",
    "timeoutMs": 45000
  }
}

Valid event values: turn-end, awaiting-input, exited, any. timeoutMs accepts 1000-49000 — it is a long-poll, not an indefinite wait, so for longer horizons re-issue the call after each timeout. Prefer the CLI alternative below when a real shell is available to you.

MCP: session_events_poll