pi alarm: fire when a command exits or when processes exit

when_done runs a command (bash -c, in pi's cwd, output to a log file) and
fires when it exits, with its exit status; cancelling the alarm or ending
the session stops it. when_exits polls PIDs already running and fires once
all are gone. Either takes an optional deadline, 24 hours by default, at
which the alarm fires anyway and a still-running command is stopped.

A process exiting is a signal any condition can be turned into -- gh run
watch, sz-wait-for, an until-curl loop -- so the agent can start something
long, end its turn and be woken, instead of blocking on it. The delivery
path is the existing one, unchanged.

pi-subagent: §5 sets an alarm on the runs' PIDs instead of waiting.

1 files changed, 26 insertions, 3 deletions

diff --git a/skills/pi-subagent/SKILL.md b/skills/pi-subagent/SKILL.md
index 7b17e50..06862c0 100644
--- a/skills/pi-subagent/SKILL.md
+++ b/skills/pi-subagent/SKILL.md
@@ -153,9 +153,32 @@ Expect minutes to tens of minutes per run. Check progress with:
 `status.sh` exits 3 while anything is still running, and also prints free disk
 space — the event streams are big while runs are in flight.
 
-**Don't sit on the wait loop.** Launching early is only worth it if you use the
-time: do your own investigation of the same question, build whatever harness
-you'll need to check the answers, establish baselines. You need your own
+**Get woken instead of waiting.** In an interactive pi, the `alarm` tool can
+fire when processes exit. Launch, set one alarm on all the runs' PIDs, and end
+your turn: when the last run exits, the alarm starts a new turn, or arrives
+after the tool call in progress if you're busy by then. For the PIDs, print
+`$!` after each launch in the same bash call, or read `"$P"/out/*.running`,
+which holds each run's PID while it's in flight.
+
+```
+alarm action=set when_exits=[<pids>] in_minutes=<the --timeout, in minutes, + 5>
+  note="pi-subagent runs <names> in <$P> have ended. Run <$SK>/status.sh <$P>,
+        handle failures (§6), verify (§7), report with the cost table (§8)."
+```
+
+- Write the note with absolute paths. By the time it fires, this context may
+  have been compacted away.
+- One alarm per PID wakes you as each run ends instead. That's worth it for a
+  long split whose parts you can check as they come; for a fan-out, one
+  alarm for all is the point.
+- The alarm sees no exit status. `status.sh` has it.
+- The deadline is a backstop, in case a run hangs past its own timeout.
+- Without the `alarm` tool (print or RPC mode), monitor with `status.sh`.
+
+**Don't sit on the wait loop.** With an alarm set, there's nothing to wait
+for. Otherwise, launching early is only worth it if you use the time: do your
+own investigation of the same question, build whatever harness you'll need to
+check the answers, establish baselines. You need your own
 evidence in §7 regardless. When you do block, give the shell call a timeout
 and loop, rather than one unbounded wait.