@henryqw/pi-subagent 22.0.1 → 22.2.0

package/README.md

@@ -21,15 +21,20 @@ 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.
 
 Commands are for you; tools and the packaged skill are for Main. You do not need to call agent tools or manage candidate identities yourself.
 
+In the TUI, the compact widget uses one row per visible agent/task: `D` or `I` marks direct or isolated work, and `[S]` or `[I3]` identifies the Role initial (plus the isolated model class: `1` fast, `2` balanced, `3` frontier, `*` fav). Direct rows show the launched model, thinking level, elapsed time, and measured session tokens (`— tok` until usage is available). Isolated rows show the recorded task state and any retained workspace; their status glyphs use the active TUI theme, while the text still names the status without color. Herdr does not currently provide reliable live model, thinking, or token readings for those rows. Attention appears before ordinary work, with a `+N more` summary when direct rows overflow. A ready isolated candidate is **not promoted** to Main. Use `/subagent` or `subagent_status` for exact identities, failures, and recovery.
+
 | 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. |
@@ -121,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/direct-herdr.d.ts

@@ -8,9 +8,11 @@ export interface DirectHandle {
     sessionFile: string;
     prompt: string;
     answer(maxBytes: number): Promise<string>;
+    usageTokens(): Promise<number | undefined>;
     cancel(): Promise<void>;
 }
 export declare function exactDirectAnswer(jsonl: string, prompt: string, maxBytes?: number): string;
+export declare function directSessionTokens(jsonl: string, prompt: string): number | undefined;
 export type DirectTab = Pick<DirectHandle, "name" | "tabId" | "paneId" | "sessionFile">;
 export declare function createDirectHerdr(pi: Pick<ExtensionAPI, "exec">, cwd: string, idleMs: number): {
     start(launch: ResolvedRoleLaunch, name: string, label: string, task: string, signal: AbortSignal, onTab: (tab: DirectTab) => void): Promise<DirectHandle>;

package/dist/direct-herdr.js

@@ -70,6 +70,43 @@ export function exactDirectAnswer(jsonl, prompt, maxBytes = ANSWER_LIMIT) {
         throw new Error(`Pi final answer exceeds the ${maxBytes}-byte workflow limit; read the private session file for recovery.`);
     return text;
 }
+// Ignore a partial trailing JSONL entry while the child is writing it.
+export function directSessionTokens(jsonl, prompt) {
+    let active = false;
+    let total = 0;
+    let observed = false;
+    for (const line of jsonl.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            break;
+        }
+        if (entry.type !== "message" || !entry.message || typeof entry.message !== "object")
+            continue;
+        const message = entry.message;
+        if (message.role === "user") {
+            active = Array.isArray(message.content) && message.content.length === 1
+                && message.content[0]?.text === prompt;
+            if (active) {
+                total = 0;
+                observed = false;
+            }
+        }
+        else if (active && message.role === "assistant" && message.usage && typeof message.usage === "object") {
+            const usage = message.usage;
+            const values = [usage.input, usage.output, usage.cacheRead, usage.cacheWrite];
+            if (values.every((value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0)) {
+                total += values.reduce((sum, value) => sum + value, 0);
+                observed = true;
+            }
+        }
+    }
+    return observed ? total : undefined;
+}
 export function createDirectHerdr(pi, cwd, idleMs) {
     if (process.env.HERDR_ENV !== "1")
         throw new Error("Direct delegation requires a Herdr-managed Pi pane (HERDR_ENV=1).");
@@ -131,8 +168,20 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                 const state = inspect(accepted, "agent_prompted", name, paneId, tabId);
                 if (state === "blocked" || state === "unknown")
                     throw new Error(`Herdr agent became ${state}; inspect it before retrying.`);
+                let lastUsageSize = -1;
+                let lastTokens;
                 return {
                     name, tabId, paneId, sessionFile, prompt,
+                    async usageTokens() {
+                        const info = await stat(sessionFile);
+                        if (info.size > SESSION_LIMIT)
+                            return undefined;
+                        if (info.size !== lastUsageSize) {
+                            lastTokens = directSessionTokens(await readFile(sessionFile, "utf8"), prompt);
+                            lastUsageSize = info.size;
+                        }
+                        return lastTokens;
+                    },
                     async answer(maxBytes) {
                         const readAnswer = async () => {
                             const info = await stat(sessionFile);

package/dist/git-runtime.js

@@ -321,10 +321,8 @@ export class CheckedGitRuntime {
         if (!await this.isAncestor(requiredBase, identity.head, worktree.cwd, context)) {
             throw new Error(`Task ${task.id} tip does not descend from its recorded base ${requiredBase}.`);
         }
-        if (requireChange) {
-            const count = Number.parseInt(oneLine(await this.requireGit(["rev-list", "--count", `${requiredBase}..${identity.head}`], worktree.cwd, context), "task commit count"), 10);
-            if (!Number.isSafeInteger(count) || count < 1)
-                throw new Error(`Task ${task.id} has no committed change from its recorded base.`);
+        if (requireChange && identity.head === requiredBase) {
+            throw new Error(`Task ${task.id} has no committed change from its recorded base.`);
         }
         return identity;
     }
@@ -341,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,
@@ -157,7 +157,7 @@ export class RoleLaunchRuntime {
         if (typeof resolvedRoot !== "string" || !isAbsolute(resolvedRoot) || resolvedRoot.includes("\0")) {
             throw new Error("Pi Subagent root resolver must return an absolute canonical path.");
         }
-        const root = normalize(await realpath(resolvedRoot));
+        const root = await realpath(resolvedRoot);
         if (root !== resolvedRoot)
             throw new Error("Pi Subagent root resolver returned a non-canonical path.");
         const rootInfo = await lstat(root);

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;
         }
@@ -189,7 +194,7 @@ export class FileRunStore {
                 throw new Error(`Pi Subagent request ${state.request.id} already exists.`);
             throw error;
         }
-        const saved = parseRunState(structuredClone(state));
+        const saved = JSON.parse(contents);
         this.onStateSaved?.(structuredClone(saved));
         return this.handle(saved, path);
     }
@@ -282,7 +287,7 @@ export class FileRunStore {
         return new RunStateHandle(state, path, async (contents) => {
             await this.assertSafeDestination(state.root, path);
             await writePrivateTextFileAtomically(path, contents);
-            this.onStateSaved?.(parseRunState(JSON.parse(contents)));
+            this.onStateSaved?.(JSON.parse(contents));
         });
     }
 }

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;
 }
 /**