@howarewoo/pi-subagents 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [0.3.0]
+
+Requires Node 22.19+ and stable Pi 1.5.2 or newer, unchanged from 0.2.x. Tested host
+remains Pi 1.5.2; newer stable hosts are allowed, not guaranteed compatible.
+
+### Breaking — completed-context resume and migration
+
+- Resume of successfully completed work now continues the same full SDK conversation and tool history, with the same identity, generation and session count, rather than starting a fresh session. To start fresh work in a new generation, use explicit model-issued `delegate_coordinate` `followup` or `revive` and supply the context it needs; those operations do not replay the old conversation.
+- Only the deadline window resets on resume; request/tool/spawn counters remain cumulative, with at most 64 execution windows per generation. Paused windows retain provisional structured submission state and publish no final outcome artifacts. Completed windows preserve immutable outcome/artifact evidence in `completedWindows`; later completed-window artifacts use `window-N/` without replacing earlier files. Resumed completed structured assignments require a new `submit_result`.
+- Context restoration lasts only for the current parent runtime; saved transcripts are not reload/restart recovery state. Let active tasks drain before updating, then restart Pi. Reload/shutdown aborts and drains children rather than migrating them. Resume the exact parent generation first, then explicitly resume selected children; descendants never resume automatically. Existing authority, grants, authentication, capacity and writer checks still apply.
+
+### Changes
+
+- Make the queued deadline/continuation lifecycle regression test deterministic with a controlled deadline clock, preserving pre-dispatch expiry and repeated continuation coverage while verifying shutdown disposes an actual retained SDK session. Runtime deadline policy is unchanged.
+
+- Correct resume to continue paused or successfully completed conversations with the same identity, generation, session count and full SDK/tool history. Completed runtimes restore from the canonical SessionManager into the same transcript, never a result summary or silent fresh generation. Preserve cumulative budgets and earlier window artifacts/outcomes; revalidate current authority/auth/capacity, reject stopped/failed/retired/unavailable identities, and bound continuations to 64 windows. Explicit followup/revive behavior is unchanged.
+
+- Preserve successfully completed descendants across ancestor completion for explicit parent-first same-context resume, without undoing explicit retirement. Validate retained post-handoff model availability on resume rather than requiring the obsolete admission model; keep lineage, grants and writer checks.
+
+- Count individual subagent sessions, including retained historical generations, in the widget total using the same roster source as the unfiltered Hub. Distinct tasks sharing a profile and nested sessions each count separately; active widget rows remain bounded and scheduling/lifecycle behavior is unchanged.
+
 ## [0.2.1]
 
 Requires Node 22.19+ and stable Pi 1.5.2 or newer. Tested host remains Pi 1.5.2;

package/README.md

@@ -104,7 +104,7 @@ Pi discovers the native `subagent` tool at startup through its tool description
 - `worker` maps to the configured `implementation` profile; `scout`, `review` and `general` are also available.
 - Calls are async by default and wake the parent after drain. Set `async:false` to wait; use `tasks:[{agent,task,cwd?}]` for a batch.
 - Control a task with its returned `id` and `action:"status"`, `"steer"`, `"stop"` or `"resume"`. Steer/resume also require `message`.
-- Resume keeps a paused conversation in the same generation. Completed idle/parked work gets a fresh generation, so include needed prior conclusions.
+- Resume continues a drained paused **or completed** conversation, preserving the same identity, generation, session count and full SDK conversation/tool history. Completed idle/parked agents restore their canonical session into a new SDK runtime using the same transcript, not a result summary. Missing restoration state, stopped/failed identities and retired descendants reject; there is no fresh-context fallback. Explicit `delegate_coordinate` followup/revive still start fresh work.
 
 The coordinator supplies an existing workspace and the complete handoff, including accessible skill/reference paths. The extension does not create or manage worktrees. This is the [supported orchestration interface](docs/delegation-contract.md#native-orchestration-compatibility), not compatibility with every competing workflow script or custom agent definition.
 
@@ -197,7 +197,7 @@ All bundled profiles may delegate to `scout` and `review` by default, within a t
 Default task limits are **30 minutes**, **100 model requests** and **100 tool calls**:
 
 - A deadline pauses the active subtree after tool/provider drain, releasing capacity and writer leases but retaining sessions and conversations.
-- Use `subagent` resume or root-only `delegate_coordinate` `{action:"resume",target:{id,generation},assignment:"Continue…"}` to continue the same identity and conversation. Only the deadline resets; request/tool/spawn counters remain cumulative.
+- Use `subagent` resume or root-only `delegate_coordinate` `{action:"resume",target:{id,generation},assignment:"Continue…"}` to continue the same identity and conversation. Only the deadline resets; request/tool/spawn counters remain cumulative (at most 64 windows per generation). Completed windows retain earlier result/artifact evidence in `completedWindows`; a resumed completed structured assignment requires a new `submit_result`.
 - Resume the parent first, then explicitly selected children. Descendants never resume automatically.
 - Stop, shutdown and hard request/tool limits cancel and dispose. Unresponsive code must drain before pause or cancellation can release resources.
 

package/docs/delegation-contract.md

@@ -29,10 +29,10 @@ The model-only `subagent` tool is registered and described through Pi's public `
 - Launch: `{agent,task,cwd?,model?,limits?,async?}`. `agent` is required: `general`, `scout`, `review`, `implementation`, or explicit compatibility name `worker` for the configured `implementation` profile. Unknown/custom agent definitions are rejected, not silently mapped. Authority and prompts still resolve through the existing profiles; no ambient Markdown agent loading or role/model fallback is added.
 - Batch: `{tasks:[{agent,task,cwd?,model?,limits?}],cwd?,async?}`. Shared cwd is the default for items lacking one. Existing whole-batch preflight, FIFO limits, ordered outcomes and global writer serialization apply.
 - `async` defaults true; false waits for final results. Accepted calls return immediately with exact `id:"UUID@generation"`, `taskId` (original UUID), generation and normal snapshot fields/artifact references. Control handles never prefix-match or resolve to the latest generation. Native `delegate_task` retains its UUID+generation output and foreground default.
-- Read/control: `{action:"agents"}` or `"list"`; `{action:"status"|"stop",id}`; `{action:"steer"|"resume",id,message}`. Status can inspect a historical generation; mutations refuse stale handles. Resume continues a drained paused assignment in the same SDK conversation and generation. For completed idle/parked presence it still starts a fresh generation in the original workspace, requiring current narrowing checks; include needed prior conclusions for that fresh assignment. Native coordination remains available for richer inbox/wait/park behavior.
+- Read/control: `{action:"agents"}` or `"list"`; `{action:"status"|"stop",id}`; `{action:"steer"|"resume",id,message}`. Status can inspect a historical generation; mutations refuse stale handles. Resume continues a drained paused or successfully completed (idle/parked) assignment in the same conversation and generation, without increasing session count. Completed runtime graphs are reconstructed from the retained canonical SessionManager, preserving system context and actual tool history in the same transcript; no previous-result-summary or fresh-context fallback is allowed. Stopped, failed, cancelled, retired or unavailable conversations reject without starting new work. Use explicit `delegate_coordinate` followup/revive for fresh work. Native coordination remains available for richer inbox/wait/park behavior.
 - Model overrides accept the native exact selection object or `provider/id[:effort]`. Omitted effort uses the parent's selected effort; overrides still require exact operator grants, availability/auth/scope and supported effort. Bare model IDs and unknown providers are not guessed. Omitting model retains ordinary parent/profile routing.
 
-An async compatibility launch sends one window-outcome custom message per single/batch call after actual drain (paused or completed), using public `sendMessage(...,{triggerTurn:true,deliverAs:"followUp"})` to wake the parent. Compatibility resume does the same once for its new execution window or fresh completed-agent generation. This may cause a parent model turn and provider charges; no polling or detached worker survives parent shutdown. The original native tool's notification-only behavior is unchanged. Neither a notification nor a receipt proves the model understood the outcome.
+An async compatibility launch sends one window-outcome custom message per single/batch call after actual drain (paused or completed), using public `sendMessage(...,{triggerTurn:true,deliverAs:"followUp"})` to wake the parent. Compatibility resume does the same once for its new execution window; rejected resumes send no completion notification. This may cause a parent model turn and provider charges; no polling or detached worker survives parent shutdown. The original native tool's notification-only behavior is unchanged. Neither a notification nor a receipt proves the model understood the outcome.
 
 The coordinator owns workspace allocation, exclusive writer handoff, Git/PR publication and retirement under the active workflow. Supply a complete task and accessible skill/reference paths: general inherits available skills and restricted reviewed leaf capabilities as specified below; workers never inherit parent instructions/history or context files. No scripts/workflow engine, supervisor RPC, automatic worktree lifecycle, external CLI worker, retained-run migration or blanket competitor API parity is promised.
 
@@ -158,11 +158,11 @@ A parent waiting in its child-local `delegate_task` retains its permit. Nested b
 
 Deadlines pause rather than cancel. `queued|setup|running → pausing → paused` stops new dispatch, aborts SDK work and waits for actual subtree drain before releasing capacity and writer leases. Snapshots expose `pauseReason` (`deadline` or `ancestor deadline`), `retainedContext`, `window`, cumulative request/tool/spawn counters, and unfinalized structured submission state. Paused is neither success nor failure; no final outcome artifacts are published. A queued assignment can pause before any session/transcript exists.
 
-Root-only `delegate_coordinate` `{action:"resume",target:{id,generation},assignment:"Continue…"}` or `subagent` `{action:"resume",id:"UUID@generation",message:"Continue…"}` appends that message to the retained SDK conversation. UUID, generation, assignment, workspace, selected model/prewalk state, role instructions, all prior SDK messages/tool calls/results and structured submission state remain intact. Each explicit resume starts a fresh configured deadline window (still bounded by originally admitted and current limits). Cumulative requests/tools/spawns are **not** replenished. A pre-session queued pause starts the original assignment followed by the continuation when dispatched. No automatic replay, undo, process freezing, restart or cross-parent recovery is provided.
+Root-only `delegate_coordinate` `{action:"resume",target:{id,generation},assignment:"Continue…"}` or `subagent` `{action:"resume",id:"UUID@generation",message:"Continue…"}` appends that message to the retained SDK conversation. UUID, generation, assignment, workspace, selected model/prewalk state, role instructions, all prior SDK messages/tool calls/results remain intact. A paused window retains its provisional structured submission state. Completed windows retain immutable result/outcome/artifact references in `completedWindows`; their existing files are never replaced. A resumed completed structured assignment requires a new submission (the previous validated value is evidence, not the new window's result). Later completed-window artifacts are published exclusively under `window-N/` inside the same task directory. Each explicit resume starts a fresh configured deadline window (still bounded by originally admitted and current limits). Cumulative requests/tools/spawns are **not** replenished. Each generation permits at most 64 execution windows, bounding completion evidence and notifications. A pre-session queued pause starts the original assignment followed by the continuation when dispatched. After a completed prewalk handoff, resume validates the retained current model and current/admitted lineage grants, not the obsolete admission model; it neither broadens model grants nor rearms prewalk. No automatic replay, undo, process freezing, restart or cross-parent recovery is provided.
 
-An ancestor deadline marks its entire active subtree before draining any member. Resume the exact original parent generation first, then explicitly resume selected children; resuming a parent does not resume descendants. Existing no-permit-lending, writer ancestry and admission rules still apply. Parent completion/stop retires its children, including paused sessions.
+An ancestor deadline marks its entire active subtree before draining any member. Resume the exact original parent generation first, then explicitly resume selected children; resuming a parent does not resume descendants. Existing no-permit-lending, writer ancestry and admission rules still apply. Parent completion retires active/paused children, but preserves successfully completed retained child conversations for later explicit resume once that exact parent generation is running again. Explicit stop/retirement remains effective even across parent resume; failed/cancelled children cannot resume.
 
-Resume rechecks operator/trusted-project limits and grants, ancestor spawn/capability ceilings, model availability/authentication, callable tools/provenance and writer/capacity admission. It never broadens original admission. A revoked retained grant rejects rather than rebuilding the SDK tool/resource graph; restore the grant or stop and launch a newly authorized identity. Policy/auth/capacity failure leaves the paused conversation intact with an actionable tool error; there is no fallback model or replacement agent. Concurrent duplicate resumes reject atomically. Stop/shutdown wins a concurrent pending resume and disposes retained sessions.
+Resume rechecks operator/trusted-project limits and grants, ancestor spawn/capability ceilings, model availability/authentication, callable tools/provenance and writer/capacity admission. It never broadens original admission. A revoked retained grant rejects rather than silently changing the admitted SDK tool/resource graph; restore the grant or stop and launch a newly authorized identity. Policy/auth/capacity/restoration failure leaves the paused or completed conversation intact with an actionable tool error; there is no fallback model or replacement agent. Concurrent duplicate resumes reject atomically. Stop/shutdown wins a concurrent pending resume and disposes retained sessions.
 
 Requests/tools remain hard cancellation guards. The first committed hard-limit reason (`requests` or `tools`) is retained and produces final `status:"cancelled"`, `limitReason`, and explanatory `error`. Stop before setup cancels without SDK setup/transcript. Request guards check **before forwarding** to the parent's public registry. Counts include failed dispatches but not rejected over-limit dispatches, auth preflight or provider-internal retries/subrequests. Tool guards count entered, granted custom-tool executions, including permission-denied forwarded calls; malformed/unknown calls rejected by Pi before execution are not counted. Requests still bound loops of rejected tools.
 
@@ -212,7 +212,7 @@ Operator `coordination` grants selected `message`, `inbox`, `wait` actions; abse
 | `status`              | Root-only pinned `target`; returns `{snapshot,generations,agents}`. Snapshot/history describe assignments; agents describes current presence. Full detached details, bounded text preview.                                                                                                    |
 | `stop`                | Root-only pinned current `target`; closes idle/parked presence or aborts/drains active subtree. Completed outcomes/files are unchanged. Stopped identities cannot revive.                                                                                                                     |
 | `park`                | Root-only current disposed idle target; records parked presence. Active parking rejects: stop active work explicitly. No live SDK session, shell, permit or writer lease is retained while idle or parked.                                                                                    |
-| `resume`              | Root-only drained paused `target` and nonblank `assignment` continuation. Returns the same identity/window snapshot and sends one notification after that resumed window drains. No schema replacement or descendant auto-resume.                                                             |
+| `resume`              | Root-only drained paused or successfully completed `target` and nonblank `assignment` continuation. Returns the same identity/window snapshot and sends one notification after that resumed window drains. No schema replacement or descendant auto-resume.                                   |
 | `followup` / `revive` | Root-only current target and nonblank `assignment`, optional supported `resultSchema`. Followup requires idle; revive requires parked. Returns the new admitted snapshot, not final success. Use wait/status for completion; no unsolicited duplicate generation-completion message is added. |
 
 A message returns `{id,sender,recipient,text,mode,status,error?}`. `accepted` means mailbox admission, `queued` means the public SDK accepted a steer/followUp, `handled` means an SDK input handler consumed it, `delivered` means the exact message entered the recipient transcript or an inbox tool/wait returned it. None means model acknowledgment, understanding or assignment completion. `not-running` means no running recipient (including an undelivered receipt whose recipient ended), and `error` preserves delivery errors. Unknown/foreign/stale identities or receipts reject visibly, not as apparent successful delivery. Inbox messages are not automatically steered; steer/followUp are also retained in the bounded mailbox. Their `delivered` state comes from actual SDK user-message events, not queue acceptance. Message text is literal prefixed data, not tool authority.
@@ -227,7 +227,7 @@ Followup/revive re-resolve operator/trusted-project policy and selected root mod
 
 The UUID stays stable and generation increments atomically **only after** synchronous admission checks. Concurrent renewals race on the original reference; exactly one can replace it. A newly owned generation directory `<id>-g<N>` holds its SDK session, `agent/`, transcript and exclusive artifacts. Generation 1 keeps `<id>/`. For these completed-agent fresh generations, no old files are opened for continuation, consulted, replayed, appended or migrated. The new prompt contains only the new explicit assignment plus current role/resources and identity; provide any relevant prior conclusions explicitly. This deliberately avoids retained-conversation replay/tool execution and does not claim a warm resumed Pi session.
 
-Descendant renewal requires its **exact original** `parentId+parentGeneration` still active, non-cancelling and authorized. Current ancestor spawn roles, depth/limits, remaining spawn count, immediate nested capacity and writer ancestry all revalidate before generation mutation/setup. Replaced/disposed/stopped ancestors reject; the caller must delegate a new identity through an authorized live parent, never reparent the old one. Parent completion/stop closes descendant idle/parked presence too. Old callbacks, steering, stops, submissions, message delivery and waits capture the originating entry/reference, never retarget by latest UUID. Wait outcomes remain pinned even if a later generation is admitted. Shutdown/reload closes all presence and waiters, drains actual resources and suppresses old-runtime final messages; no cross-parent/process revival exists.
+Descendant renewal requires its **exact original** `parentId+parentGeneration` still active, non-cancelling and authorized. Current ancestor spawn roles, depth/limits, remaining spawn count, immediate nested capacity and writer ancestry all revalidate before generation mutation/setup. Replaced/disposed/stopped ancestors reject; the caller must delegate a new identity through an authorized live parent, never reparent the old one. Explicit parent stop closes descendant idle/parked presence too. Successful parent completion does not retire already-successful retained descendant conversations; their explicit resume still requires the exact original active parent generation. Old callbacks, steering, stops, submissions, message delivery and waits capture the originating entry/reference, never retarget by latest UUID. Wait outcomes remain pinned even if a later generation is admitted. Shutdown/reload closes all presence and waiters, drains actual resources and suppresses old-runtime final messages; no cross-parent/process revival exists.
 
 ## Writer coordination and unsupported shell boundary
 
@@ -256,7 +256,7 @@ Hub names are snapshot-derived assignment headlines plus role, not a naming regi
 | Outcome wait                                                                                                      | Hub `w` → native event wait with explicit 1000ms bound; native tool supports 1–60000ms outcome/inbox/receipt waits with existing deadlock/refusal rules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | Stop subtree                                                                                                      | Hub `x` → pinned target → `y` confirmation → existing stop/drain, retaining capacity/writer until disposal. Queued/setup/running/paused UI targets supported; historical/pausing/draining/disposed UI targets refuse, including transitions during pinned input. `/subagent-stop` and native root stop retain existing semantics.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Park                                                                                                              | Hub `p` or native root tool; only disposed idle current identity with valid original parent. No warm SDK retained.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| Followup/revive                                                                                                   | **Native model-issued `delegate_coordinate` or compatibility `subagent` resume**. Paused assignments continue the retained conversation; idle/parked assignments use fresh session/generation/current narrowed authority. Both require the exact active original parent for descendants. Hub command context lacks `tools/executeTool`: it cannot safely start a generation; f/r only explain refusal, allocate nothing and dispatch nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Followup/revive                                                                                                   | **Native model-issued `delegate_coordinate` followup/revive only**. Idle/parked assignments use fresh session/generation/current narrowed authority. `subagent` resume continues paused or successfully completed conversations with full restored context and unchanged identity/generation/session count. Both require the exact active original parent for descendants. Hub command context lacks `tools/executeTool`: it cannot safely start a generation; f/r only explain refusal, allocate nothing and dispatch nothing.                                                                                                                                                                                                                                                                                                                                                                 |
 | Child coordination/spawn/model authority                                                                          | Coordination/model authority remains operator default-off; spawn defaults to scout/review only. All remain project/request/ancestor subset-only; the UI cannot mint grants or impersonate a child.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | Manual !/!!, external editors/terminals, arbitrary extension JS                                                   | Uncoordinated; model-tool-only writer boundary, never a shell ban/wrapper/sandbox.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | Supplied workspace / production isolation                                                                         | Explicit path/shell-cwd adaptation through root hooks is supported for existing supplied workspaces. Filesystem sandboxing, managed worktrees, copying/apply and cleanup remain unimplemented; cwd is not a resource grant.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

package/docs/verification.md

@@ -28,7 +28,7 @@ Startup guidance, examples and compatibility tests describe native Pi delegation
 
 The approved follow-up adds startup `subagent` discovery/guidance, common launch/control calls, supplied-workspace execution and native completion wake-ups. It does not import another extension or promise full API/configuration parity. Source/test manifest digest: `41d44bc852b2c6b60a61112232992a704d13a0e590abd5ac152a5f7b8f5d470c`.
 
-**Controlled SDK/CLI integration:** the default suite passes 145/145 with zero failures, cancellations or skips. Typecheck, SDK exercise, 19-file package dry run and diff checks pass. The actual isolated Pi CLI exposes `subagent` at ordinary startup without an enable call and completes two scouts without activating extra builtins. Real SDK children read/edit/write/run bash in a throwaway Git worktree containing spaces and an apostrophe; root hooks see the actual adapted arguments and retain their real parent cwd. Tests cover root tool/write refusal, failed-cd no-fallback behavior, global writer queue/parent-write exclusion, atomic invalid-cwd admission, search defaults/shorthand refusal, parent-policy retention, task-file cwd, explicitly granted nested workspace inheritance, exact model selection, idle-parent wake once, fresh-generation resume/workspace retention and stale-control refusal. The first focused attempt used obsolete edit arguments and allowed the controlled parent to replay worker steps; the fixture now uses the current `edits[]` schema and acknowledges parent results. No assertions, runner concurrency or timeouts were weakened.
+**Controlled SDK/CLI integration:** the default suite passes 145/145 with zero failures, cancellations or skips. Typecheck, SDK exercise, 19-file package dry run and diff checks pass. The actual isolated Pi CLI exposes `subagent` at ordinary startup without an enable call and completes two scouts without activating extra builtins. Real SDK children read/edit/write/run bash in a throwaway Git worktree containing spaces and an apostrophe; root hooks see the actual adapted arguments and retain their real parent cwd. Tests cover root tool/write refusal, failed-cd no-fallback behavior, global writer queue/parent-write exclusion, atomic invalid-cwd admission, search defaults/shorthand refusal, parent-policy retention, task-file cwd, explicitly granted nested workspace inheritance, exact model selection, idle-parent wake once, completed-agent context restoration without fresh generations/sessions, paused resume identity/context retention and stale-control refusal. The first focused attempt used obsolete edit arguments and allowed the controlled parent to replay worker steps; the fixture now uses the current `edits[]` schema and acknowledges parent results. No assertions, runner concurrency or timeouts were weakened.
 
 **Unrun:** live-model automatic tool selection and complete multi-task delivery with disposable remote PR/stack creation. This run authorized neither live inference nor a separate smoke repository's external writes. Controlled SDK/CLI results do not prove a model automatically chooses the extension or follows a complete external workflow. No installed-package cutover, active-session reload, retained-run migration or new human visual acceptance was performed. Replacement use requires only one loaded `subagent` provider; Pi's first-registration behavior is not a provider-priority mechanism.
 
@@ -428,3 +428,7 @@ The new redacted ANSI and cursor-separated text captures are retained outside th
 Reviewed only this task's changes before final checks. Removed redundant shutdown waits/nested cleanup scaffolding by letting the existing cancellation method own the startup barrier, preserving `finally` disposal. Kept one child, one observable snapshot and one observer subscription; no scheduler, generalized verifier, recovery service or duplicate terminal renderer. Removed an arbitrary finite scripted-response queue in favor of reusing Pi's response factory for each actual request. The final checks cover these changes. For the UI repair, kept rendering stateless (theme recalculated each render), one shared status/activity presentation and native width helpers; no new timers, retained command UI context, scheduler or terminal renderer. The widget subscription is removed before shutdown/disposal so stale children cannot repaint a replacement session.
 
 For Slice 0, the scoped pass retained one native color conversion per render and reused the existing row-paint boundary; no color cache, theme classifier, palette configuration or verifier framework was added. Simplified the real-theme regression's per-row comparison before the final full-suite checks.
+
+### Same-conversation completed resume correction
+
+Real SDK tests in `completed-resume.test.ts` and `compatibility.test.ts` exercise completed idle/parked continuation with original system messages, assistant tool calls and actual tool results, a stable transcript/identity/generation/session count, repeat completions, cumulative exhaustion, immutable earlier artifacts, and per-window structured submissions. Fault-injected unavailable canonical state and revoked policy reject without snapshot/model/event mutation; stop wins pending resume and cancellation drains the writer. Existing deadline-pause/subtree tests continue to exercise retained paused context. Restoration uses the supported `createAgentSession({sessionManager})` API, not direct agent message assignment or result summaries. Parent-lifetime only; no process-restart recovery is claimed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howarewoo/pi-subagents",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Pi-native single-assignment delegation with explicit profiles and parent-owned SDK children",
   "keywords": [
     "pi-package"

package/src/child-execution.ts

@@ -34,6 +34,9 @@ export type ExecutionRecord = {
   timer?: ReturnType<typeof setTimeout>;
   run?: Promise<void>;
   session?: AgentSession;
+  /** Canonical entry tree survives runtime disposal; never substitute a result summary. */
+  sessionManager?: SessionManager;
+  resourcePrompt?: string;
   unsubscribe?: () => void;
   paused?: boolean;
   prompt?: (text: string) => Promise<void>;
@@ -89,11 +92,15 @@ export async function createChildExecution(
         ? entry.state.id
         : `${entry.state.id}-g${entry.state.generation}`,
     );
-    await mkdir(taskDir, { mode: 0o700 }); // exclusive ownership: never reuse an existing task record
+    const restoring = !!entry.sessionManager;
+    if (!restoring) await mkdir(taskDir, { mode: 0o700 }); // exclusive initial ownership
     const agentDir = join(taskDir, "agent");
-    await mkdir(agentDir, { mode: 0o700 });
+    if (!restoring) await mkdir(agentDir, { mode: 0o700 });
     const transcriptDir = join(taskDir, "transcripts");
-    await mkdir(transcriptDir, { mode: 0o700 });
+    if (!restoring) await mkdir(transcriptDir, { mode: 0o700 });
+    // Each completed window publishes exclusively, leaving all earlier artifacts intact.
+    const outcomeDir = restoring ? join(taskDir, `window-${entry.state.window}`) : taskDir;
+    if (restoring) await mkdir(outcomeDir, { mode: 0o700 });
     const target =
       entry.state.prewalk?.status === "armed"
         ? validateModelSelection(input.context, entry.state.prewalk.target)
@@ -116,14 +123,15 @@ export async function createChildExecution(
       target ? [target] : [],
     );
     const resources = childResources(
-      input.profile.prompt +
+      (entry.resourcePrompt ??=
+        input.profile.prompt +
         (target
           ? "\nPrewalk: investigate and plan using only granted context/tools. After the first completed edit or write the same conversation switches once to the explicitly granted implementation target; all normal budgets still apply."
           : "") +
         `\nYour delegation identity is ${entry.state.id} generation ${entry.state.generation}; parent ${entry.state.parentId}. Coordination, if granted, is limited to family identities explicitly supplied to you.` +
         (entry.validator
           ? "\nThis assignment requires a structured result. Call submit_result with the actual value; final prose is not a submission."
-          : ""),
+          : "")),
       input.skills,
     );
     const loader = new DefaultResourceLoader({
@@ -316,9 +324,10 @@ export async function createChildExecution(
         compaction: { enabled: false },
         retry: { enabled: false },
       }),
-      sessionManager: SessionManager.create(selection.cwd, transcriptDir),
+      sessionManager: entry.sessionManager ?? SessionManager.create(selection.cwd, transcriptDir),
     });
     entry.session = session;
+    entry.sessionManager = session.sessionManager;
     if (session.thinkingLevel !== selection.thinkingLevel)
       throw new Error("SDK did not preserve selected effort");
     if (
@@ -389,7 +398,7 @@ export async function createChildExecution(
           const artifacts: NonNullable<ChildSnapshot["artifacts"]> = {};
           try {
             artifacts.text = await saveOutcomeArtifact(
-              taskDir,
+              outcomeDir,
               "result.txt",
               last?.content
                 .filter((block) => block.type === "text")
@@ -398,7 +407,7 @@ export async function createChildExecution(
             );
             if (entry.state.outcome?.validation === "submitted")
               artifacts.structured = await saveOutcomeArtifact(
-                taskDir,
+                outcomeDir,
                 "structured.json",
                 JSON.stringify(entry.state.outcome.value),
               );

package/src/coordinator.ts

@@ -1,6 +1,7 @@
 import { requireSupportedHost } from "./supported-host.ts";
 import { leafDenial, toolProvenance, type CapabilityDenial } from "./capabilities.ts";
 import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
 import {
   SessionManager,
   type AgentSession,
@@ -110,12 +111,14 @@ export class DelegationCoordinator {
       presence: this.presence.get(state.id),
     }));
   }
-  generations(id: string): ChildSnapshot[] {
+  /** Full parent-lifetime session roster, including retained historical generations. */
+  sessions(): ChildSnapshot[] {
     return [...this.history.values()]
-      .map((record) => record.state)
-      .concat(this.list())
-      .filter((state) => state.id === id)
-      .map((state) => structuredClone(state));
+      .map((record) => structuredClone(record.state))
+      .concat(this.list());
+  }
+  generations(id: string): ChildSnapshot[] {
+    return this.sessions().filter((state) => state.id === id);
   }
   private listeners = new Set<(event: RegistryEvent) => void>();
   private parentMutations = new Set<string>();
@@ -224,6 +227,15 @@ export class DelegationCoordinator {
         throw new Error("Prewalk target requires an exact model grant");
       validateModelSelection(selection, input.profile.prewalk);
     }
+    this.validateAdmission(input, effective, input.model);
+    return selection;
+  }
+  /** Shared writer/lineage checks; resume supplies its retained selection, not admission defaults. */
+  private validateAdmission(
+    input: StartTask,
+    effective: ModelSelection,
+    explicit?: ModelSelection,
+  ): void {
     const writer = this.writer ? this.entries.get(this.writer) : undefined;
     if (
       isWriter(input.profile) &&
@@ -234,7 +246,7 @@ export class DelegationCoordinator {
       const parent = this.entry(input.parent);
       if (parent.cancelled || parent.paused || parent.state.disposed)
         throw new Error("Delegating parent is no longer active");
-      this.assertDescendantModels(parent, input.profile, effective, input.model);
+      this.assertDescendantModels(parent, input.profile, effective, explicit);
       if (!parent.input.profile.spawn?.includes(input.profile.name))
         throw new Error("Ancestor spawn role denied");
       if (parent.state.depth >= Math.min(this.policy.depth, parent.state.limits.depth))
@@ -248,7 +260,6 @@ export class DelegationCoordinator {
         ancestor = this.entries.get(ancestor.state.parentId);
       }
     }
-    return selection;
   }
   private assertDescendantModels(
     parent: Entry,
@@ -721,15 +732,56 @@ export class DelegationCoordinator {
   async resume(ref: ChildRef, text: string): Promise<ChildRef> {
     requireSupportedHost();
     const entry = this.entry(ref);
-    if (entry.resuming || entry.state.status !== "paused" || entry.cancelled || this.closing)
-      throw new Error("Resume requires a drained paused assignment; duplicate resume rejected");
+    const completed = entry.state.status === "settled" && entry.state.disposed;
+    const eligible = entry.state.status === "paused" || completed;
+    if (
+      entry.resuming ||
+      !eligible ||
+      entry.cancelled ||
+      this.closing ||
+      this.presence.get(ref.id) === "stopped"
+    )
+      throw new Error(
+        "Resume requires a drained paused or completed conversation; stopped/failed identities and duplicate resume rejected",
+      );
+    if ((entry.state.window ?? 1) >= MAX_GENERATIONS)
+      throw new Error("Resume window limit (64) reached");
+    if (
+      completed &&
+      (!entry.sessionManager ||
+        !entry.finalizedMessages?.length ||
+        JSON.stringify(entry.sessionManager.buildSessionContext().messages) !==
+          JSON.stringify(entry.finalizedMessages))
+    )
+      throw new Error("Resume unavailable: canonical conversation state was not retained");
+    if (completed) {
+      // SessionManager.open() can silently initialize missing/empty files. Never use that
+      // fallback here: the retained tree AND its original persisted transcript must agree.
+      try {
+        const persisted = readFileSync(entry.state.transcript!, "utf8")
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line));
+        const manager = entry.sessionManager!;
+        if (
+          JSON.stringify(persisted) !==
+          JSON.stringify([manager.getHeader(), ...manager.getEntries()])
+        )
+          throw new Error("transcript differs from retained canonical entries");
+      } catch (error) {
+        throw new Error(
+          `Resume unavailable: original transcript cannot be restored: ${String(error)}`,
+        );
+      }
+    } else if (entry.prompted && !entry.session) {
+      throw new Error("Resume unavailable: paused SDK conversation was not retained");
+    }
     if (!text.trim()) throw new Error("Nonempty continuation text is required");
     entry.resuming = true;
     try {
       const parent = this.renewalParent(ref);
       const input = entry.input;
       const policy = await resolveScheduling(input.context.cwd, input.context.isProjectTrusted());
-      this.configure(policy);
       const limits = { ...entry.state.limits };
       for (const key of Object.keys(limits) as (keyof ExecutionLimits)[])
         limits[key] = Math.min(
@@ -810,21 +862,52 @@ export class DelegationCoordinator {
         throw new Error("Resume denied: delegation depth limit");
       // Reuse the original admission's writer and nested no-lending checks, without
       // admitting another task or charging another spawn.
-      this.validate(input);
+      this.validateAdmission(
+        input,
+        selected,
+        entry.state.prewalk?.status === "armed" ? undefined : selected,
+      );
       this.renewalParent(ref);
       const available =
         this.active().length < policy.concurrency &&
         (!isWriter(input.profile) || (!this.writer && !this.parentMutations.size));
       if (parent && (this.queue.size || !available))
         throw new Error("Nested capacity unavailable; no permit lending");
-      this.assertQueueCapacity([input]);
+      const previousPolicy = this.policy;
+      this.policy = policy;
+      try {
+        this.assertQueueCapacity([input]);
+      } finally {
+        this.policy = previousPolicy;
+      }
       if (
         entry.cancelled ||
         this.closing ||
-        entry.state.disposed ||
-        entry.state.status !== "paused"
+        this.presence.get(ref.id) === "stopped" ||
+        (completed ? entry.state.status !== "settled" : entry.state.status !== "paused")
       )
         throw new Error("Resume cancelled by stop or shutdown");
+      if (completed) {
+        const { window, status, result, outcome, artifacts, error, endedAt } = entry.state;
+        entry.state = {
+          ...entry.state,
+          completedWindows: [
+            ...(entry.state.completedWindows ?? []),
+            structuredClone({ window, status, result, outcome, artifacts, error, endedAt }),
+          ],
+          disposed: false,
+          endedAt: null,
+          outcome: entry.validator
+            ? { validation: "awaiting", attempts: 0, errors: [], finalized: false }
+            : undefined,
+          artifacts: undefined,
+          result: "",
+          progress: "",
+        };
+        entry.selection.model = validateModelSelection(input.context, selected);
+        entry.selection.thinkingLevel = selected.effort;
+      }
+      this.policy = policy;
       entry.done = new Promise<void>((resolve) => {
         entry.finish = resolve;
       });
@@ -989,24 +1072,27 @@ export class DelegationCoordinator {
       dispose: () => this.dispose(entry),
     });
   }
-  private closeDescendantPresence(entry: Entry): void {
+  private closeDescendantPresence(entry: Entry, completed = false): void {
     for (const child of this.entries.values())
       if (
         child.state.parentId === entry.state.id &&
         child.state.parentGeneration === entry.state.generation
       ) {
-        this.presence.set(child.state.id, "stopped");
-        this.closeDescendantPresence(child);
+        // Ancestor completion closes live/paused descendants, but does not retire a
+        // successful retained conversation. Explicit stop remains sticky.
+        if (!(completed && child.state.disposed && child.state.status === "settled"))
+          this.presence.set(child.state.id, "stopped");
+        this.closeDescendantPresence(child, completed);
       }
   }
   private dispose(entry: Entry): void {
     if (entry.state.disposed) return;
     this.queue.delete(entry);
     clearTimeout(entry.timer);
-    entry.finalizedMessages = structuredClone(entry.session?.messages ?? []);
+    if (entry.session) entry.finalizedMessages = structuredClone(entry.session.messages);
     entry.unsubscribe?.();
     entry.session?.dispose();
-    // Retain immutable evidence, not the disposed SDK session graph, while idle/parked.
+    // Retain the authoritative SessionManager and immutable evidence, not the SDK runtime graph.
     entry.unsubscribe = undefined;
     entry.session = undefined;
     entry.prompt = undefined;
@@ -1015,11 +1101,14 @@ export class DelegationCoordinator {
     entry.run = undefined;
     entry.pauseDrain = undefined;
     if (this.writer === entry.state.id) this.writer = undefined;
-    this.closeDescendantPresence(entry);
+    this.closeDescendantPresence(
+      entry,
+      entry.state.status === "settled" && !entry.cancelled && !this.closing,
+    );
     this.presence.set(entry.state.id, entry.cancelled || this.closing ? "stopped" : "idle");
     this.update(entry, {
       disposed: true,
-      retainedContext: false,
+      retainedContext: !!entry.sessionManager && entry.state.status === "settled",
       endedAt: Date.now(),
       writerLease: false,
       outcome: entry.state.outcome ? { ...entry.state.outcome, finalized: true } : undefined,

package/src/delegation-types.ts

@@ -42,6 +42,13 @@ export type ChildSnapshot = Readonly<
     pauseReason?: string;
     retainedContext?: boolean;
     window?: number;
+    /** Immutable completion evidence from earlier windows of this same conversation. */
+    completedWindows?: ReadonlyArray<
+      Pick<
+        ChildSnapshot,
+        "window" | "status" | "result" | "outcome" | "artifacts" | "error" | "endedAt"
+      >
+    >;
     status:
       | "queued"
       | "setup"

package/src/hub.ts

@@ -85,8 +85,7 @@ export function createHub(
   const roster = () =>
     taskTree(
       coordinator
-        .list()
-        .flatMap((child) => coordinator.generations(child.id))
+        .sessions()
         .filter((child) =>
           lineText(
             [
@@ -208,7 +207,7 @@ export function createHub(
           paint(
             interactionTarget
               ? "Resize · Esc cancels"
-              : "Subagent Hub " + coordinator.list().length,
+              : "Subagent Hub " + coordinator.sessions().length,
           ),
         ];
       const inner = Math.max(0, width - 4);

package/src/pi-extended-subagents.ts

@@ -107,7 +107,7 @@ export default function delegation(pi: ExtensionAPI) {
       (tui, theme) => {
         renderWidget = () => tui.requestRender();
         return createChildWidget(
-          () => coordinator.list(),
+          () => coordinator.sessions(),
           theme,
           () => tui.terminal.rows,
         );
@@ -373,7 +373,7 @@ export default function delegation(pi: ExtensionAPI) {
     label: "Coordinate delegation",
     exposure: "model-only",
     description:
-      "Live-parent identity-pinned coordination. message targets a running family agent (omit target for root inbox, direct children only); inbox reads own bounded mailbox; wait targets an outcome or own inbox with required 1–60000ms timeout, retaining capacity. No transcript access. Child actions require explicit operator grants. Root additionally has status/stop/park, paused resume (assignment is the appended continuation), and idle followup/parked revive. Resume retains identity and full context, resets only the deadline window, and requires explicit child resumes after parent resume. Followup/revive create a fresh generation/session with current model/auth and narrowed current grants, no old tool replay or historical recovery. Message accepted/queued is NOT model acknowledgment; delivered means transcript/inbox visibility only. 4096-byte messages, 64 mailbox/waiters, 512 messages and 64 generations per live parent.",
+      "Live-parent identity-pinned coordination. message targets a running family agent (omit target for root inbox, direct children only); inbox reads own bounded mailbox; wait targets an outcome or own inbox with required 1–60000ms timeout, retaining capacity. No transcript access. Child actions require explicit operator grants. Root additionally has status/stop/park, paused/completed resume (assignment is the appended continuation), and idle followup/parked revive. Resume retains identity and full context, resets only the deadline window, and requires explicit child resumes after parent resume. Followup/revive create a fresh generation/session with current model/auth and narrowed current grants, no old tool replay or historical recovery. Message accepted/queued is NOT model acknowledgment; delivered means transcript/inbox visibility only. 4096-byte messages, 64 mailbox/waiters, 512 messages and 64 generations per live parent.",
     parameters: coordinationParameters,
     async execute(callerId, args, signal, _update, ctx) {
       if (["resume", "followup", "revive"].includes(args.action)) requireSupportedHost();
@@ -493,10 +493,10 @@ export default function delegation(pi: ExtensionAPI) {
     promptGuidelines: [
       "Use subagent for native worker delegation requested by the user or an active workflow; no extension-specific user instruction or enable call is needed. Use agent worker for implementation, scout for research, review for review, or general for restricted inherited capabilities.",
       "Pass subagent the approved task handoff and existing workspace cwd. Preserve selected model routing; no model override is needed to inherit the parent. Pass accessible skill/reference paths in the task; general inherits available skills and callable builtins, plus operator-reviewed leaf tools only; parent instructions/history and project trust are not inherited.",
-      "subagent launches are async by default and wake this session after actual drain. Continue independent work or yield; do not poll or sleep. Use the exact returned id (UUID@generation) for status, steer, stop or resume. Resume continues a paused conversation with its full context and cumulative budgets; completed idle/parked work starts a fresh generation.",
+      "subagent launches are async by default and wake this session after actual drain. Continue independent work or yield; do not poll or sleep. Use the exact returned id (UUID@generation) for status, steer, stop or resume. Resume continues a drained paused or completed conversation with its same identity/generation, full SDK context and cumulative budgets; unavailable context and stopped/failed identities reject. Use explicit delegate_coordinate followup/revive for fresh completed work.",
     ],
     description:
-      "Native delegation for orchestration and coding task owners. Launch {agent,task,cwd?,model?,async?} or an ordered {tasks:[...],async?,cwd?} batch. worker maps explicitly to the implementation profile; unknown/custom agent names reject. Model strings require exact provider/id[:effort] and operator grants. Actions: agents, list, status/stop with exact returned id, steer/resume with id and message. Uses the same registry, parent permissions, limits and global writer lease as delegate_task. Existing workspaces only: file paths and shell cwd are explicitly adapted through root builtin hooks. No automatic worktree creation/commits/apply/deletion, detached survival, script workflows or blanket competing API parity. Do not load another provider of the subagent tool alongside this extension.",
+      "Native delegation for orchestration and coding task owners. Launch {agent,task,cwd?,model?,async?} or an ordered {tasks:[...],async?,cwd?} batch. worker maps explicitly to the implementation profile; unknown/custom agent names reject. Model strings require exact provider/id[:effort] and operator grants. Actions: agents, list, status/stop with exact returned id, steer/resume with id and message. Resume requires a drained paused or completed session and restores its full conversation with the same identity/generation and session count; unavailable context and stopped/failed identities reject. Uses the same registry, parent permissions, limits and global writer lease as delegate_task. Existing workspaces only: file paths and shell cwd are explicitly adapted through root builtin hooks. No automatic worktree creation/commits/apply/deletion, detached survival, script workflows or blanket competing API parity. Do not load another provider of the subagent tool alongside this extension.",
     parameters: compatibleParameters,
     async execute(callerId, args, signal, onUpdate, ctx) {
       if (!("action" in args) || args.action === "resume" || args.action === "steer")
@@ -564,20 +564,10 @@ export default function delegation(pi: ExtensionAPI) {
       if (args.action === "stop") await owner.stop(target);
       else if (args.action === "steer") await owner.steer(target, args.message);
       else if ("message" in args) {
-        const presence = owner
-          .agents()
-          .find(
-            (state) => state.id === target.id && state.generation === target.generation,
-          )?.presence;
         const response = await coordinationTool(undefined, undefined, true).execute(
           callerId,
           {
-            action:
-              owner.snapshot(target)?.status === "paused"
-                ? "resume"
-                : presence === "parked"
-                  ? "revive"
-                  : "followup",
+            action: "resume",
             target,
             assignment: args.message,
           },
@@ -586,10 +576,6 @@ export default function delegation(pi: ExtensionAPI) {
           ctx,
         );
         const next = response.details as ChildSnapshot;
-        if (next.generation !== target.generation)
-          void owner.wait(next).then((state) => {
-            if (!closing && coordinator === owner) show(compatible(state), state.transcript, true);
-          });
         return result(compatible(next));
       }
       return result(compatible(owner.snapshot(target)!));

package/src/subagent-widget.ts

@@ -15,7 +15,7 @@ import {
   taskTree,
 } from "./task-presentation.ts";
 
-/** Event-driven, bounded current-agent tree; history and full metrics remain in the Hub. */
+/** Full session totals with an event-driven, bounded active-agent tree; details remain in the Hub. */
 export function createChildWidget(
   snapshot: () => ChildSnapshot[],
   theme: Pick<Theme, "fg"> & Partial<Pick<Theme, "bold">>,