@henryqw/pi-subagent 22.1.0 → 22.2.0

package/README.md

@@ -21,7 +21,9 @@ pi install npm:pi-mcp-adapter
 
 ## Use
 
-![Delegation mode routing and the checked changeset lifecycle through recovery, validation, and promotion](./docs/delegation-routing.svg)
+![Main, its coordinator extension, and a Herdr subagent through checked work, worker failure, and coordinator interruption](./docs/worker-lifecycle.svg)
+
+The coordinator is extension code running in Main's Pi process, not another agent. It persists the request, launches the Herdr subagent, checks its committed work, and reports saved results; Main chooses what to stage and promote. If a worker fails, the coordinator reports attention after the wave settles, not necessarily immediately while siblings work. If Main's Pi process stops, no follow-up is guaranteed: restart and run `/subagent recover` in the canonical repository to classify orphaned interruptions and send Main one recovery report. Main then uses `subagent_status` for exact evidence and deliberate next actions. A stale `running` state does not prove a worker is still active; interrupted or ambiguous actions are never replayed automatically.
 
 Ask Main to delegate a bounded task, such as “Have a scout trace sign-in without editing files.” Main uses `delegate_task`; you receive progress and a result or an actionable failure while Main remains available.
 
@@ -31,7 +33,8 @@ In the TUI, the compact widget uses one row per visible agent/task: `D` or `I` m
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `/subagent` | command | Pick direct or isolated work to inspect; send or edit pending instructions for a locally active isolated changeset. Requires interactive TUI or RPC. |
+| `/subagent` | command | Browse work, launch isolated status inspection in a separate Herdr tab with the `fast` model, or send/edit pending instructions. Requires interactive TUI or RPC; inspection also requires a Herdr-managed pane and a read-only `scout` Role. |
+| `/subagent recover` | command | Classify orphaned isolated work in the current canonical repository and send Main one follow-up with request IDs, blockers, and reported next actions. No UI or Herdr pane required. |
 | `delegate_task` | tool | Start read-only direct work or a durable isolated checked graph. |
 | `subagent_status` | tool | Read durable isolated state and the exact allowed continuation without replaying work. |
 | `subagent_resume` | tool | Perform the reported `retry`, `verify`, or `finalize` continuation; does not replace staging or integration. |
@@ -123,21 +126,23 @@ An isolated request has one durable ID, one goal, and 1–8 typed tasks:
 
 `dependsOn` controls scheduling. `contextFrom` may name completed text tasks and preserves the declared order. Changesets require focused task checks; a graph with changesets requires final checks. A canonical root `package.json` test script is required: the runner adds `pnpm test` to final checks if missing, and Main runs it on the combined integration checkout before promotion. Checks and judgments bind to exact Git identities; candidate drift, Main drift, mutation during validation, ambiguity, or conflicts stop promotion and retain evidence.
 
-`delegate_task` and `subagent_resume` return a durable request ID after its state is saved; productive work continues while Main is free. Pi delivers completion or attention as a follow-up message in the launching session. Use `subagent_status` if delivery is missed or you need current state.
+`delegate_task`, `subagent_resume`, and `subagent_integrate advance` return a durable request ID after the wave is saved; productive work continues while Main is free. Pi sends a follow-up in the launching session whenever a checked worker becomes ready, and again when the wave finishes or needs attention. Use `subagent_status` if delivery is missed or you need current state.
 
-The worker produces a clean committed candidate, then runs focused preliminary checks and optional judgment. The runner records a ready candidate but **does not integrate it automatically**. Main inspects `subagent_status`, selects each exact candidate with `subagent_stage` in an owned integration worktree, and resolves conflicts there. `subagent_integrate` can advance dependent tasks from a staged snapshot, validate the combined tip with full root checks and optional final judgment, and promote it to Main only after exact validation. A definitive failed combined check/review allows one committed correction in the integration checkout followed by another validation. Main must explicitly promote; promotion and cleanup never silently discard retained work.
+The worker produces a committed candidate without tracked or untracked changes, then runs focused preliminary checks and optional judgment. Ignored generated files do not block candidacy, but prevent automatic worktree cleanup; inspect them before deleting retained work. The runner records each ready candidate immediately but **does not integrate it automatically**. Main can inspect `subagent_status` and use `subagent_stage` to select the exact candidate in an owned integration worktree while siblings are still working; conflicts are resolved there. Stage and resolve are available during an active wave, but rejection and revision wait for the wave to settle. `subagent_integrate` can advance dependent tasks from a staged snapshot, validate the combined tip with full root checks and optional final judgment after the wave settles, and promote it to Main only after exact validation. A definitive failed combined check/review allows one committed correction in the integration checkout followed by another validation. Main must explicitly promote; promotion and cleanup never silently discard retained work.
 
-Open `/subagent` without arguments to pick work by label. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout (including requests launched in other sessions). Pick a task to inspect status and recovery in separate notices; retained paths and worker identities remain exact even when the request has many attempts or generations. Refresh or choose completed/history for older work. Invalid state IDs are warned about and preserved. Outside Git or when isolated inventory is unavailable, direct recovery still works. Browsing does not resume work or change resources.
+Open `/subagent` without arguments to pick work by label. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout (including requests launched in other sessions). Pick an isolated request and **Inspect status and recovery** to launch a non-focused Herdr tab with a read-only `scout` Role on the configured `fast` route. Its prompt contains bounded saved status (including retained paths, but not raw launch environment or session transcripts); the analysis stays in that tab and does not queue a Main turn. The tab and session file are recorded for recovery even if launch becomes uncertain. The read-only `subagent_status` tool remains Main's authority for exact identities before any stage or recovery action. If Herdr or the read-only fast route is unavailable, inspection fails without changing the request; Main can use `subagent_status`. Refresh or choose completed/history for older work. Invalid state IDs are warned about and preserved. Outside Git or when isolated inventory is unavailable, direct recovery still works. Browsing does not resume work or change resources.
 
-For a locally active unsealed isolated changeset, choose **Send follow-up instructions** to open a native multiline editor; submission queues the instruction, not a completed revision. Choose **Edit queued instructions** to withdraw *all still-pending* instructions for that selected task before the editor opens. Their full text appears in FIFO order separated by blank lines. Explicit submission queues **one replacement** at the tail. Cancel leaves the withdrawn instructions removed; already-claimed instructions, initial prompts, and automatic corrections cannot be recalled. A worker may seal during editing: failed submission reopens the full submitted text for deliberate editing or copying, never automatically requeues it. Combined text above the single-instruction limit is preserved in the editor but rejected until shortened. Cancelling before withdrawal makes no change. Neither action touches Main's editor or Pi's global Option+Up queue shortcut. No-UI sessions must use the agent tools for inspection and recovery.
+For a locally active unsealed isolated changeset, choose **Send follow-up instructions** to open a native multiline editor; submission queues the instruction, not a completed revision. Choose **Edit queued instructions** to withdraw *all still-pending* instructions for that selected task before the editor opens. Their full text appears in FIFO order separated by blank lines. Explicit submission queues **one replacement** at the tail. Cancel leaves the withdrawn instructions removed; already-claimed instructions, initial prompts, and automatic corrections cannot be recalled. A worker may seal during editing: failed submission reopens the full submitted text for deliberate editing or copying, never automatically requeues it. Combined text above the single-instruction limit is preserved in the editor but rejected until shortened. Cancelling before withdrawal makes no change. Neither action touches Main's editor or Pi's global Option+Up queue shortcut. No-UI sessions can run `/subagent recover` or use agent tools for individual inspection and recovery.
 
 A queued follow-up runs after the current turn settles and must produce a new clean commit that passes preliminary checks again. When no queued revision remains, the checked candidate seals immediately; there is no guaranteed post-completion editing window. Late follow-ups fail visibly.
 
 ### Isolated recovery
 
-Main uses the recovery tools in the interface table above. The following details describe their exact identity and retained-work requirements.
+After a coordinator interruption, run `/subagent recover` once. It acquires the repository productive lease before changing any orphaned `pending` or `running` state, preserves unreadable state files and retained candidates, and reports blockers and existing continuations to Main without replaying prompts, merges, promotion, or cleanup. If another productive run holds the lease, it only reads status and reports the live owner; wait rather than taking over. Repeating the command is safe. Main uses `subagent_status` for exact identities and the recovery tools in the interface table above for deliberate decisions; the command never stages or promotes. Direct Herdr tab recovery remains in `/subagent`.
+
+The following details describe exact identity and retained-work requirements.
 
-Pass the exact `generation`, candidate (`taskId`, `attempt`, `candidate`) and `expectedTip` identities reported by status to stage; pass the generation and combined `expectedTip` to integrate. If Main advances cleanly before promotion, call `subagent_integrate refresh` with the recorded `expectedMain`, old `expectedTip`, and new clean `newMain`. Main must restage selected immutable candidates into the new generation and rerun combined checks. Dirty or divergent Main blocks refresh. Stale identities fail. At most two integration worktrees may remain unreleased per request; a superseded generation is read-only. To release a superseded *clean* integration checkout, call `subagent_integrate` with `{ id, action: "release", generation, expectedTip }`, using that generation's last staged tip (or integration base when no stage completed). To release a rejected candidate after its worker has terminated and all generations using it are released, pass `{ id, action: "release", generation: <latest generation number, or 1>, taskId, attempt, expectedTip: <candidate tip> }`. Release persists each host/checkout/branch step, verifies ownership and cleanliness (including ignored files), and deletes the branch only if its ref still names the exact tip. Dirty, conflicted, changed, or uncertain resources remain for manual inspection; retry the same release after resolving the obstacle. Released checkouts free a retained slot; abort is available after every retained resource is released. Rejection can invalidate dependent work; if fresh dependent execution is impossible, start a new request instead of forcing promotion. Productive requests have no whole-run wall-clock deadline. Resume does not reset the recorded policy or correction count. Child limits, abort signals, process I/O, status inspection, exact termination, and cleanup retain finite safety bounds.
+Pass the exact `generation`, candidate (`taskId`, `attempt`, `candidate`) and `expectedTip` identities reported by status to stage; pass the generation and combined `expectedTip` to integrate. If Main advances cleanly before promotion, call `subagent_integrate refresh` with the recorded `expectedMain`, old `expectedTip`, and new clean `newMain`. Main must restage selected immutable candidates into the new generation and rerun combined checks. Dirty or divergent Main blocks refresh. Stale identities fail. If integration allocation was uncertain, `subagent_stage resolve` first proves the owned checkout is still at its base before starting the selected merge; otherwise it retains the intent. At most two integration worktrees may remain unreleased per request; a superseded generation is read-only. To release a superseded *clean* integration checkout, call `subagent_integrate` with `{ id, action: "release", generation, expectedTip }`, using that generation's last staged tip (or integration base when no stage completed). To release a rejected candidate after its worker has terminated and all generations using it are released, pass `{ id, action: "release", generation: <latest generation number, or 1>, taskId, attempt, expectedTip: <candidate tip> }`. Release persists each host/checkout/branch step, verifies ownership and cleanliness (including ignored files), and deletes the branch only if its ref still names the exact tip. Dirty, conflicted, changed, or uncertain resources remain for manual inspection; retry the same release after resolving the obstacle. Released checkouts free a retained slot; abort is available after every retained resource is released. Rejection can invalidate dependent work; if fresh dependent execution is impossible, start a new request instead of forcing promotion. Productive requests have no whole-run wall-clock deadline. Resume does not reset the recorded policy or correction count. Child limits, abort signals, process I/O, status inspection, exact termination, and cleanup retain finite safety bounds.
 
 The extension never pushes, opens a pull request, publishes, deploys, force-cleans recoverable work, or silently falls back to Main.
 

package/dist/git-runtime.js

@@ -339,24 +339,27 @@ export class CheckedGitRuntime {
         return worktree;
     }
     async inspectInFlightWorkspace(cwd, context) {
-        const branch = oneLine(await this.requireGit(["symbolic-ref", "--quiet", "HEAD"], cwd, context), "branch reference");
-        const head = oid(await this.requireGit(["rev-parse", "--verify", "HEAD^{commit}"], cwd, context), "HEAD");
-        const hadGitlinks = await this.hasGitlinks(cwd, context);
-        const inspection = await inspectWorktreeDirty(cwd, this.gitRunner(context));
-        if (inspection.failure)
-            throw new Error(`Worktree inspection failed: ${inspection.failure}`);
-        const index = oid(await this.requireGit(["write-tree"], cwd, context), "index tree");
-        const tree = oid(await this.requireGit(["rev-parse", "--verify", "HEAD^{tree}"], cwd, context), "HEAD tree");
-        const hasGitlinks = hadGitlinks || await this.hasGitlinks(cwd, context);
-        const finalBranch = oneLine(await this.requireGit(["symbolic-ref", "--quiet", "HEAD"], cwd, context), "branch reference");
-        const finalHead = oid(await this.requireGit(["rev-parse", "--verify", "HEAD^{commit}"], cwd, context), "HEAD");
-        if (branch !== finalBranch || head !== finalHead)
-            throw new Error("Git workspace changed during in-flight identity inspection.");
-        return {
-            candidate: { branch, head, index, tree },
-            clean: !inspection.dirty,
-            supported: !hasGitlinks,
-        };
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const branch = oneLine(await this.requireGit(["symbolic-ref", "--quiet", "HEAD"], cwd, context), "branch reference");
+            const head = oid(await this.requireGit(["rev-parse", "--verify", "HEAD^{commit}"], cwd, context), "HEAD");
+            const hadGitlinks = await this.hasGitlinks(cwd, context);
+            const inspection = await inspectWorktreeDirty(cwd, this.gitRunner(context), false);
+            if (inspection.failure)
+                throw new Error(`Worktree inspection failed: ${inspection.failure}`);
+            const index = oid(await this.requireGit(["write-tree"], cwd, context), "index tree");
+            const tree = oid(await this.requireGit(["rev-parse", "--verify", "HEAD^{tree}"], cwd, context), "HEAD tree");
+            const hasGitlinks = hadGitlinks || await this.hasGitlinks(cwd, context);
+            const finalBranch = oneLine(await this.requireGit(["symbolic-ref", "--quiet", "HEAD"], cwd, context), "branch reference");
+            const finalHead = oid(await this.requireGit(["rev-parse", "--verify", "HEAD^{commit}"], cwd, context), "HEAD");
+            if (branch !== finalBranch || head !== finalHead)
+                continue;
+            return {
+                candidate: { branch, head, index, tree },
+                clean: !inspection.dirty,
+                supported: !hasGitlinks,
+            };
+        }
+        throw new Error("Git workspace changed during in-flight identity inspection.");
     }
     async inspectWorkspace(cwd, strictIgnored, context) {
         const branch = oneLine(await this.requireGit(["symbolic-ref", "--quiet", "HEAD"], cwd, context), "branch reference");

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { captureWorkingCheckoutBaseline, captureWorkingCheckoutState, prepareWor
 export declare const PI_SUBAGENT_PROCESS_LEASE = "PI_SUBAGENT_PROCESS_LEASE";
 export declare const ROLE_MCP_POLICY_FLAG = "pi-subagent-role-mcps";
 export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+export declare const EXECUTION_BUDGET_FLAG = "pi-subagent-execution-budget";
 export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "ask_question", "subagent_status", "subagent_resume", "subagent_stage", "subagent_abort"];
 export declare const CHILD_EXCLUDED_TOOLS: string;
 export declare const DELEGATE_TASK: {

package/dist/index.js

@@ -19,6 +19,7 @@ const ROLE_TOOLS_EXTENSION = fileURLToPath(new URL("../extensions/role-tools.ts"
 export const PI_SUBAGENT_PROCESS_LEASE = "PI_SUBAGENT_PROCESS_LEASE";
 export const ROLE_MCP_POLICY_FLAG = "pi-subagent-role-mcps";
 export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+export const EXECUTION_BUDGET_FLAG = "pi-subagent-execution-budget";
 export const CHILD_EXCLUDED_TOOL_NAMES = [
     "delegate_task",
     "ask_question",

package/dist/integration-git.js

@@ -45,10 +45,12 @@ async function sharedHistory(base, tip, cwd, signal) {
 /** Check helper-derived names even after a safely removed checkout is no longer present. */
 async function ownershipMetadata(root, info, signal) {
     const canonical = await realpath(root);
+    const first = (await requireGit(["worktree", "list", "--porcelain", "-z"], root, signal)).split("\0")[0];
+    const primary = first.startsWith("worktree ") ? await realpath(first.slice("worktree ".length)) : "";
     if (await realpath(await requireGit(["rev-parse", "--show-toplevel"], root, signal)) !== canonical
-        || info.repoRoot !== canonical || info.cwd !== info.path
+        || info.repoRoot !== primary || info.cwd !== info.path
         || !/^pi-subagent\/subagent-[0-9a-f]{24}$/.test(info.branch)
-        || info.path !== join(canonical, ".worktrees", basename(info.branch))) {
+        || info.path !== join(primary, ".worktrees", basename(info.branch))) {
         throw new Error("Git worktree is not an exact owned checkout of Main.");
     }
 }

package/dist/launch-runtime.d.ts

@@ -1,5 +1,5 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type EphemeralSubagentExecutionBudget } from "./ephemeral.ts";
+import type { EphemeralSubagentExecutionBudget } from "./ephemeral.ts";
 import type { CoordinatorRuntime, OperationContext, TransientLaunchHandle, VerifiedLaunch } from "./runner.ts";
 import { type ExecuteRequest, type ModelClass, type WorkspaceIdentity } from "./schema.ts";
 export declare const ISOLATED_MODEL_TASK: {

package/dist/launch-runtime.js

@@ -3,8 +3,7 @@ import { constants } from "node:fs";
 import { chmod, lstat, mkdtemp, open, realpath, rmdir, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, normalize, relative, sep } from "node:path";
-import { resolveConfiguredRoleLaunch } from "./index.js";
-import { EXECUTION_BUDGET_ENV } from "./ephemeral.js";
+import { EXECUTION_BUDGET_FLAG, resolveConfiguredRoleLaunch } from "./index.js";
 import { registerModelTask } from "@henryqw/pi-task-models";
 const PROMPT_FLAG = "--append-system-prompt";
 const DIRECTORY_MODE = 0o700;
@@ -138,13 +137,14 @@ export class RoleLaunchRuntime {
                 modelClass,
                 model: `${prepared.model.provider}/${prepared.model.id}`,
                 thinkingLevel: prepared.thinkingLevel,
-                args: Object.freeze([...prepared.args]),
-                env: Object.freeze({
-                    ...prepared.env,
-                    ...(executionBudget === undefined ? {} : {
-                        [EXECUTION_BUDGET_ENV]: JSON.stringify({ ...executionBudget, startedAt: this.now() }),
-                    }),
-                }),
+                args: Object.freeze([
+                    ...prepared.args,
+                    ...(executionBudget === undefined ? [] : [
+                        `--${EXECUTION_BUDGET_FLAG}`,
+                        JSON.stringify({ ...executionBudget, startedAt: this.now() }),
+                    ]),
+                ]),
+                env: Object.freeze({ ...prepared.env }),
                 tools: Object.freeze([...prepared.tools]),
             }),
             prompt: prepared.systemPrompt,

package/dist/runner.d.ts

@@ -303,6 +303,13 @@ export declare class IsolatedRunner {
         }>;
         invalidIds: string[];
     }>;
+    /** Classify orphaned work under the same repository lease as productive execution.
+     * Status remains read-only; Main alone chooses any subsequent action. */
+    recoverRepository(root: string): Promise<{
+        requests: RunResponse[];
+        invalidIds: string[];
+        leaseBusy: boolean;
+    }>;
     canFollowup(root: string, requestId: string, taskId: string): boolean;
     drainFollowups(root: string, requestId: string, taskId: string): string[];
     queueFollowup(root: string, requestId: string, taskId: string, instruction: string): string;

package/dist/runner.js

@@ -2,7 +2,7 @@ import { readFileSync, realpathSync } from "node:fs";
 import { createChildWorktree, finalizeChildWorktree } from "./worktree.js";
 import { IntegrationGit } from "./integration-git.js";
 import { checkBatchPasses, CLEANUP_KINDS, isCleanCommitted, MAX_PERSISTED_RUNTIME_TEXT_BYTES, MAX_POSSIBLE_RESOURCES, parseExecuteRequest, parseIntegrationAction, integrationGenerationPasses, parseResumeRequest, parseStageRequest, reviewEvidencePasses, sameIdentity, RUN_STATE_VERSION, } from "./schema.js";
-import { FileRunStore } from "./store.js";
+import { FileRunStore, ProductiveRunLeaseBusyError } from "./store.js";
 const TRUNCATION_MARKER = "\n[truncated]";
 const TEXT_TASK_PROMPT_MAX_BYTES = 64 * 1024;
 const CHANGESET_TASK_PROMPT_MAX_BYTES = 96 * 1024;
@@ -533,6 +533,39 @@ export class IsolatedRunner {
                 })),
             })) };
     }
+    /** Classify orphaned work under the same repository lease as productive execution.
+     * Status remains read-only; Main alone chooses any subsequent action. */
+    async recoverRepository(root) {
+        root = realpathSync.native(root);
+        let leaseBusy = false;
+        let inventory;
+        try {
+            inventory = await this.withProductiveRun(root, async (lifecycle) => await this.store.withLock(root, async () => {
+                const listed = await this.listRequests(root);
+                for (const request of listed.requests) {
+                    if (request.status !== "pending" && request.status !== "running")
+                        continue;
+                    const handle = await this.store.load(root, request.id);
+                    if (this.recoverInterrupted(handle.state))
+                        await handle.save();
+                }
+                return listed;
+            }, { productiveRunLease: lifecycle.lease }));
+        }
+        catch (error) {
+            if (!(error instanceof ProductiveRunLeaseBusyError))
+                throw error;
+            leaseBusy = true;
+            inventory = await this.listRequests(root);
+        }
+        const requests = [];
+        for (const request of inventory.requests) {
+            if (["pending", "running", "needs_attention", "completed · retained"].includes(request.status)) {
+                requests.push(await this.status(request.id, root));
+            }
+        }
+        return { requests, invalidIds: inventory.invalidIds, leaseBusy };
+    }
     canFollowup(root, requestId, taskId) {
         const active = this.activeControl(realpathSync.native(root), requestId, taskId);
         return active !== undefined && active.task.status === "working" && !active.control.isSealed;
@@ -564,12 +597,13 @@ export class IsolatedRunner {
             if (this.productiveLifecycles.has(root)) {
                 throw new Error("Another Pi Subagent productive request is active in this runner.");
             }
-            const lifecycle = { lease, stopped: false };
+            const lifecycle = { lease, stages: new Set(), stopped: false };
             this.productiveLifecycles.set(root, lifecycle);
             try {
                 return await operation(lifecycle);
             }
             finally {
+                await Promise.allSettled(lifecycle.stages);
                 this.productiveLifecycles.delete(root);
             }
         });
@@ -756,10 +790,11 @@ export class IsolatedRunner {
     async stage(value, root, outerSignal) {
         const action = parseStageRequest(value);
         root = realpathSync.native(root);
-        return await this.withProductiveRun(root, async (lifecycle) => {
-            const handle = await this.store.withLock(root, async () => await this.store.load(root, action.id), { productiveRunLease: lifecycle.lease });
+        const stageSelected = async (handle, duringWave) => {
             const state = handle.state;
-            if (terminal(state) || state.status !== "needs_attention" || (state.integration.refresh && state.integration.refresh.status !== "ready")) {
+            if (terminal(state) || (state.status !== "needs_attention"
+                && !(duringWave && state.status === "running" && (action.action === "stage" || action.action === "resolve")))
+                || (state.integration.refresh && state.integration.refresh.status !== "ready")) {
                 throw new Error("Request is not waiting for Main staging or refresh allocation remains uncertain.");
             }
             const candidate = state.integration.candidates.find((item) => item.taskId === action.taskId && item.attempt === action.attempt
@@ -912,7 +947,7 @@ export class IsolatedRunner {
             }
             if (action.action === "resolve") {
                 const pending = generation?.stages.at(-1);
-                if (!pending || !["staging", "conflict"].includes(pending.status)
+                if (!pending || !["pending", "staging", "conflict"].includes(pending.status)
                     || pending.taskId !== action.taskId || pending.attempt !== action.attempt
                     || !sameIdentity(pending.source, action.candidate)
                     || !sameIdentity(pending.onto, action.expectedTip))
@@ -983,9 +1018,15 @@ export class IsolatedRunner {
                 }
                 await this.saveProductive(handle); // Exact candidate and previous tip before merge.
             }
-            const outcome = await scope.call((context) => action.action === "stage"
+            let outcome = await scope.call((context) => action.action === "stage"
                 ? this.integrationGit.stage(root, worktree, state.main, receipts, worker, candidate.tip, context.signal)
                 : this.integrationGit.reconcileStage(root, worktree, state.main, receipts, worker, candidate.tip, context.signal));
+            if (action.action === "resolve" && stage.status === "pending"
+                && outcome.outcome === "ready" && outcome.value === "not_started") {
+                stage.status = "staging";
+                await this.saveProductive(handle); // Read-only proof before Main's explicit merge request.
+                outcome = await scope.call((context) => this.integrationGit.stage(root, worktree, state.main, receipts, worker, candidate.tip, context.signal));
+            }
             if (outcome.outcome === "ready" && outcome.value !== "not_started") {
                 stage.status = "staged";
                 stage.tip = outcome.value.tip;
@@ -1008,6 +1049,28 @@ export class IsolatedRunner {
             // Unproved outcomes keep the intent; never replay a merge automatically.
             await this.saveProductive(handle);
             return this.response(state);
+        };
+        const active = this.productiveLifecycles.get(root);
+        if (active?.handle?.state.request.id === action.id) {
+            if (active.stopped)
+                throw new DurableRunStopped(active.handle.state);
+            if (action.action !== "stage" && action.action !== "resolve") {
+                throw new Error("Wait for active workers before revising or rejecting a candidate.");
+            }
+            if (active.stages.size)
+                throw new Error("Another stage or resolution is active; retry after it finishes.");
+            const stage = stageSelected(active.handle, true);
+            active.stages.add(stage);
+            try {
+                return await stage;
+            }
+            finally {
+                active.stages.delete(stage);
+            }
+        }
+        return await this.withProductiveRun(root, async (lifecycle) => {
+            const handle = await this.store.withLock(root, async () => await this.store.load(root, action.id), { productiveRunLease: lifecycle.lease });
+            return await stageSelected(handle, false);
         });
     }
     stageReceipts(generation) {
@@ -1581,6 +1644,8 @@ export class IsolatedRunner {
     }
     async run(handle, scope, forceTextTaskId, stagedSnapshot) {
         const state = handle.state;
+        const lifecycle = this.productiveLifecycles.get(state.root);
+        lifecycle.handle = handle;
         let saveOnExit = true;
         state.status = "running";
         state.updatedAt = this.coordinatorRuntime.now();
@@ -1653,6 +1718,10 @@ export class IsolatedRunner {
                 const dispatched = await Promise.allSettled(ready.map(async (task) => {
                     try {
                         await this.dispatchTask(handle, task, scope);
+                        if (task.kind === "changeset" && task.status === "ready_to_integrate") {
+                            this.retainCandidate(state, task);
+                            await this.saveProductive(handle);
+                        }
                     }
                     catch (error) {
                         this.rethrowStopped(error);
@@ -1681,9 +1750,6 @@ export class IsolatedRunner {
                     forceTextTaskId = undefined;
                     continue;
                 }
-                for (const task of ready)
-                    if (task.kind === "changeset")
-                        this.retainCandidate(state, task);
                 wave.status = "needs_attention";
                 state.status = "needs_attention";
                 await this.saveProductive(handle);
@@ -1712,9 +1778,15 @@ export class IsolatedRunner {
         }
         finally {
             this.closeRequestControls(state.root, state.request.id);
-            if (saveOnExit) {
-                state.updatedAt = this.coordinatorRuntime.now();
-                await this.saveProductive(handle);
+            try {
+                if (saveOnExit) {
+                    state.updatedAt = this.coordinatorRuntime.now();
+                    await this.saveProductive(handle);
+                }
+            }
+            finally {
+                if (lifecycle.handle === handle)
+                    delete lifecycle.handle;
             }
         }
     }
@@ -2279,6 +2351,8 @@ export class IsolatedRunner {
             tip: attempt.candidate, checks: attempt.preliminaryChecks,
             ...(request.judgment ? { review: attempt.preliminaryReview } : {}), worker: "retained",
         });
+        state.integration.candidates.sort((a, b) => state.tasks.findIndex((item) => item.taskId === a.taskId)
+            - state.tasks.findIndex((item) => item.taskId === b.taskId));
     }
     async verifyRetainedTask(handle, task, scope) {
         const attempt = latestAttempt(task);

package/dist/store.d.ts

@@ -1,5 +1,8 @@
 import { type RunState } from "./schema.ts";
 declare const productiveRunLeaseBrand: unique symbol;
+export declare class ProductiveRunLeaseBusyError extends Error {
+    constructor();
+}
 export interface ProductiveRunLease {
     readonly [productiveRunLeaseBrand]: true;
 }

package/dist/store.js

@@ -24,6 +24,11 @@ const LIFECYCLE_LOCK_OPTIONS = {
     retries: { forever: true, factor: 1, minTimeout: 25, maxTimeout: 25 },
 };
 const productiveRunLeaseBrand = Symbol("productiveRunLease");
+export class ProductiveRunLeaseBusyError extends Error {
+    constructor() {
+        super("Another Pi Subagent productive request is active in this repository.");
+    }
+}
 function isMissing(error) {
     return Boolean(error && typeof error === "object" && error.code === "ENOENT");
 }
@@ -127,7 +132,7 @@ export class FileRunStore {
         }
         catch (error) {
             if (isLocked(error)) {
-                throw new Error("Another Pi Subagent productive request is active in this repository.");
+                throw new ProductiveRunLeaseBusyError();
             }
             throw error;
         }

package/dist/worktree.d.ts

@@ -47,7 +47,7 @@ export declare function inspectIndexFlags(cwd: string, run?: GitRunner, signal?:
     failure?: string;
 }>;
 /** Proves a worktree has no tracked, untracked, ignored, index-hidden, or nested submodule work. */
-export declare function inspectWorktreeDirty(cwd: string, run?: GitRunner): Promise<WorktreeDirtyInspection>;
+export declare function inspectWorktreeDirty(cwd: string, run?: GitRunner, includeIgnored?: boolean): Promise<WorktreeDirtyInspection>;
 /**
  * Inspects and possibly prunes a child worktree after it finishes. Commit count
  * reads the dedicated branch and refuses to prune when checkout HEAD no longer

package/dist/worktree.js

@@ -170,12 +170,12 @@ export async function inspectIndexFlags(cwd, run = runGit, signal) {
         return { hidden: false, failure: `ls-files exit ${flags.code}: ${flags.stderr.trim().slice(0, 200)}` };
     return { hidden: flags.stdout.split("\0").some((entry) => /^(?:[a-z]|S) /.test(entry)) };
 }
-async function inspectDirty(run, cwd) {
+async function inspectDirty(run, cwd, includeIgnored = true) {
     const refreshed = await run(["update-index", "--really-refresh"], cwd);
     if (refreshed.code !== 0 && refreshed.code !== 1) {
         return { dirty: false, failure: `update-index exit ${refreshed.code}: ${refreshed.stderr.trim().slice(0, 200)}` };
     }
-    const status = await run(["status", "--porcelain", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], cwd);
+    const status = await run(["status", "--porcelain", "--untracked-files=all", ...(includeIgnored ? ["--ignored=matching"] : []), "--ignore-submodules=none"], cwd);
     if (status.code !== 0)
         return { dirty: false, failure: `status exit ${status.code}: ${status.stderr.trim().slice(0, 200)}` };
     if (refreshed.code === 1 || status.stdout.trim())
@@ -188,8 +188,8 @@ async function inspectDirty(run, cwd) {
     return { dirty: false };
 }
 /** Proves a worktree has no tracked, untracked, ignored, index-hidden, or nested submodule work. */
-export async function inspectWorktreeDirty(cwd, run = runGit) {
-    const root = await inspectDirty(run, cwd);
+export async function inspectWorktreeDirty(cwd, run = runGit, includeIgnored = true) {
+    const root = await inspectDirty(run, cwd, includeIgnored);
     if (root.dirty || root.failure)
         return root;
     const modules = await run(["submodule", "status", "--recursive"], cwd);
@@ -204,14 +204,14 @@ export async function inspectWorktreeDirty(cwd, run = runGit) {
         if (!paths.length)
             return { dirty: false, failure: "initialized submodule paths unavailable" };
         for (const path of paths) {
-            const nested = await inspectDirty(run, path);
+            const nested = await inspectDirty(run, path, includeIgnored);
             if (nested.failure)
                 return { dirty: false, failure: `submodule ${path}: ${nested.failure}` };
             if (nested.dirty)
                 return { dirty: true };
         }
     }
-    const rechecked = await inspectDirty(run, cwd);
+    const rechecked = await inspectDirty(run, cwd, includeIgnored);
     return initializedSubmodules ? { ...rechecked, initializedSubmodules } : rechecked;
 }
 /**

package/docs/worker-lifecycle.html

@@ -0,0 +1,92 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Checked subagent lifecycle and coordinator recovery</title>
+<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap" rel="stylesheet">
+<style>
+  * { box-sizing: border-box; } body { margin: 0; padding: 32px; background: #f0eee9; color: #101828; font-family: 'Geist', sans-serif; }
+  main { max-width: 1280px; margin: auto; } h1 { font: 400 28px 'Instrument Serif', serif; margin: 0 0 16px; }
+  svg { display: block; width: 100%; height: auto; }
+</style>
+</head>
+<body><main><h1>Checked subagent lifecycle and coordinator recovery</h1>
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="worker-lifecycle-title worker-lifecycle-desc">
+<title id="worker-lifecycle-title">Checked subagent lifecycle and coordinator recovery</title>
+<desc id="worker-lifecycle-desc">Main delegates to the coordinator extension in its own Pi process. The coordinator saves state and launches a Herdr subagent in an isolated worktree. After the subagent commits, the coordinator verifies and saves a checked candidate; Main explicitly stages and promotes only after combined validation. A worker failure waits for the wave to settle before an attention follow-up. If the coordinator process stops, no follow-up is guaranteed; the last durable state remains for status inspection and deliberate recovery without automatic replay.</desc>
+<defs>
+<style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap');</style>
+<marker id="worker-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
+<marker id="worker-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#1d4ed8"/></marker>
+</defs>
+<rect width="1280" height="720" fill="#f0eee9"/>
+<text x="48" y="60" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1.5">PI SUBAGENT / ONE ISOLATED WORKER</text>
+<text x="48" y="99" fill="#101828" font-family="'Instrument Serif',serif" font-size="28">A worker commits. Main decides what is integrated.</text>
+<text x="48" y="126" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">The coordinator is extension code inside Main's Pi process, not another agent.</text>
+<rect x="64" y="158" width="1138" height="58" rx="8" fill="#e6e4de"/>
+<text x="84" y="181" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">One worker shown; siblings can keep working after this candidate is ready.</text>
+<text x="84" y="200" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">State is persisted by the coordinator. Herdr agent status alone does not prove a clean, checked candidate.</text>
+<!-- Connectors before nodes. Primary rail is the checked path; dashed paths retain uncertainty. -->
+<line x1="234" y1="350" x2="306" y2="350" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<line x1="476" y1="350" x2="548" y2="350" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<line x1="718" y1="350" x2="790" y2="350" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<line x1="960" y1="350" x2="1032" y2="350" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#worker-arrow-accent)"/>
+<path d="M633 405 V434 Q633 442 625 442 H408 Q400 442 400 450 V512" fill="none" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#worker-arrow)"/>
+<line x1="500" y1="546" x2="526" y2="546" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<line x1="875" y1="405" x2="875" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#worker-arrow)"/>
+<line x1="968" y1="546" x2="994" y2="546" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<!-- Transition labels sit above, not on, their strokes. -->
+<g fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" text-anchor="middle">
+<rect x="242" y="324" width="56" height="12" rx="2" fill="#f0eee9"/><text x="270" y="333">START</text>
+<rect x="484" y="324" width="56" height="12" rx="2" fill="#f0eee9"/><text x="512" y="333">LAUNCH</text>
+<rect x="726" y="324" width="56" height="12" rx="2" fill="#f0eee9"/><text x="754" y="333">CHECK</text>
+<rect x="968" y="324" width="56" height="12" rx="2" fill="#f0eee9"/><text x="996" y="333" fill="#1d4ed8">READY</text>
+</g>
+<!-- Five phases, with ownership above each. -->
+<g fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1" text-anchor="middle">
+<text x="149" y="272">MAIN AGENT</text><text x="391" y="272">COORDINATOR</text>
+<text x="633" y="272">HERDR SUBAGENT</text><text x="875" y="272">COORDINATOR</text>
+<text x="1117" y="272">MAIN AGENT</text>
+</g>
+<g fill="#ffffff" stroke="#101828">
+<rect x="64" y="295" width="170" height="110" rx="8"/>
+<rect x="306" y="295" width="170" height="110" rx="8"/>
+<rect x="548" y="295" width="170" height="110" rx="8"/>
+<rect x="790" y="295" width="170" height="110" rx="8" fill="#1d4ed8" fill-opacity="0.08" stroke="#1d4ed8"/>
+<rect x="1032" y="295" width="170" height="110" rx="8"/>
+</g>
+<g fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600" text-anchor="middle">
+<text x="149" y="339">Delegate task</text><text x="391" y="339">Save + launch</text>
+<text x="633" y="339">Implement + commit</text><text x="875" y="339">Check + seal</text>
+<text x="1117" y="339">Stage + promote</text>
+</g>
+<g fill="#4c5665" font-family="'Geist',sans-serif" font-size="11" text-anchor="middle">
+<text x="149" y="370">Bounded request</text><text x="391" y="370">Durable ID + lease</text>
+<text x="633" y="370">Isolated worktree</text><text x="875" y="370">Clean tip + task checks</text>
+<text x="1117" y="370">Combined validation first</text>
+</g>
+<!-- Recovery bands: an incomplete worker and a stopped coordinator are distinct. -->
+<rect x="286" y="468" width="448" height="146" rx="8" fill="#e6e4de"/>
+<rect x="756" y="468" width="446" height="146" rx="8" fill="#e6e4de"/>
+<g fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">
+<text x="310" y="492">WORKER FAILURE</text><text x="778" y="492">COORDINATOR STOPS / ANY PHASE</text>
+</g>
+<g fill="#ffffff" stroke="#4c5665" stroke-dasharray="5,4">
+<rect x="310" y="512" width="190" height="68" rx="8"/>
+<rect x="526" y="512" width="192" height="68" rx="8"/>
+<rect x="778" y="512" width="190" height="68" rx="8"/>
+<rect x="994" y="512" width="190" height="68" rx="8"/>
+</g>
+<g fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600" text-anchor="middle">
+<text x="405" y="540">No checked candidate</text><text x="622" y="540">Wave needs attention</text>
+<text x="873" y="540">No guaranteed message</text><text x="1089" y="540">Inspect saved state</text>
+</g>
+<g fill="#4c5665" font-family="'Geist',sans-serif" font-size="10" text-anchor="middle">
+<text x="405" y="560">Failure retained</text><text x="622" y="560">Follow-up when settled</text>
+<text x="873" y="560">Last write survives</text><text x="1089" y="560">Restart; recover deliberately</text>
+</g>
+<line x1="48" y1="648" x2="1232" y2="648" stroke="#101828" stroke-opacity="0.12"/>
+<text x="48" y="675" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">GUARD</text>
+<text x="128" y="675" fill="#101828" font-family="'Geist',sans-serif" font-size="12">Status reports exact saved evidence; uncertain steps are never replayed automatically.</text>
+<text x="128" y="696" fill="#4c5665" font-family="'Geist',sans-serif" font-size="11">A ready candidate may be staged while siblings run. Promotion still requires full combined validation.</text>
+</svg></main></body></html>

package/docs/worker-lifecycle.svg

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="worker-lifecycle-title worker-lifecycle-desc">
+<title id="worker-lifecycle-title">Checked subagent lifecycle and coordinator recovery</title>
+<desc id="worker-lifecycle-desc">Main delegates to the coordinator extension in its own Pi process. The coordinator saves state and launches a Herdr subagent in an isolated worktree. After the subagent commits, the coordinator verifies and saves a checked candidate; Main explicitly stages and promotes only after combined validation. A worker failure waits for the wave to settle before an attention follow-up. If the coordinator process stops, no follow-up is guaranteed; the last durable state remains for status inspection and deliberate recovery without automatic replay.</desc>
+<defs>
+<style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap');</style>
+<marker id="worker-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
+<marker id="worker-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#1d4ed8"/></marker>
+</defs>
+<rect width="1280" height="720" fill="#f0eee9"/>
+<text x="48" y="60" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1.5">PI SUBAGENT / ONE ISOLATED WORKER</text>
+<text x="48" y="99" fill="#101828" font-family="'Instrument Serif',serif" font-size="28">A worker commits. Main decides what is integrated.</text>
+<text x="48" y="126" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">The coordinator is extension code inside Main's Pi process, not another agent.</text>
+<rect x="64" y="158" width="1138" height="58" rx="8" fill="#e6e4de"/>
+<text x="84" y="181" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">One worker shown; siblings can keep working after this candidate is ready.</text>
+<text x="84" y="200" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">State is persisted by the coordinator. Herdr agent status alone does not prove a clean, checked candidate.</text>
+<!-- Connectors before nodes. Primary rail is the checked path; dashed paths retain uncertainty. -->
+<line x1="234" y1="350" x2="306" y2="350" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<line x1="476" y1="350" x2="548" y2="350" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<line x1="718" y1="350" x2="790" y2="350" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<line x1="960" y1="350" x2="1032" y2="350" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#worker-arrow-accent)"/>
+<path d="M633 405 V434 Q633 442 625 442 H408 Q400 442 400 450 V512" fill="none" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#worker-arrow)"/>
+<line x1="500" y1="546" x2="526" y2="546" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<line x1="875" y1="405" x2="875" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#worker-arrow)"/>
+<line x1="968" y1="546" x2="994" y2="546" stroke="#4c5665" marker-end="url(#worker-arrow)"/>
+<!-- Transition labels sit above, not on, their strokes. -->
+<g fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" text-anchor="middle">
+<rect x="242" y="324" width="56" height="12" rx="2" fill="#f0eee9"/><text x="270" y="333">START</text>
+<rect x="484" y="324" width="56" height="12" rx="2" fill="#f0eee9"/><text x="512" y="333">LAUNCH</text>
+<rect x="726" y="324" width="56" height="12" rx="2" fill="#f0eee9"/><text x="754" y="333">CHECK</text>
+<rect x="968" y="324" width="56" height="12" rx="2" fill="#f0eee9"/><text x="996" y="333" fill="#1d4ed8">READY</text>
+</g>
+<!-- Five phases, with ownership above each. -->
+<g fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1" text-anchor="middle">
+<text x="149" y="272">MAIN AGENT</text><text x="391" y="272">COORDINATOR</text>
+<text x="633" y="272">HERDR SUBAGENT</text><text x="875" y="272">COORDINATOR</text>
+<text x="1117" y="272">MAIN AGENT</text>
+</g>
+<g fill="#ffffff" stroke="#101828">
+<rect x="64" y="295" width="170" height="110" rx="8"/>
+<rect x="306" y="295" width="170" height="110" rx="8"/>
+<rect x="548" y="295" width="170" height="110" rx="8"/>
+<rect x="790" y="295" width="170" height="110" rx="8" fill="#1d4ed8" fill-opacity="0.08" stroke="#1d4ed8"/>
+<rect x="1032" y="295" width="170" height="110" rx="8"/>
+</g>
+<g fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600" text-anchor="middle">
+<text x="149" y="339">Delegate task</text><text x="391" y="339">Save + launch</text>
+<text x="633" y="339">Implement + commit</text><text x="875" y="339">Check + seal</text>
+<text x="1117" y="339">Stage + promote</text>
+</g>
+<g fill="#4c5665" font-family="'Geist',sans-serif" font-size="11" text-anchor="middle">
+<text x="149" y="370">Bounded request</text><text x="391" y="370">Durable ID + lease</text>
+<text x="633" y="370">Isolated worktree</text><text x="875" y="370">Clean tip + task checks</text>
+<text x="1117" y="370">Combined validation first</text>
+</g>
+<!-- Recovery bands: an incomplete worker and a stopped coordinator are distinct. -->
+<rect x="286" y="468" width="448" height="146" rx="8" fill="#e6e4de"/>
+<rect x="756" y="468" width="446" height="146" rx="8" fill="#e6e4de"/>
+<g fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">
+<text x="310" y="492">WORKER FAILURE</text><text x="778" y="492">COORDINATOR STOPS / ANY PHASE</text>
+</g>
+<g fill="#ffffff" stroke="#4c5665" stroke-dasharray="5,4">
+<rect x="310" y="512" width="190" height="68" rx="8"/>
+<rect x="526" y="512" width="192" height="68" rx="8"/>
+<rect x="778" y="512" width="190" height="68" rx="8"/>
+<rect x="994" y="512" width="190" height="68" rx="8"/>
+</g>
+<g fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600" text-anchor="middle">
+<text x="405" y="540">No checked candidate</text><text x="622" y="540">Wave needs attention</text>
+<text x="873" y="540">No guaranteed message</text><text x="1089" y="540">Inspect saved state</text>
+</g>
+<g fill="#4c5665" font-family="'Geist',sans-serif" font-size="10" text-anchor="middle">
+<text x="405" y="560">Failure retained</text><text x="622" y="560">Follow-up when settled</text>
+<text x="873" y="560">Last write survives</text><text x="1089" y="560">Restart; recover deliberately</text>
+</g>
+<line x1="48" y1="648" x2="1232" y2="648" stroke="#101828" stroke-opacity="0.12"/>
+<text x="48" y="675" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">GUARD</text>
+<text x="128" y="675" fill="#101828" font-family="'Geist',sans-serif" font-size="12">Status reports exact saved evidence; uncertain steps are never replayed automatically.</text>
+<text x="128" y="696" fill="#4c5665" font-family="'Geist',sans-serif" font-size="11">A ready candidate may be staged while siblings run. Promotion still requires full combined validation.</text>
+</svg>

package/extensions/isolated.ts

@@ -400,6 +400,7 @@ function toolResult(response: RunResponse, ctx: ExtensionContext, rowsByRequest:
 export interface IsolatedSurface {
 	execute(params: unknown, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof toolResult>>;
 	inventory(cwd: string): Promise<IsolatedInventory>;
+	recover(cwd: string): Promise<string>;
 	inspect(root: string, requestId: string): Promise<readonly string[]>;
 	canFollowup(root: string, requestId: string, taskId: string): boolean;
 	enqueue(root: string, requestId: string, taskId: string, text: string, current: () => boolean): string;
@@ -417,7 +418,7 @@ export interface RegisterIsolatedOptions {
 export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIsolatedOptions): IsolatedSurface {
 	if (process.argv.includes(`--${ROLE_TOOL_POLICY_FLAG}`)) {
 		const denied = (): never => { throw new Error("Child Roles cannot access isolated delegation."); };
-		return { execute: async () => denied(), inventory: async () => denied(), inspect: async () => denied(), canFollowup: denied, enqueue: denied, drain: denied };
+		return { execute: async () => denied(), inventory: async () => denied(), recover: async () => denied(), inspect: async () => denied(), canFollowup: denied, enqueue: denied, drain: denied };
 	}
 	const componentsFactory = options.componentsFactory ?? createIsolatedComponents;
 	let latestCtx: ExtensionContext | undefined;
@@ -498,8 +499,11 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		const controller = new AbortController();
 		activeJobs.add(controller);
 		jobOwners.set(key, canDeliver);
+		const notified = new Set<string>();
+		let candidateListener: ((state: RunState) => void) | undefined;
 		const finish = () => {
 			activeJobs.delete(controller);
+			if (candidateListener) stateListeners.delete(candidateListener);
 			if (jobOwners.get(key) === canDeliver) jobOwners.delete(key);
 		};
 		const abortBeforeAck = () => controller.abort(signal?.reason);
@@ -514,6 +518,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			if (state.root !== root || state.request.id !== id) return;
 			latestState = state;
 			if (!acknowledged(state)) return;
+			for (const candidate of state.integration.candidates) notified.add(`${candidate.taskId}\0${candidate.attempt}\0${candidate.tip.head}`);
 			stateListeners.delete(listener);
 			removeTurnAbort();
 			accept(state);
@@ -539,6 +544,17 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 				if (ctx.hasUI) ctx.ui.notify(`Pi Subagent ${id} result delivery failed; use subagent_status to recover.`, "error");
 			}
 		};
+		candidateListener = (state) => {
+			if (state.root !== root || state.request.id !== id || state.status !== "running" || !canDeliver()) return;
+			latestState = state;
+			for (const candidate of state.integration.candidates) {
+				const identity = `${candidate.taskId}\0${candidate.attempt}\0${candidate.tip.head}`;
+				if (candidate.decision || notified.has(identity)) continue;
+				notified.add(identity);
+				deliver(`Pi Subagent ${id}: ${candidate.taskId} ready to integrate. Inspect the exact candidate with subagent_status and stage it now; other workers may still be running.`);
+			}
+		};
+		stateListeners.add(candidateListener);
 		void Promise.resolve().then(() => start(controller.signal)).then(
 			(response) => {
 				finish();
@@ -614,6 +630,12 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
 			const root = await lookupRoot(ctx.cwd, signal);
+			if (params.action === "advance") {
+				return await startInSession(params.id, root, signal, ctx,
+					(state) => state.status === "running" && state.waves.at(-1)?.status === "dispatching"
+						&& sameIdentity(state.waves.at(-1)!.base, params.expectedTip),
+					(runSignal) => getComponents().runner.integrate(params, root, runSignal));
+			}
 			return toolResult(await getComponents().runner.integrate(params, root, signal), ctx, workspaceRowsByRequest);
 		},
 	});
@@ -634,6 +656,47 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			const root = await lookupRoot(cwd);
 			return { root, ...await getComponents().runner.listRequests(root) };
 		},
+		async recover(cwd) {
+			const root = await lookupRoot(cwd);
+			const { requests, invalidIds, leaseBusy } = await getComponents().runner.recoverRepository(root);
+			const lines = [
+				`Pi Subagent recovery in ${root}: ${leaseBusy ? "productive lease is live; no state changed" : "orphaned interruptions classified; no work replayed"}.`,
+				...(requests.length ? requests.map((response) => {
+					const state = response.state;
+					const blockers = state.tasks.flatMap((task) => [
+						...(task.failure ? [`${task.taskId}: ${boundedPublicText(task.failure)}`] : []),
+						...(task.kind === "changeset" && task.attempts.some((attempt) => attempt.prompts.some((prompt) => prompt.status === "ambiguous"))
+							? [`${task.taskId}: ambiguous worker prompt; do not replay`] : []),
+					]);
+					const generation = state.integration.generations.at(-1);
+					const readyCandidates = state.integration.candidates.filter((candidate) => candidate.worker === "retained" && !candidate.decision);
+					return [
+						`${state.request.id}: ${state.status}; Main ${response.main?.status ?? "not checked"}.`,
+						...blockers.map((blocker) => `  Blocker: ${blocker}`),
+						...(state.final.failure ? [`  Final blocker: ${boundedPublicText(state.final.failure)}`] : []),
+						...(generation?.failure ? [`  Integration blocker: ${boundedPublicText(generation.failure)}`] : []),
+						...(state.status !== "completed" && readyCandidates.length ? [`  ${readyCandidates.length} retained candidate(s); Main selects exact candidates with subagent_stage after subagent_status.`] : []),
+						...(state.status === "completed" ? ["  Retained resources after completion; inspect subagent_status for guarded cleanup."] : []),
+						...(generation ? [`  Generation ${generation.number}: ${generation.status}; inspect subagent_status before any subagent_integrate action.`] : []),
+						...(!leaseBusy && response.continuation ? [`  Reported next action: subagent_resume ${JSON.stringify(response.continuation)}.`] : []),
+					].join("\n");
+			}) : ["No unfinished or retained isolated requests."]),
+			...(invalidIds.length ? [`Unreadable state IDs (preserved; inspect with their compatible owner): ${invalidIds.map((id) => JSON.stringify(id)).join(", ")}.`] : []),
+			leaseBusy ? "Wait for the active productive run; use subagent_status to inspect its current state. No work was taken over."
+				: "Main: inspect subagent_status for exact identities and blockers before deciding stage, promote, resume, or guarded release. No worker prompt, merge, promotion, or cleanup was replayed.",
+			];
+			const report: string[] = [];
+			let bytes = 0;
+			let omitted = 0;
+			for (const line of lines.flatMap((entry) => entry.split("\n"))) {
+				const size = Buffer.byteLength(`${line}\n`, "utf8");
+				if (bytes + size > 7_900) { omitted++; continue; }
+				report.push(line);
+				bytes += size;
+			}
+			if (omitted) report.push(`[${omitted} recovery report lines omitted; use subagent_status for exact request evidence.]`);
+			return report.join("\n");
+		},
 		async inspect(root, requestId) {
 			const response = await getComponents().runner.status(requestId, root);
 			return inspectionNotices(response);

package/extensions/role-tools.ts

@@ -3,6 +3,7 @@ import { isAbsolute } from "node:path";
 import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	CHILD_EXCLUDED_TOOL_NAMES,
+	EXECUTION_BUDGET_FLAG,
 	EXECUTION_BUDGET_ENV,
 	PI_SUBAGENT_PROCESS_LEASE,
 	ROLE_TOOL_POLICY_FLAG,
@@ -47,8 +48,9 @@ function configuredTools(value: unknown): string[] {
 	return [...new Set(parsed.map((name) => name.trim()))];
 }
 
-function executionBudget(value: string | undefined): EphemeralSubagentExecutionBudget | undefined {
+function executionBudget(value: string | boolean | undefined): EphemeralSubagentExecutionBudget | undefined {
 	if (value === undefined) return;
+	if (typeof value !== "string") throw new Error(`${EXECUTION_BUDGET_ENV} must be a JSON execution budget.`);
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(value);
@@ -104,7 +106,11 @@ export default function roleTools(pi: ExtensionAPI): void {
 		description: "Internal Pi Subagent Role tool policy",
 		type: "string",
 	});
-	const budget = executionBudget(process.env[EXECUTION_BUDGET_ENV]);
+	pi.registerFlag(EXECUTION_BUDGET_FLAG, {
+		description: "Internal Pi Subagent execution budget",
+		type: "string",
+	});
+	const budget = executionBudget(pi.getFlag(EXECUTION_BUDGET_FLAG) ?? process.env[EXECUTION_BUDGET_ENV]);
 	let handoffSent = false;
 	pi.on("session_start", () => {
 		const selected = configuredTools(pi.getFlag(ROLE_TOOL_POLICY_FLAG));

package/extensions/subagent-command.ts

@@ -31,7 +31,8 @@ export interface IsolatedInventory {
 export interface SubagentCommandAdapter {
 	direct(ctx: ExtensionContext): readonly DirectTask[];
 	isolated(cwd: string): Promise<IsolatedInventory>;
-	inspect(root: string, requestId: string): Promise<readonly string[]>;
+	recover(cwd: string): Promise<string>;
+	inspectInTab(root: string, requestId: string, ctx: ExtensionContext, current: () => boolean): Promise<{ tabId: string; name: string; sessionFile: string }>;
 	canFollowup(root: string, requestId: string, taskId: string): boolean;
 	enqueue(root: string, requestId: string, taskId: string, text: string, current: () => boolean): string;
 	drain(root: string, requestId: string, taskId: string, current: () => boolean): readonly string[];
@@ -55,10 +56,11 @@ async function choose<T>(ctx: ExtensionContext, title: string, items: readonly P
 
 export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentCommandAdapter): void {
 	pi.registerCommand("subagent", {
-		description: "Inspect direct and isolated work; send or edit pending isolated instructions",
+		description: "Inspect direct and isolated work, or recover orphaned isolated requests with /subagent recover",
 		handler: async (args, ctx) => {
-			if (args.trim()) throw new Error("Usage: /subagent (no arguments)");
-			if (!ctx.hasUI) throw new Error("/subagent requires interactive UI (TUI or RPC); use the subagent agent tools in non-interactive mode.");
+			const command = args.trim();
+			if (command && command !== "recover") throw new Error("Usage: /subagent [recover]");
+			if (!command && !ctx.hasUI) throw new Error("/subagent requires interactive UI (TUI or RPC); use the subagent agent tools in non-interactive mode.");
 			const manager = ctx.sessionManager;
 			const session = manager.getSessionId();
 			const file = manager.getSessionFile();
@@ -73,6 +75,13 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				return now.length >= branch.length && branch.every((id, index) => now[index]?.id === id)
 					&& now.slice(branch.length).every((entry) => !existing.has(entry.id));
 			};
+			if (command === "recover") {
+				const report = await adapter.recover(ctx.cwd);
+				if (!current()) return;
+				pi.sendMessage({ customType: "pi-subagent-recovery", content: report, display: true },
+					{ triggerTurn: true, deliverAs: "followUp" });
+				return;
+			}
 			const valid = () => {
 				if (current()) return true;
 				ctx.ui.notify("Session or branch changed; reopen /subagent in the current context.", "warning");
@@ -130,8 +139,8 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 					if (action === "back") break;
 					if (action === "inspect") {
 						try {
-							const notices = await adapter.inspect(root, request.id);
-							if (valid()) for (const notice of notices) ctx.ui.notify(notice, "info");
+							const tab = await adapter.inspectInTab(root, request.id, ctx, current);
+							if (valid()) ctx.ui.notify(`Status inspection started in Herdr tab ${tab.tabId} · agent ${tab.name} · session ${tab.sessionFile}.`, "info");
 						}
 						catch (error) { if (valid()) ctx.ui.notify(`Inspection failed: ${errorText(error)}`, "error"); }
 						continue;

package/extensions/subagent.ts

@@ -228,7 +228,51 @@ export default function subagentExtension(
 			return [...grouped.values()];
 		},
 		isolated: (cwd) => isolatedSurface.inventory(cwd),
-		inspect: (root, id) => isolatedSurface.inspect(root, id),
+		recover: (cwd) => isolatedSurface.recover(cwd),
+		async inspectInTab(root, id, ctx, current) {
+			const notices = await isolatedSurface.inspect(root, id);
+			if (!current()) throw new Error("Session or branch changed before status inspection.");
+			const snapshot = notices.join("\n");
+			if (Buffer.byteLength(snapshot, "utf8") > 32_000) throw new Error("Status exceeds the 32 KiB inspection limit; use subagent_status for exact evidence.");
+			const role = loadRoles().find((candidate) => candidate.name === "scout");
+			if (!role || roleCanWrite(role)) throw new Error("Status inspection requires a configured read-only scout Role.");
+			const prepared = prepareRoleLaunch(pi, ctx, { role, task: DELEGATE_TASK, modelClass: "fast" });
+			const herdr = createDirectHerdr(pi, ctx.cwd, currentPolicy().childIdleMs);
+			const controller = new AbortController();
+			const taskId = `inspect-${id}-${randomUUID()}`;
+			const handles: DirectHandle[] = [];
+			const tabs: DirectTabRecord[] = [];
+			let resolveSettled!: () => void;
+			const settled = new Promise<void>((resolve) => { resolveSettled = resolve; });
+			directTasks.set(taskId, { controller, settled, handles, tabs });
+			try {
+				const transient = await materializeTransientLaunch({ launch: prepared, prompt: prepared.systemPrompt,
+					promptArgIndex: prepared.promptArgIndex }, controller.signal);
+				let handle: DirectHandle;
+				try {
+					handle = await herdr.start(
+						{ ...prepared, args: [...transient.launch.args] }, `i-${randomUUID().replaceAll("-", "").slice(0, 24)}`,
+						`Inspect ${id}`, `Analyze this saved, read-only status snapshot for request ${id}. Summarize blockers and safe next decisions; do not infer missing evidence or mutate resources. The subagent_status tool in Main remains authoritative for exact action identities.\n\n${snapshot}`,
+						controller.signal, (tab) => {
+							const record = { taskId, entryId: id, ...tab };
+							pi.appendEntry(DIRECT_TAB_TYPE, record);
+							tabs.push(record);
+						});
+				} catch (error) {
+					throw new Error(`${error instanceof Error ? error.message : String(error)}. Inspection Role prompt retained at ${transient.launch.args[prepared.promptArgIndex + 1]} after uncertain start.`, { cause: error });
+				}
+				handles.push(handle);
+				await transient.cleanup();
+				if (!current() || controller.signal.aborted) {
+					await handle.cancel();
+					throw new Error(`Session changed during inspection launch; inspect Herdr tab ${handle.tabId}.`);
+				}
+				return { tabId: handle.tabId, name: handle.name, sessionFile: handle.sessionFile };
+			} finally {
+				directTasks.delete(taskId);
+				resolveSettled();
+			}
+		},
 		canFollowup: (root, id, task) => isolatedSurface.canFollowup(root, id, task),
 		enqueue: (root, id, task, text, current) => isolatedSurface.enqueue(root, id, task, text, current),
 		drain: (root, id, task, current) => isolatedSurface.drain(root, id, task, current),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "22.1.0",
+  "version": "22.2.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",

package/skills/pi-subagent/SKILL.md

@@ -26,10 +26,10 @@ Use one compact `role`/`name`/`task` packet, `tasks` for independent packets, or
 
 Give the request a unique ID and goal. Give each task a unique ID, kind, Role, model class, bounded requirements, deliverable, `dependsOn`, and `contextFrom`. Changesets require focused task checks, and a graph containing changesets requires final checks. The root must have a `package.json` test script; `pnpm test` is added to final checks if missing and runs against the combined tip before Main promotion. Text context may name only completed text tasks and preserves declared order.
 
-Every changeset advances automatically after preliminary checks pass. While a locally owned changeset task is actively working, the user may open `/subagent` to queue bounded same-worker revisions or withdraw all still-pending instructions into the native editor and submit one replacement. Cancellation after withdrawal leaves the originals removed; already-claimed instructions cannot be recalled. Each revision must produce a new clean commit and rerun preliminary checks. When no queued revision remains, the runner seals and durably records the exact ready candidate without waiting for input. There is no guaranteed post-completion editing window, and late follow-ups fail visibly.
+Every changeset advances automatically after preliminary checks pass. While a locally owned changeset task is actively working, the user may open `/subagent` to queue bounded same-worker revisions or withdraw all still-pending instructions into the native editor and submit one replacement. Cancellation after withdrawal leaves the originals removed; already-claimed instructions cannot be recalled. Each revision must produce a new clean commit and rerun preliminary checks. When no queued revision remains, the runner seals and durably records the exact ready candidate without waiting for sibling workers. There is no guaranteed post-completion editing window, and late follow-ups fail visibly.
 
-A ready candidate does not integrate automatically. Inspect `subagent_status` and use `subagent_stage` with the exact `generation`, `taskId`, `attempt`, candidate `tip`, and `expectedTip` to select and merge candidates into the owned integration checkout in explicit order. Resolve conflicts there and verify with `resolve`; never edit Main to resolve them. For dependents, `subagent_integrate advance` runs ready tasks against the exact staged snapshot. When selected work is staged, use `subagent_integrate validate` on the exact `combinedTip` for full root checks and optional final judgment; `promote` requires passing evidence and unchanged Main. One Main-authored committed correction to a definitively failed combined validation can be recorded with `correct`, then revalidated. Only proven promotion triggers selected-worker termination and verified cleanup. Failures, ambiguity, conflicts, interruption, child-limit exhaustion, or Main drift retain work and never waive checks or identity guards. The extension never pushes, opens a pull request, publishes, or deploys.
+A ready candidate does not integrate automatically. Each checked worker triggers a follow-up while its siblings continue; inspect `subagent_status` and immediately use `subagent_stage` with the exact `generation`, `taskId`, `attempt`, candidate `tip`, and `expectedTip` to select and merge it into the owned integration checkout. Stage and resolve are available during the active wave; wait for the wave to settle before rejecting or revising. Resolve conflicts in the integration checkout and verify with `resolve`; never edit Main to resolve them. For dependents, `subagent_integrate advance` acknowledges a durable background wave, then reports checked candidates as they finish. When selected work is staged and the wave settles, use `subagent_integrate validate` on the exact `combinedTip` for full root checks and optional final judgment; `promote` requires passing evidence and unchanged Main. One Main-authored committed correction to a definitively failed combined validation can be recorded with `correct`, then revalidated. Only proven promotion triggers selected-worker termination and verified cleanup. Failures, ambiguity, conflicts, interruption, child-limit exhaustion, or Main drift retain work and never waive checks or identity guards. The extension never pushes, opens a pull request, publishes, or deploys.
 
-Use `subagent_status` to inspect durable state without mutation, including candidate identities, generations, and retained resources. `subagent_resume` handles only the reported retry/verify/finalize continuation; it cannot replace Main's stage/integrate decisions or reset policy/corrections. `subagent_stage reject` or `revise` freezes a generation containing the candidate and invalidates dependent attempts; restage chosen work in a new generation. If Main advances cleanly before promotion, use `subagent_integrate refresh` with exact old/new Main and combined-tip identities; restage immutable candidates into the new generation and rerun combined validation. Dirty or divergent Main blocks refresh. At most two unreleased integration worktrees may coexist. Rejected candidates and superseded generations remain retained until Main explicitly calls `subagent_integrate release` with the exact generation and tip; for a rejected worker include its task ID and attempt after releasing all generations using it. Dirty/conflicted or unproved resources block release without force deletion. Impossible fresh dependent work after rejection needs a new request. `subagent_abort` cannot discard retained candidates or integration generations; it may finish once all are released. Old v4 state is rejected (current state is v5), not migrated. Status, abort, process I/O, termination, and verified post-promotion cleanup keep finite safety budgets.
+After a coordinator interruption in the canonical repository, ask the user to run `/subagent recover` once: it acquires the productive lease, classifies orphaned interruptions, preserves invalid files and retained work, and sends Main one follow-up with blockers and next actions. A live productive lease is read-only and cannot be taken over. Recovery never replays prompts, merges, promotion, or cleanup. Use `subagent_status` to inspect exact durable state without mutation, including candidate identities, generations, and retained resources. `subagent_resume` handles only the reported retry/verify/finalize continuation; it cannot replace Main's stage/integrate decisions or reset policy/corrections. `subagent_stage reject` or `revise` freezes a generation containing the candidate and invalidates dependent attempts; restage chosen work in a new generation. If Main advances cleanly before promotion, use `subagent_integrate refresh` with exact old/new Main and combined-tip identities; restage immutable candidates into the new generation and rerun combined validation. Dirty or divergent Main blocks refresh. At most two unreleased integration worktrees may coexist. Rejected candidates and superseded generations remain retained until Main explicitly calls `subagent_integrate release` with the exact generation and tip; for a rejected worker include its task ID and attempt after releasing all generations using it. Dirty/conflicted or unproved resources block release without force deletion. Impossible fresh dependent work after rejection needs a new request. `subagent_abort` cannot discard retained candidates or integration generations; it may finish once all are released. Old v4 state is rejected (current state is v5), not migrated. Status, abort, process I/O, termination, and verified post-promotion cleanup keep finite safety budgets.
 
 All launches use the global policy in `config/pi-subagent/config.json`: productive concurrency, per-child turns/tokens, and idle timeout. Ephemeral children also have a hard runtime limit; isolated requests have a correction cap. Productive requests have no whole-run wall-clock deadline. Request fields cannot replenish or override limits.

package/docs/delegation-routing.html

@@ -1,89 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Delegation routing and checked task lifecycle</title>
-<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap" rel="stylesheet">
-<style>
-  * { box-sizing: border-box; } body { margin: 0; padding: 32px; background: #f0eee9; color: #101828; font-family: 'Geist', sans-serif; }
-  main { max-width: 1280px; margin: auto; } h1 { font: 400 28px 'Instrument Serif', serif; margin: 0 0 16px; }
-  svg { display: block; width: 100%; height: auto; }
-</style>
-</head>
-<body><main><h1>Delegation routing and checked task lifecycle</h1>
-<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="delegation-routing-title delegation-routing-desc">
-<title id="delegation-routing-title">Delegation routing and checked task lifecycle</title>
-<desc id="delegation-routing-desc">A read-only Role runs direct in the current workspace; implementation uses an isolated checked graph. In that graph workers produce a checked candidate, Main stages and validates the combined tip, then explicitly promotes it. Interruptions retain work for recovery and revalidation.</desc>
-<defs>
-<marker id="routing-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
-<marker id="routing-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#1d4ed8"/></marker>
-<marker id="routing-arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
-</defs>
-<rect width="1280" height="720" fill="#f0eee9"/>
-<text x="48" y="60" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1.5">PI SUBAGENT / ROUTING + LIFECYCLE</text>
-<text x="48" y="99" fill="#101828" font-family="'Instrument Serif',serif" font-size="28">One explicit mode; only checked work can be promoted</text>
-<text x="48" y="126" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Direct work returns an observed result. Isolated changesets yield a candidate that Main must validate and promote.</text>
-<!-- Routes and transitions are drawn before nodes. -->
-<line x1="224" y1="212" x2="248" y2="212" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<path d="M336 268 V296 Q336 304 328 304 H192 Q184 304 184 312 V352" fill="none" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<path d="M424 212 H488 Q496 212 496 220 V352" fill="none" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#routing-arrow-accent)"/>
-<line x1="560" y1="400" x2="624" y2="400" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<line x1="784" y1="400" x2="848" y2="400" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<line x1="1008" y1="400" x2="1072" y2="400" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#routing-arrow-accent)"/>
-<!-- Interruption / re-entry paths use separate attach points. -->
-<line x1="448" y1="448" x2="448" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="512" y1="512" x2="512" y2="448" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="896" y1="448" x2="896" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="960" y1="512" x2="960" y2="448" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<!-- Arrow labels have an 8px gap to their strokes. -->
-<g fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" text-anchor="middle">
-<rect x="256" y="284" width="48" height="12" rx="2" fill="#f0eee9"/><text x="280" y="293">YES</text>
-<rect x="432" y="192" width="72" height="12" rx="2" fill="#f0eee9"/><text x="468" y="201" fill="#1d4ed8">NO / GRAPH</text>
-<rect x="568" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="592" y="389">CHECK</text>
-<rect x="792" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="816" y="389">STAGE</text>
-<rect x="1016" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="1040" y="389" fill="#1d4ed8">VERIFY</text>
-<rect x="384" y="472" width="56" height="12" rx="2" fill="#f0eee9"/><text x="412" y="481">PAUSE</text>
-<rect x="520" y="472" width="56" height="12" rx="2" fill="#f0eee9"/><text x="548" y="481">RESUME</text>
-<rect x="816" y="472" width="72" height="12" rx="2" fill="#f0eee9"/><text x="852" y="481">MAIN DRIFT</text>
-<rect x="968" y="472" width="72" height="12" rx="2" fill="#f0eee9"/><text x="1004" y="481">RECHECK</text>
-</g>
-<!-- Mode selection. -->
-<rect x="80" y="180" width="144" height="64" rx="24" fill="#ffffff" stroke="#101828"/>
-<text x="152" y="217" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Delegate task</text>
-<polygon points="336,156 424,212 336,268 248,212" fill="#ffffff" stroke="#101828"/>
-<text x="336" y="208" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Direct</text>
-<text x="336" y="226" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">eligible?</text>
-<!-- Direct is intentionally a single terminal branch: no worktree or candidate. -->
-<text x="80" y="336" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">DIRECT</text>
-<rect x="80" y="352" width="208" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="184" y="384" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Herdr tabs</text>
-<text x="184" y="406" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Current workspace</text>
-<text x="184" y="428" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Observe result</text>
-<text x="80" y="477" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Single · parallel · chain</text>
-<!-- Isolated changeset rail. -->
-<text x="400" y="336" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">ISOLATED / CHECKED CHANGESET</text>
-<rect x="400" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="480" y="387" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Saved + working</text>
-<text x="480" y="411" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Durable ID</text>
-<text x="480" y="429" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Owned worktree</text>
-<rect x="624" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="704" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Ready candidate</text>
-<text x="704" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Clean commit + checks</text>
-<rect x="848" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="928" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Staged by Main</text>
-<text x="928" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Exact candidate tip</text>
-<rect x="1072" y="352" width="160" height="96" rx="8" fill="#1d4ed8" fill-opacity="0.08" stroke="#1d4ed8"/>
-<text x="1152" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Promoted by Main</text>
-<text x="1152" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">After combined checks</text>
-<!-- Recovery states do not erase or bypass exact checks. -->
-<text x="400" y="497" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">WAIT / RECOVERY</text>
-<rect x="400" y="512" width="160" height="72" rx="8" fill="#e6e4de" stroke="#4c5665" stroke-dasharray="5,4"/>
-<text x="480" y="541" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Needs attention</text>
-<text x="480" y="562" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Status / retry</text>
-<rect x="848" y="512" width="160" height="72" rx="8" fill="#e6e4de" stroke="#4c5665" stroke-dasharray="5,4"/>
-<text x="928" y="541" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Revalidate</text>
-<text x="928" y="562" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Restage if needed</text>
-<line x1="48" y1="648" x2="1232" y2="648" stroke="#101828" stroke-opacity="0.12"/>
-<text x="48" y="674" fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">GUARD</text>
-<text x="128" y="674" fill="#101828" font-family="'Geist',sans-serif" font-size="12">No fallback between modes. Failed validation retains evidence; abort requires no retained work.</text>
-</svg></main></body></html>

package/docs/delegation-routing.svg

@@ -1,78 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="delegation-routing-title delegation-routing-desc">
-<title id="delegation-routing-title">Delegation routing and checked task lifecycle</title>
-<desc id="delegation-routing-desc">A read-only Role runs direct in the current workspace; implementation uses an isolated checked graph. In that graph workers produce a checked candidate, Main stages and validates the combined tip, then explicitly promotes it. Interruptions retain work for recovery and revalidation.</desc>
-<defs>
-<style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap');</style>
-<marker id="routing-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
-<marker id="routing-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#1d4ed8"/></marker>
-<marker id="routing-arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
-</defs>
-<rect width="1280" height="720" fill="#f0eee9"/>
-<text x="48" y="60" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1.5">PI SUBAGENT / ROUTING + LIFECYCLE</text>
-<text x="48" y="99" fill="#101828" font-family="'Instrument Serif',serif" font-size="28">One explicit mode; only checked work can be promoted</text>
-<text x="48" y="126" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Direct work returns an observed result. Isolated changesets yield a candidate that Main must validate and promote.</text>
-<!-- Routes and transitions are drawn before nodes. -->
-<line x1="224" y1="212" x2="248" y2="212" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<path d="M336 268 V296 Q336 304 328 304 H192 Q184 304 184 312 V352" fill="none" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<path d="M424 212 H488 Q496 212 496 220 V352" fill="none" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#routing-arrow-accent)"/>
-<line x1="560" y1="400" x2="624" y2="400" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<line x1="784" y1="400" x2="848" y2="400" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<line x1="1008" y1="400" x2="1072" y2="400" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#routing-arrow-accent)"/>
-<!-- Interruption / re-entry paths use separate attach points. -->
-<line x1="448" y1="448" x2="448" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="512" y1="512" x2="512" y2="448" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="896" y1="448" x2="896" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="960" y1="512" x2="960" y2="448" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<!-- Arrow labels have an 8px gap to their strokes. -->
-<g fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" text-anchor="middle">
-<rect x="256" y="284" width="48" height="12" rx="2" fill="#f0eee9"/><text x="280" y="293">YES</text>
-<rect x="432" y="192" width="72" height="12" rx="2" fill="#f0eee9"/><text x="468" y="201" fill="#1d4ed8">NO / GRAPH</text>
-<rect x="568" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="592" y="389">CHECK</text>
-<rect x="792" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="816" y="389">STAGE</text>
-<rect x="1016" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="1040" y="389" fill="#1d4ed8">VERIFY</text>
-<rect x="384" y="472" width="56" height="12" rx="2" fill="#f0eee9"/><text x="412" y="481">PAUSE</text>
-<rect x="520" y="472" width="56" height="12" rx="2" fill="#f0eee9"/><text x="548" y="481">RESUME</text>
-<rect x="816" y="472" width="72" height="12" rx="2" fill="#f0eee9"/><text x="852" y="481">MAIN DRIFT</text>
-<rect x="968" y="472" width="72" height="12" rx="2" fill="#f0eee9"/><text x="1004" y="481">RECHECK</text>
-</g>
-<!-- Mode selection. -->
-<rect x="80" y="180" width="144" height="64" rx="24" fill="#ffffff" stroke="#101828"/>
-<text x="152" y="217" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Delegate task</text>
-<polygon points="336,156 424,212 336,268 248,212" fill="#ffffff" stroke="#101828"/>
-<text x="336" y="208" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Direct</text>
-<text x="336" y="226" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">eligible?</text>
-<!-- Direct is intentionally a single terminal branch: no worktree or candidate. -->
-<text x="80" y="336" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">DIRECT</text>
-<rect x="80" y="352" width="208" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="184" y="384" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Herdr tabs</text>
-<text x="184" y="406" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Current workspace</text>
-<text x="184" y="428" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Observe result</text>
-<text x="80" y="477" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Single · parallel · chain</text>
-<!-- Isolated changeset rail. -->
-<text x="400" y="336" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">ISOLATED / CHECKED CHANGESET</text>
-<rect x="400" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="480" y="387" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Saved + working</text>
-<text x="480" y="411" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Durable ID</text>
-<text x="480" y="429" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Owned worktree</text>
-<rect x="624" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="704" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Ready candidate</text>
-<text x="704" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Clean commit + checks</text>
-<rect x="848" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="928" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Staged by Main</text>
-<text x="928" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Exact candidate tip</text>
-<rect x="1072" y="352" width="160" height="96" rx="8" fill="#1d4ed8" fill-opacity="0.08" stroke="#1d4ed8"/>
-<text x="1152" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Promoted by Main</text>
-<text x="1152" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">After combined checks</text>
-<!-- Recovery states do not erase or bypass exact checks. -->
-<text x="400" y="497" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">WAIT / RECOVERY</text>
-<rect x="400" y="512" width="160" height="72" rx="8" fill="#e6e4de" stroke="#4c5665" stroke-dasharray="5,4"/>
-<text x="480" y="541" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Needs attention</text>
-<text x="480" y="562" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Status / retry</text>
-<rect x="848" y="512" width="160" height="72" rx="8" fill="#e6e4de" stroke="#4c5665" stroke-dasharray="5,4"/>
-<text x="928" y="541" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Revalidate</text>
-<text x="928" y="562" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Restage if needed</text>
-<line x1="48" y1="648" x2="1232" y2="648" stroke="#101828" stroke-opacity="0.12"/>
-<text x="48" y="674" fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">GUARD</text>
-<text x="128" y="674" fill="#101828" font-family="'Geist',sans-serif" font-size="12">No fallback between modes. Failed validation retains evidence; abort requires no retained work.</text>
-</svg>