[zacheryph]

Step 12 of the subagent work roadmap. Stacked on #120 (step 11), then #119, #118, #117, #116, #115, #114 and #113. This is the last of steps 6 to 12.

What

A parent reload no longer stops waiting agents, and a restart reports what it lost.

• Shutdown: session_shutdown used to run abortAll, which cancelled every waiting child's items. It now runs SubagentWork.dispose, then SubagentManager.suspend(), then dispose(reason). suspend cuts a queued or running run short, so the agent reads idle with outcome interrupted. abandonWork, workChanged and finish do nothing while suspended, so nothing is cancelled or reported. The parent's saved record keeps reading queued or running, which is how the next start recognizes the cut-short run. ESC and subagent_stop still go through abortAll and still cancel.
• Per reason: on reload, children that hold open work are told reload, so pi-job keeps their jobs in its reload handoff. On quit, new, resume and fork, children are told quit and their jobs die. The next start finds the items open, reports jobs and subagents lost, and still adopts questions. A done agent, and every child of a delegated session, gets quit.
• Persisted: the v2 record gains an optional waitingOn (labels of the idle agent's open items). Older records read as before. A running or queued agent is checked from its transcript instead.
• Startup: StartupRestore is the last of pi-subagent's session_start handlers. It runs for root sessions on reload, startup and resume only. It adopts the parent's own items for candidate agents, reopens the sessions, settles, and writes one report.
• Reopen without a run: a candidate agent's session is reopened through createSubagentSession with its transcriptPath, with no execution.admit and no turn loop, so it takes no concurrency slot and starts no model run. The child's session_start reason is reload after a reload, which pi-job needs to take back its jobs, and resume after a restart. pi-ask adopts its questions either way. At most four are reopened at once. Whatever nobody adopts is closed as lost by the child's host, which writes work:lost into the child's own transcript.
• One parent message: lost work and interrupted runs go to the parent in a single subagent:lost message, sent with triggerTurn: false, so it wakes nothing. Interrupted records are corrected and saved so a second start doesn't report them again, and the parent's items for reported agents are cancelled silently.
• Wake: a message that arrives during startup, such as a job that ended in the reload gap, wakes the agent through the limiter. Messages already in a transcript before a restart wake nothing. Nothing restarts on its own.
• pi-job (vendored, has a CHANGELOG entry): Owner.parent is recorded at reload suspend, and the parent's session_start no longer warns "awaiting reload handoff; ownership is unknown" about its own children. pi-job's session_start runs before pi-subagent reopens them, so the manual TUI check showed that warning on every /reload.

Added in review

Two review rounds each found something worth fixing before this went up:

• A hung child could block the parent's startup forever. Reopening an agent now has a 20-second bound (RESTORE_TIMEOUT_MS, injectable for tests, not a setting). On timeout the agent is reported as one that "could not be reopened at startup, so its work was not checked", with its record untouched and its adopted item cancelled. It occupies a lane for the bound at most.
• A late session could corrupt a reopened transcript. If a timed-out child's session finally arrived after subagent_send had reopened the same transcript, it ran its host startup against the shared file. In the reviewer's probe it wrote a second work:lost and forked the entry tree, and the whole subagent_send exchange was missing from the reopened branch. createSubagentSession now takes an isStale check, with a second layer in ChildWork. A stale creation writes nothing, skips adoption and settleStartup, and publishes no disposed event. A restore that completes after shutdown disposes its session and registers nothing.
• The subagent:lost message's details was unbounded (13.7 MB for 500 agents with 50 items each). It is now capped at 30 agents and 8 items per list with clipped text, keeping totals. Quotes and backslashes in labels are escaped in the report text.

Tests

• Real sessions (restore-sdk.test.ts): reload with a child waiting on a real job_watch (still waiting, no model request, the job wakes it through the limiter, the parent hears once), a job that ends in the reload gap, a question across a reload, a nested subagent (the grandchild's item is lost, reported, and the child is told), a run interrupted by a reload, a double reload, a missing transcript, six agents with maxConcurrent: 2 (no run and no slot at startup, then all wake), a restart by copying session files (the lost job is reported in one message, the question is adopted, no model run, both agents take subagent_send), and quit, new, resume and fork shutdowns each followed by a restart. A child that hangs in session_start covers the bound and the late session in both arrival orders.
• Unit tests: restore.test.ts (including four fake-timer tests for the bound), lost-report.test.ts, transcript-work.test.ts, the restore handler, and the spawner-side adoption.
• Rewritten, each with a comment: the shutdown-order test in lifecycle.test.ts (it pinned abortAll; it now pins suspend and the child shutdown reason per session-end reason), the restart test in work-sdk.test.ts (it expected a host work:lost for an agent still running at the crash; it now expects an interrupted run in subagent:lost), and records-sdk (a question across a reload now reads waiting: answer). No .skip or .only was added.
• Manual TUI check, done: with the tui-screenshot driver I ran a scripted scenario where a child runs job_watch, ends its turn, and the parent shows waiting: CI. After /reload the Subagents widget still showed waiting: CI and 1 waiting agent, with one "Reloaded" line and no handoff warning. With the watch set to match about 40 seconds after load, the capture afterwards showed the child woken (1 running agent, thinking…). The reviewer re-ran the reload half independently.

Verification

• Tests: pi-subagent 2712, pi-work 111, pi-ask 90, pi-dashboard 113, pi-todo 298 and pi-job 169 (166 pass, 3 skipped as before) pass. Root scripts 33 pass, and the full root npm test exits 0, run twice by the reviewer.
• Checks: npm run check and npm run verify:bundle pass on the final commit.
• Mutations: about 40 across the review rounds. The core ones are all caught: reload still cancelling, lost not reported, the report sent twice, adoption missing, a reopen starting a run or taking a slot, the interrupted outcome missing, reload told as quit, waitingOn not persisted, the bound and late-session disposal removed, and each stale guard.
• Flaky pi-job test: the root npm test failed intermittently on pi-job's job_list, job_read and job_kill. It is a pre-existing timing race in that test, unrelated to this stack: the test is byte-identical on main, and the reviewer reproduced the failure on a clean main checkout under CPU load. It passes in the runs recorded above. I'm opening a separate PR against main to fix the test.

Known gaps

None blocking:

• A late session can still delete services other extensions registered for the live session. The late session's bind-time handlers call provide(sessionId, …) for their own services (pi-stash's stash:service, pi-git's), which overwrites the live session's entry, and the late session's withdraw then removes it. Lookups for those services by the child's id fail until the child restarts. The child's own tools keep working. It needs a hang of more than 20 seconds, a subagent_send in that window, and the hung session finishing later. work:v1 and work:parent are unaffected.
• Two of the stale checks (after the loader reloads, and after the session is built) are untested, because the fixture only hangs inside the child's session_start. Extension writes made directly during bind, such as pi.appendEntry, aren't covered by the stale check. None of the bundled extensions do this.
• Startup waits for reopening, a few agents at a time with the 20-second bound each, so a parent with many waiting agents starts more slowly.
• A reload gap longer than pi-job's five-minute owner expiry still loses the job, and so do the jobs of a child that the new parent never reopens.
• Records written before this step have no waitingOn. They are treated as done, so their open items are reported lost the next time the agent is reopened by subagent_send.
• subagent:lost has no custom renderer. It shows as Pi's default custom message, like work:lost.
• A fork's copied agents are reported lost by the root host's generic message, because a fork doesn't adopt them.
• For step 13: the host's lost wording ("when this session started") for a reopened child, the Run.answering and abandonWork paths that steps 10 and 11 added, rebuildFromSaved (still the lazy path for non-candidates), and abortAll wording in older CHANGELOG entries.

Stack: #113 ← #114 ← #115 ← #116 ← #117 ← #118 ← #119 ← #120 ← this

---

Generated by Claude Code