@henryqw/pi-subagent 27.0.0 → 27.1.1

package/dist/prune.js

@@ -0,0 +1,192 @@
+import { existsSync, realpathSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { createHerdrClient } from "@henryqw/pi-herdr";
+import { runGit } from "./git-process.js";
+import { runProcess } from "./process.js";
+import { inspectWorktreeDirty, OWNED_BRANCH_PATTERN, WORKTREES_DIRNAME } from "./worktree.js";
+const HERDR_TIMEOUT_MS = 30_000;
+const IN_PROGRESS_MARKERS = ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD", "BISECT_LOG", "rebase-merge", "rebase-apply", "sequencer"];
+async function requireGit(run, args, cwd) {
+    const result = await run(args, cwd);
+    if (result.code !== 0)
+        throw new Error(`git ${args[0]} failed (exit ${result.code}): ${result.stderr.trim().slice(0, 200)}`);
+    return result.stdout.trimEnd();
+}
+const within = (directory, path) => path === directory || path.startsWith(`${directory}${sep}`);
+/** Every pane in every Herdr workspace with its shell and foreground working directories. */
+export async function listHerdrPanes(cwd) {
+    const response = await createHerdrClient(runProcess).json(["pane", "list"], { cwd, timeoutMs: HERDR_TIMEOUT_MS });
+    const result = response.result;
+    if (result?.type !== "pane_list" || !Array.isArray(result.panes))
+        throw new Error("Herdr pane list response is malformed.");
+    return result.panes.map((pane) => {
+        const cwds = [pane.cwd, pane.foreground_cwd].filter((cwd) => typeof cwd === "string");
+        if (typeof pane.pane_id !== "string" || !cwds.length)
+            throw new Error("Herdr listed a pane without an ID or working directory.");
+        return { paneId: pane.pane_id, cwds };
+    });
+}
+async function snapshot(root, mainCwd, run) {
+    const checkouts = [];
+    let current;
+    for (const field of (await requireGit(run, ["worktree", "list", "--porcelain", "-z"], root)).split("\0")) {
+        if (field.startsWith("worktree "))
+            checkouts.push(current = { path: field.slice("worktree ".length), locked: false, missing: false });
+        else if (current && field.startsWith("branch refs/heads/"))
+            current.branch = field.slice("branch refs/heads/".length);
+        else if (current && (field === "locked" || field.startsWith("locked ")))
+            current.locked = true;
+        else if (current && (field === "prunable" || field.startsWith("prunable ")))
+            current.missing = true;
+    }
+    if (!checkouts[0])
+        throw new Error("Primary Git worktree is unavailable.");
+    const branches = new Map();
+    for (const line of (await requireGit(run, ["for-each-ref", "--format=%(refname:lstrip=2) %(objectname)", "refs/heads/"], root)).split("\n")) {
+        const [branch, tip] = line.split(" ");
+        if (branch && tip && OWNED_BRANCH_PATTERN.test(branch))
+            branches.set(branch, tip);
+    }
+    const targets = [{ label: "Main HEAD", head: await requireGit(run, ["rev-parse", "--verify", "HEAD^{commit}"], mainCwd) }];
+    const origin = await run(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], root);
+    if (origin.code === 0) {
+        const ref = origin.stdout.trim();
+        targets.push({ label: ref.replace(/^refs\/remotes\//, ""), head: await requireGit(run, ["rev-parse", "--verify", `${ref}^{commit}`], root) });
+    }
+    return { primary: checkouts[0].path, checkouts, branches, targets };
+}
+async function classify(snap, branch, mainCwd, ownership, panes, run, root) {
+    const tip = snap.branches.get(branch);
+    const name = basename(branch);
+    const ownedPath = join(snap.primary, WORKTREES_DIRNAME, name);
+    // A detached or switched owned checkout no longer names the branch; find it by its owned path too.
+    const checkout = snap.checkouts.find((item) => item.branch === branch) ?? snap.checkouts.find((item) => item.path === ownedPath);
+    const blockers = [];
+    if (checkout && checkout.branch !== branch)
+        blockers.push(`owned checkout is ${checkout.branch ? `on branch ${checkout.branch}` : "detached"}; inspect it manually`);
+    let ignored = [];
+    const owner = ownership.owner(name);
+    if (owner)
+        blockers.push(owner);
+    if (ownership.lease)
+        blockers.push(ownership.lease);
+    let merged;
+    for (const target of snap.targets) {
+        const result = await run(["merge-base", "--is-ancestor", tip, target.head], root);
+        if (result.code === 0) {
+            merged = target.label;
+            break;
+        }
+        if (result.code !== 1)
+            throw new Error(`git merge-base failed (exit ${result.code}): ${result.stderr.trim().slice(0, 200)}`);
+    }
+    if (!merged)
+        blockers.push(`branch has commits not in ${snap.targets.map(({ label }) => label).join(" or ")}`);
+    if (checkout) {
+        const path = checkout.path;
+        if (path !== ownedPath)
+            blockers.push("checkout is not at its owned .worktrees path");
+        if (checkout.locked)
+            blockers.push("checkout is locked");
+        if (checkout.missing || !existsSync(path))
+            blockers.push("checkout directory is missing; inspect it, then run git worktree prune");
+        else {
+            const real = realpathSync.native(path);
+            if (within(real, realpathSync.native(mainCwd)))
+                blockers.push("Main runs inside the checkout");
+            const gitDir = await requireGit(run, ["rev-parse", "--absolute-git-dir"], path);
+            const markers = IN_PROGRESS_MARKERS.filter((marker) => existsSync(join(gitDir, marker)));
+            if (markers.length)
+                blockers.push(`Git operation in progress (${markers.join(", ")})`);
+            const dirty = await inspectWorktreeDirty(path, run, false);
+            if (dirty.failure)
+                blockers.push(`checkout could not be inspected: ${dirty.failure}`);
+            else if (dirty.dirty)
+                blockers.push("checkout has tracked or untracked changes");
+            else if (dirty.initializedSubmodules)
+                blockers.push("checkout has initialized submodules; Git cannot remove it without force, so remove it manually");
+            if (typeof panes === "string")
+                blockers.push(`Herdr unavailable (${panes}); cannot prove no pane uses the checkout`);
+            else {
+                const used = panes.filter((pane) => pane.cwds.some((cwd) => within(path, cwd) || within(real, cwd)));
+                if (used.length)
+                    blockers.push(`Herdr pane ${used.map(({ paneId }) => paneId).join(", ")} works inside the checkout`);
+            }
+            ignored = (await requireGit(run, ["status", "--porcelain=v1", "-z", "--ignored=matching", "--untracked-files=normal"], path))
+                .split("\0").filter((entry) => entry.startsWith("!! ")).map((entry) => entry.slice(3));
+        }
+    }
+    return {
+        branch, tip, ...(checkout ? { path: checkout.path } : {}), prunable: !blockers.length, ignored,
+        reason: blockers.length ? blockers.join("; ") : `merged into ${merged}; ${checkout ? "clean checkout" : "no checkout"}`,
+    };
+}
+const existing = (snap) => snap.checkouts.filter((item) => !item.missing && existsSync(item.path)).map(({ path }) => path);
+async function evidence(root, mainCwd, guards, run) {
+    const snap = await snapshot(root, mainCwd, run);
+    const ownership = await guards.ownership(existing(snap));
+    let panes;
+    try {
+        panes = await guards.panes();
+    }
+    catch (error) {
+        panes = (error instanceof Error ? error.message : String(error)).slice(0, 200);
+    }
+    return { snap, ownership, panes };
+}
+/** Read-only review of every pi-subagent worker or integration branch and its checkout. */
+export async function inspectPruneCandidates(root, mainCwd, guards, run = runGit) {
+    const { snap, ownership, panes } = await evidence(root, mainCwd, guards, run);
+    const items = [];
+    for (const branch of [...snap.branches.keys()].sort())
+        items.push(await classify(snap, branch, mainCwd, ownership, panes, run, root));
+    return items;
+}
+async function removeOne(root, mainCwd, reviewed, allowIgnored, guards, run) {
+    const skip = (reason) => ({ outcome: "skipped", item: reviewed, reason });
+    const fail = (reason) => ({ outcome: "failed", item: reviewed, reason });
+    const { snap, ownership, panes } = await evidence(root, mainCwd, guards, run);
+    if (snap.branches.get(reviewed.branch) !== reviewed.tip)
+        return skip("branch was deleted or moved since review");
+    const fresh = await classify(snap, reviewed.branch, mainCwd, ownership, panes, run, root);
+    if (!fresh.prunable)
+        return skip(fresh.reason);
+    if (fresh.path !== reviewed.path)
+        return skip("checkout registration changed since review");
+    if (fresh.ignored.some((entry) => !allowIgnored || !reviewed.ignored.includes(entry)))
+        return skip("ignored content was not approved or changed since review");
+    const stale = () => guards.current !== undefined && !guards.current();
+    if (fresh.path) {
+        if (stale())
+            return skip("session or branch changed before removal; reopen /subagent prune");
+        // Git removes ignored content without --force; the checks above approved it.
+        const removed = await run(["worktree", "remove", fresh.path], root);
+        if (removed.code !== 0)
+            return fail(`git worktree remove failed: ${removed.stderr.trim().slice(0, 200)}`);
+        if (existsSync(fresh.path))
+            return fail("git worktree remove succeeded but the checkout remains");
+    }
+    if (stale())
+        return skip(`${fresh.path ? "checkout removed; " : ""}session or branch changed before branch deletion; branch kept`);
+    const deleted = await run(["update-ref", "-d", `refs/heads/${reviewed.branch}`, reviewed.tip], root);
+    if (deleted.code !== 0)
+        return fail(`${fresh.path ? "checkout removed; " : ""}branch kept: ${deleted.stderr.trim().slice(0, 200)}`);
+    return { outcome: "removed", item: reviewed, reason: fresh.reason };
+}
+/**
+ * Re-verify each reviewed prunable item immediately before removing its checkout, then delete its
+ * branch only at the reviewed tip. Ignored entries are deleted only when `allowIgnored` and all of
+ * them were in the review. Returns the repository checkouts that still exist.
+ */
+export async function removePruneCandidates(root, mainCwd, reviewed, allowIgnored, guards, run = runGit) {
+    const removals = [];
+    for (const item of reviewed) {
+        try {
+            removals.push(await removeOne(root, mainCwd, item, allowIgnored, guards, run));
+        }
+        catch (error) {
+            removals.push({ outcome: "failed", item, reason: (error instanceof Error ? error.message : String(error)).slice(0, 300) });
+        }
+    }
+    return { removals, checkouts: existing(await snapshot(root, mainCwd, run)) };
+}

package/dist/runner.d.ts

@@ -1,7 +1,10 @@
 import type { EphemeralSubagentExecutor } from "./ephemeral.ts";
+import type { PruneOwnership } from "./prune.ts";
 import { IntegrationGit } from "./integration-git.ts";
 import { type AllocationKind, type CheckCommand, type ChangesetTaskRequest, type CleanupKind, type ExecuteRequest, type ExecutionPolicySnapshot, type HostAllocationIntent, type HostAllocationPlan, type ModelClass, type ReviewEvidence, type ResumeRequest, type RunState, type TaskAttempt, type TaskRequest, type TaskState, type WorktreeAllocationIntent, type WorktreeAllocationPlan, type WorkspaceIdentity } from "./schema.ts";
 import { FileRunStore } from "./store.ts";
+/** One durable follow-up per attempt; the runner itself never commits, stages, stashes, or discards. */
+export declare const COMMIT_NUDGE_INSTRUCTION = "Your turn ended with uncommitted changes in your worktree. Commit the intended changes now so the worktree is clean, or explain in your reply why they must not be committed. Do not discard work.";
 export declare const CLEANUP_SAFETY_BUDGET_MS = 30000;
 export declare const TERMINATION_SAFETY_BUDGET_MS = 15000;
 export declare const STATUS_INSPECTION_BUDGET_MS = 5000;
@@ -65,6 +68,11 @@ export type WorkerResult = {
 } | {
     outcome: "blocked" | "not_prompted";
     diagnostic: string;
+}
+/** The exact turn finished in its valid owned worktree with tracked or untracked changes. */
+ | {
+    outcome: "uncommitted";
+    diagnostic: string;
 } | {
     outcome: "unknown" | "interrupted";
     diagnostic: string;
@@ -314,6 +322,11 @@ export declare class IsolatedRunner {
         invalidIds: string[];
         leaseBusy: boolean;
     }>;
+    /** Prune evidence across checkouts. A non-terminal state owns every resource name its saved text
+     * mentions; an unreadable state owns every name its raw text mentions, or every name when unreadable. */
+    pruneOwnership(checkouts: readonly string[]): Promise<PruneOwnership>;
+    /** After pruning, reconcile aborted requests that recorded a removed resource through the guarded abort path. */
+    reconcilePrunedAborts(checkouts: readonly string[], names: readonly string[]): Promise<string[]>;
     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

@@ -7,8 +7,11 @@ 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;
+const CORRECTION_DELIVERY_RESERVE_BYTES = 1024;
 const MAX_WORKER_PROMPTS = 32;
 const MAX_QUEUED_FOLLOWUPS = 16;
+/** One durable follow-up per attempt; the runner itself never commits, stages, stashes, or discards. */
+export const COMMIT_NUDGE_INSTRUCTION = "Your turn ended with uncommitted changes in your worktree. Commit the intended changes now so the worktree is clean, or explain in your reply why they must not be committed. Do not discard work.";
 export const CLEANUP_SAFETY_BUDGET_MS = 30_000;
 export const TERMINATION_SAFETY_BUDGET_MS = 15_000;
 export const STATUS_INSPECTION_BUDGET_MS = 5_000;
@@ -369,6 +372,9 @@ function exactCommandResults(results, checks) {
             && result.args.every((arg, argIndex) => arg === check.args[argIndex]);
     });
 }
+function isCommitNudge(prompt) {
+    return prompt.kind === "followup" && prompt.instruction === COMMIT_NUDGE_INSTRUCTION;
+}
 function correctionEligible(request, attempt) {
     const initial = attempt.prompts[0];
     if (initial?.kind !== "initial" || attempt.prompts.some((prompt) => prompt.kind === "correction" || prompt.status === "ambiguous")
@@ -377,11 +383,13 @@ function correctionEligible(request, attempt) {
     const latestPrompt = attempt.prompts.at(-1);
     if (latestPrompt.status !== "settled")
         return false;
+    // A commit nudge continues its turn; it never consumes the correction window.
+    const assignments = attempt.prompts.filter((prompt) => !isCommitNudge(prompt)).length;
     if (!attempt.candidate) {
-        return attempt.prompts.length === 1 && !attempt.preliminaryChecks && Boolean(initial.failure?.trim());
+        return assignments === 1 && !attempt.preliminaryChecks && Boolean(initial.failure?.trim());
     }
     const checks = attempt.preliminaryChecks;
-    return attempt.prompts.length === 1 && Boolean(checks
+    return assignments === 1 && Boolean(checks
         && checks.phase === "preliminary"
         && exactCommandResults(checks.results, request.checks)
         && sameIdentity(checks.candidate, attempt.candidate)
@@ -403,10 +411,10 @@ export function buildChangesetTaskPrompt(input) {
         && (typeof input.failure !== "string" || !input.failure.trim() || input.failure.trim() !== input.failure || input.failure.includes("\0"))) {
         throw new Error("correction failure must be a non-empty exact string.");
     }
-    if (input.kind === "followup"
+    if ((input.kind === "followup" || input.instruction !== undefined)
         && (typeof input.instruction !== "string" || !input.instruction.trim() || input.instruction.trim() !== input.instruction
             || input.instruction.includes("\0") || input.instruction.length > 32_000)) {
-        throw new Error("follow-up instruction must be non-empty exact text of at most 32000 characters.");
+        throw new Error(`${input.kind === "followup" ? "follow-up" : "correction"} instruction must be non-empty exact text of at most 32000 characters.`);
     }
     const checks = input.task.checks.map((check) => JSON.stringify({ command: check.command, args: check.args })).join("\n");
     const upstreamTaskData = input.contexts.length
@@ -440,6 +448,7 @@ export function buildChangesetTaskPrompt(input) {
         "Required checks (direct command/argv):",
         checks,
         ...(input.kind === "correction" ? ["", "Correction failure:", input.failure] : []),
+        ...(input.kind === "correction" && input.instruction ? ["", "Main's instruction:", input.instruction] : []),
         "",
         "Work only in the exact worktree above. Commit the complete result and leave that worktree clean.",
     ].join("\n");
@@ -572,6 +581,55 @@ export class IsolatedRunner {
         }
         return { requests, invalidIds: inventory.invalidIds, leaseBusy };
     }
+    /** Prune evidence across checkouts. A non-terminal state owns every resource name its saved text
+     * mentions; an unreadable state owns every name its raw text mentions, or every name when unreadable. */
+    async pruneOwnership(checkouts) {
+        const owners = [];
+        let lease;
+        for (const checkout of checkouts) {
+            const root = realpathSync.native(checkout);
+            if (!lease && await this.store.hasProductiveRunLease(root))
+                lease = `productive lease is held by a live run in ${root}`;
+            const { states, invalidIds } = await this.store.list(root);
+            for (const { state } of states) {
+                if (!terminal(state))
+                    owners.push({ label: `owned by ${state.status} request ${state.request.id}`, text: JSON.stringify(state) });
+            }
+            for (const id of invalidIds) {
+                let text;
+                try {
+                    text = await this.store.readRaw(root, id);
+                }
+                catch { /* It may own any name. */ }
+                owners.push({ label: `unreadable state ${id} in ${root} may own it`, text });
+            }
+        }
+        return { ...(lease ? { lease } : {}), owner: (name) => owners.find(({ text }) => text === undefined || text.includes(name))?.label };
+    }
+    /** After pruning, reconcile aborted requests that recorded a removed resource through the guarded abort path. */
+    async reconcilePrunedAborts(checkouts, names) {
+        const lines = [];
+        for (const checkout of checkouts) {
+            const root = realpathSync.native(checkout);
+            const { requests, states } = await this.listRequests(root);
+            for (const [index, state] of states.entries()) {
+                const id = state.request.id;
+                const text = JSON.stringify(state);
+                if (requests[index].status !== "aborted · retained" || !names.some((name) => text.includes(name)))
+                    continue;
+                try {
+                    await this.abort(id, root);
+                    const after = (await this.listRequests(root)).requests.find((request) => request.id === id);
+                    lines.push(after?.status === "aborted" ? `Reconciled cleanup of aborted request ${id}.`
+                        : `Aborted request ${id} still has pending cleanup; inspect subagent_status.`);
+                }
+                catch (error) {
+                    lines.push(`Aborted request ${id} could not be reconciled: ${errorText(error)}`);
+                }
+            }
+        }
+        return lines;
+    }
     canFollowup(root, requestId, taskId) {
         const active = this.activeControl(realpathSync.native(root), requestId, taskId);
         return active !== undefined && active.task.status === "working" && !active.control.isSealed;
@@ -757,6 +815,8 @@ export class IsolatedRunner {
                         throw new Error(`Task ${task.taskId} is not waiting for deliberate attention.`);
                     if (request.action === "verify")
                         throw new Error(`Text task ${task.taskId} cannot be verified.`);
+                    if (request.instruction !== undefined)
+                        throw new Error(`Text task ${task.taskId} retry cannot take a worker instruction.`);
                     if (!textRetryEligible(state, task)) {
                         const attempt = task.attempts.at(-1);
                         if ((attempt && !["failed", "superseded"].includes(attempt.status)) || task.attempts.length >= 2) {
@@ -771,7 +831,7 @@ export class IsolatedRunner {
                 if (task.status !== "needs_attention")
                     throw new Error(`Task ${task.taskId} is not waiting for deliberate attention.`);
                 if (request.action === "retry")
-                    return await this.retry(handle, task, scope);
+                    return await this.retry(handle, task, scope, request.instruction);
                 return await this.verifyRetainedTask(handle, task, scope);
             }
             catch (error) {
@@ -2179,6 +2239,8 @@ export class IsolatedRunner {
         let kind = initialKind;
         let failure = task.failure;
         let instruction = initialInstruction;
+        // A nudge keeps its dirty turn's exact clean pre-prompt lineage.
+        let nudgeFrom;
         for (;;) {
             if (kind === "followup" && instruction === undefined) {
                 throw new Error("Follow-up worker execution requires an exact queued instruction.");
@@ -2195,11 +2257,12 @@ export class IsolatedRunner {
             }
             let preCandidate;
             try {
-                preCandidate = runtimeIdentity(await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectTaskCandidate({
+                preCandidate = nudgeFrom ?? runtimeIdentity(await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectTaskCandidate({
                     root: state.root,
                     task: request,
                     attempt,
                 }, context)), "Pre-prompt candidate identity");
+                nudgeFrom = undefined;
             }
             catch (error) {
                 this.rethrowStopped(error);
@@ -2233,7 +2296,7 @@ export class IsolatedRunner {
                 kind,
                 status: "submitting",
                 preCandidate,
-                ...(kind === "followup" ? { instruction } : {}),
+                ...(instruction !== undefined ? { instruction } : {}),
                 at: nextAttemptEventAt(attempt, this.coordinatorRuntime.now()),
             };
             attempt.prompts.push(prompt);
@@ -2278,6 +2341,19 @@ export class IsolatedRunner {
                 return;
             }
             prompt.status = "settled";
+            if (worker.outcome === "uncommitted") {
+                prompt.failure = boundedRuntimeDiagnostic(worker.diagnostic, "uncommitted worker diagnostic");
+                if (attempt.prompts.some(isCommitNudge)) {
+                    this.attention(task, "The commit nudge was sent, but the worker turn still left uncommitted changes in its worktree; they are retained for inspection.");
+                    await this.saveProductive(handle);
+                    return;
+                }
+                await this.saveProductive(handle);
+                kind = "followup";
+                instruction = COMMIT_NUDGE_INSTRUCTION;
+                nudgeFrom = preCandidate;
+                continue;
+            }
             if (worker.outcome === "blocked") {
                 failure = boundedRuntimeDiagnostic(worker.diagnostic, "blocked worker diagnostic");
                 prompt.failure = failure;
@@ -2522,8 +2598,11 @@ export class IsolatedRunner {
         await this.saveProductive(handle);
         return this.response(handle.state);
     }
-    async retry(handle, task, scope) {
+    async retry(handle, task, scope, instruction) {
         const attempt = task.attempts.at(-1);
+        if (instruction !== undefined && !attempt?.prompts.length) {
+            throw new Error("A retry instruction requires a same-worker correction of a prompted attempt.");
+        }
         if (!attempt) {
             for (const pending of handle.state.tasks) {
                 if (pending.status === "needs_attention" && pending.attempts.length === 0) {
@@ -2538,11 +2617,26 @@ export class IsolatedRunner {
             if (attempt.prompts.some((prompt) => prompt.status === "ambiguous")) {
                 throw new Error("An ambiguous delivered prompt is never replayed.");
             }
-            if (!this.correctionAllowed(handle.state, changesetTaskRequest(handle.state, task.taskId), attempt)) {
+            const request = changesetTaskRequest(handle.state, task.taskId);
+            if (!this.correctionAllowed(handle.state, request, attempt)) {
                 throw new Error("The same-agent correction is unavailable or already used.");
             }
+            // Build the correction before it is recorded: an oversized prompt must not use up the only correction.
+            // The reserve covers the worktree path and turn identity the host adds before delivery.
+            const assignment = buildChangesetTaskPrompt({
+                goal: handle.state.request.goal,
+                contexts: resolveTextTaskContexts(handle.state, request),
+                task: request,
+                kind: "correction",
+                worktreeCwd: allocationByKind(attempt, "agent")?.worktreeCwd ?? "",
+                failure: task.failure,
+                ...(instruction === undefined ? {} : { instruction }),
+            });
+            if (Buffer.byteLength(assignment, "utf8") + CORRECTION_DELIVERY_RESERVE_BYTES > CHANGESET_TASK_PROMPT_MAX_BYTES) {
+                throw new Error(`Worker assignment exceeds ${CHANGESET_TASK_PROMPT_MAX_BYTES} bytes with delivery overhead; shorten the retry instruction.`);
+            }
             task.status = "working";
-            await this.driveWorkerSafely(handle, task, scope, "correction");
+            await this.driveWorkerSafely(handle, task, scope, "correction", instruction);
         }
         else {
             if (attempt.termination || allocationByKind(attempt, "agent")) {

package/dist/schema.d.ts

@@ -121,6 +121,7 @@ export declare const ResumeRequestSchema: Type.TUnion<[Type.TObject<{
     id: Type.TString;
     action: Type.TLiteral<"retry">;
     taskId: Type.TString;
+    instruction: Type.TOptional<Type.TString>;
 }>, Type.TObject<{
     id: Type.TString;
     action: Type.TLiteral<"verify">;
@@ -133,6 +134,7 @@ export declare const ResumeRequestParameters: Type.TObject<{
     id: Type.TString;
     action: Type.TUnion<[Type.TLiteral<"retry">, Type.TLiteral<"verify">, Type.TLiteral<"finalize">]>;
     taskId: Type.TOptional<Type.TString>;
+    instruction: Type.TOptional<Type.TString>;
 }>;
 export type IdOnly = Static<typeof IdOnlySchema>;
 export type CheckCommand = Static<typeof CheckCommandSchema>;
@@ -2389,6 +2391,10 @@ export declare const StatusOutputSchema: Type.TObject<{
             scope: Type.TUnion<[Type.TLiteral<"task">, Type.TLiteral<"final">, Type.TLiteral<"request">]>;
             taskId: Type.TOptional<Type.TString>;
             failure: Type.TOptional<Type.TString>;
+            failedReview: Type.TOptional<Type.TObject<{
+                verdict: Type.TString;
+                verdictTruncated: Type.TBoolean;
+            }>>;
         }>>;
         createdAt: Type.TInteger;
         updatedAt: Type.TInteger;
@@ -2421,6 +2427,7 @@ export declare const StatusOutputSchema: Type.TObject<{
         id: Type.TString;
         action: Type.TLiteral<"retry">;
         taskId: Type.TString;
+        instruction: Type.TOptional<Type.TString>;
     }>, Type.TObject<{
         id: Type.TString;
         action: Type.TLiteral<"verify">;

package/dist/schema.js

@@ -62,7 +62,7 @@ export const ExecuteRequestSchema = Type.Object({
 }, { additionalProperties: false });
 export const IdOnlySchema = Type.Object({ id: IdSchema }, { additionalProperties: false });
 export const ResumeRequestSchema = Type.Union([
-    Type.Object({ id: IdSchema, action: Type.Literal("retry"), taskId: IdSchema }, { additionalProperties: false }),
+    Type.Object({ id: IdSchema, action: Type.Literal("retry"), taskId: IdSchema, instruction: Type.Optional(TextSchema) }, { additionalProperties: false }),
     Type.Object({ id: IdSchema, action: Type.Literal("verify"), taskId: IdSchema }, { additionalProperties: false }),
     Type.Object({ id: IdSchema, action: Type.Literal("finalize") }, { additionalProperties: false }),
 ]);
@@ -75,6 +75,7 @@ export const ResumeRequestParameters = Type.Object({
         ResumeRequestSchema.anyOf[2].properties.action,
     ]),
     taskId: Type.Optional(IdSchema),
+    instruction: ResumeRequestSchema.anyOf[0].properties.instruction,
 }, { additionalProperties: false });
 const AllocationLifecycleFields = {
     generation: Type.Integer({ minimum: 1, maximum: 2 }),
@@ -466,6 +467,7 @@ export const StatusOutputSchema = Type.Object({
             scope: Type.Union([Type.Literal("task"), Type.Literal("final"), Type.Literal("request")]),
             taskId: Type.Optional(IdSchema),
             failure: Type.Optional(Type.String()),
+            failedReview: Type.Optional(Type.Object({ verdict: Type.String(), verdictTruncated: Type.Boolean() })),
         })),
         createdAt: TimestampSchema,
         updatedAt: TimestampSchema,
@@ -635,7 +637,10 @@ export function parseResumeRequest(value) {
     if (!Check(ResumeRequestSchema, value)) {
         throw schemaValidationError("subagent_resume request must match one strict action", Errors(ResumeRequestSchema, value));
     }
-    return value;
+    const request = value;
+    if ("instruction" in request && request.instruction !== undefined)
+        requireExactAllocationText(request.instruction, "Retry instruction");
+    return request;
 }
 export function sameIdentity(left, right) {
     return left.branch === right.branch && left.head === right.head && left.index === right.index && left.tree === right.tree;
@@ -1080,11 +1085,11 @@ export function parseRunState(value) {
             }
             for (let promptIndex = 0; promptIndex < attempt.prompts.length; promptIndex += 1) {
                 const prompt = attempt.prompts[promptIndex];
-                if ((prompt.kind === "followup") !== (prompt.instruction !== undefined)) {
-                    throw new Error(`Follow-up prompt history for ${definition.id} has invalid instruction evidence.`);
+                if (prompt.kind === "followup" ? prompt.instruction === undefined : prompt.kind === "initial" && prompt.instruction !== undefined) {
+                    throw new Error(`Prompt history for ${definition.id} has invalid instruction evidence.`);
                 }
                 if (prompt.instruction !== undefined) {
-                    requireExactAllocationText(prompt.instruction, `Follow-up prompt instruction for ${definition.id}`);
+                    requireExactAllocationText(prompt.instruction, `Prompt instruction for ${definition.id}`);
                 }
                 if (promptIndex === 0)
                     continue;

package/dist/store.d.ts

@@ -48,6 +48,8 @@ export declare class FileRunStore {
         states: RunStateHandle[];
         invalidIds: string[];
     }>;
+    /** Raw text of a state file, for evidence when it does not parse. */
+    readRaw(root: string, id: string): Promise<string>;
     private handle;
 }
 export {};

package/dist/store.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { mkdir, open, readdir, realpath } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { extensionConfigDir, readTextFileBounded, writePrivateTextFileAtomically } from "@henryqw/pi-config-store";
 import { check, lock } from "proper-lockfile";
@@ -272,8 +272,13 @@ export class FileRunStore {
         const entries = await this.stateEntries(root);
         const states = [];
         const invalidIds = [];
-        for (const entry of entries.filter((item) => item.isFile())) {
+        for (const entry of entries) {
             const id = entry.name.slice(0, -5);
+            // A symlink, directory, or other non-regular entry is unreadable state, never absent state.
+            if (!entry.isFile()) {
+                invalidIds.push(id);
+                continue;
+            }
             try {
                 states.push(await this.load(root, id));
             }
@@ -283,6 +288,13 @@ export class FileRunStore {
         }
         return { states, invalidIds };
     }
+    /** Raw text of a state file, for evidence when it does not parse. */
+    async readRaw(root, id) {
+        const path = this.statePath(root, id);
+        if (!(await lstat(path)).isFile())
+            throw new Error(`State entry ${id} is not a regular file.`);
+        return await readTextFileBounded(path, STATE_MAX_BYTES);
+    }
     handle(state, path) {
         return new RunStateHandle(state, path, async (contents) => {
             await this.assertSafeDestination(state.root, path);

package/dist/worktree.d.ts

@@ -24,6 +24,9 @@ export type WorktreePayload = {
     commits?: number;
     dirty?: boolean;
 };
+export declare const WORKTREES_DIRNAME = ".worktrees";
+/** Branches `createChildWorktree` creates for workers and integration checkouts, at `<primary>/.worktrees/<branch basename>`. */
+export declare const OWNED_BRANCH_PATTERN: RegExp;
 export declare class WorktreeSetupError extends Error {
     name: string;
     readonly worktree: WorktreeInfo;

package/dist/worktree.js

@@ -3,8 +3,10 @@ import { existsSync, lstatSync } from "node:fs";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { runGit } from "./git-process.js";
-const WORKTREES_DIRNAME = ".worktrees";
+export const WORKTREES_DIRNAME = ".worktrees";
 const BRANCH_NAMESPACE = "pi-subagent";
+/** Branches `createChildWorktree` creates for workers and integration checkouts, at `<primary>/.worktrees/<branch basename>`. */
+export const OWNED_BRANCH_PATTERN = new RegExp(`^${BRANCH_NAMESPACE}/subagent-[0-9a-f]{24}$`);
 export class WorktreeSetupError extends Error {
     name = "WorktreeSetupError";
     worktree;

package/docs/orchestration.md

@@ -112,7 +112,7 @@ The user's request can authorize the declared local graph, checks, review, and M
 
 `/subagent` opens a native picker for direct recovery and isolated inspection; locally owned active changesets may queue an optional same-worker revision or drain all still-pending instructions into the native editor and submit one replacement. Cancel after draining leaves them withdrawn; claimed instructions are unaffected. Pi's global Option+Up is unchanged. There is no guaranteed post-completion editing window; late follow-ups fail visibly. After readiness, use `subagent_stage revise` with an exact candidate, generation, current `expectedTip`, and instruction when a same-worker correction remains allowed. Material scope growth, missing authorization, user-owned conflicts, or consequential external actions still require a new decision. pi-subagent never pushes, publishes, deploys, or opens a pull request.
 
-`subagent_status` reports ready candidates with `taskId`, `attempt`, and `tip`, plus each generation's number, stage lineage, combined tip, checks, promotion, and retained worktree. Use those exact identities (including branch, HEAD, index, and tree) rather than guessed commits:
+`subagent_status` puts failed review verdicts from every task's latest attempt (also while siblings run), the final gate, and each generation into its model-visible text within one shared 32 KiB budget and counts omitted verdicts; its structured projection carries each verdict up to 32 KiB and sets `verdictTruncated` when it is cut; asynchronous follow-ups keep a short preview and point Main to `subagent_status`. It reports ready candidates with `taskId`, `attempt`, and `tip`, plus each generation's number, stage lineage, combined tip, checks, promotion, and retained worktree. Use those exact identities (including branch, HEAD, index, and tree) rather than guessed commits:
 
 - `subagent_stage`: `{ id, action: "stage" | "resolve" | "reject" | "revise", generation, taskId, attempt, candidate, expectedTip, instruction? }`. `candidate` is the ready candidate's `tip`; `expectedTip` is Main's recorded identity for the first stage or the previous stage's exact tip. `resolve` reconciles a pending/conflicted merge; `reject` and `revise` arbitrate a candidate without changing Main.
 - `subagent_integrate`: `{ id, action: "advance" | "validate" | "correct" | "promote" | "reconcile" | "cleanup", generation, expectedTip }`. Use the generation's exact `combinedTip`. `advance` dispatches ready dependents on that snapshot, `correct` records the single clean committed correction after a definitive failed check/review, `reconcile` inspects an interrupted validation or promotion without replaying an uncertain promotion, and `cleanup` completes proved post-promotion cleanup.
@@ -129,7 +129,9 @@ State version 5 is stored privately under:
 <agent-dir>/config/pi-subagent/state/<repository-hash>/<request-id>.json
 ```
 
-Strict parsing rejects unknown properties, malformed evidence, invalid lineage, and old v4 state without migration; preserve old files and recover their work manually. Writes are atomic and repository productive work uses a durable process lease. `delegate_task` and `subagent_resume` acknowledge only after durable state is saved, then continue productive work asynchronously. A durably recorded worker attention state sends an immediate once-per-transition Pi follow-up to the launching session, even while siblings run; the wave also reports its final outcome. Isolated workers persist a private exact Pi session under the owned process lease so a proved final answer without a changed clean commit becomes attention rather than an indefinitely pending prompt. Missing or mismatched session proof cannot establish completion and never authorizes prompt replay. `subagent_status` is read-only and remains the recovery authority if a follow-up is missed. `subagent_resume` accepts only the continuation reported by state. `subagent_abort` performs exact worker termination and conservative teardown. Without a retained candidate, it removes only owned checkouts still clean and unchanged from their pinned base, including ignored-file checks. Active productive execution defers cleanup until it settles. Repeating abort on an aborted request reconciles pending cleanup without replaying uncertain termination. Dirty or committed work and uncertain allocations stay retained with visible blockers; `/subagent recover` includes aborted requests with retained resources.
+Strict parsing rejects unknown properties, malformed evidence, invalid lineage, and old v4 state without migration; preserve old files and recover their work manually. Writes are atomic and repository productive work uses a durable process lease. `delegate_task` and `subagent_resume` acknowledge only after durable state is saved, then continue productive work asynchronously. A durably recorded worker attention state sends an immediate once-per-transition Pi follow-up to the launching session, even while siblings run; the wave also reports its final outcome. Isolated workers persist a private exact Pi session under the owned process lease so a proved final answer without a changed clean commit becomes attention rather than an indefinitely pending prompt. Missing or mismatched session proof cannot establish completion and never authorizes prompt replay. When a proved finished turn leaves tracked or untracked changes in a valid owned worktree, the runner sends the same worker one commit reminder per attempt, saved as a follow-up prompt record before delivery like any other prompt. It does not use a correction or a dispatch attempt. The runner never commits, stages, stashes, or discards; a commit from the reminder goes through the normal candidate path, and a worktree still dirty after it needs attention. `subagent_status` is read-only and remains the recovery authority if a follow-up is missed. `subagent_resume` accepts only the continuation reported by state. A `retry` that sends a same-worker correction may add an `instruction` (at most 32000 exact characters, no NUL), appended to the correction prompt as Main's instruction after the saved failure and saved in its prompt record before delivery; other actions reject it. `subagent_abort` performs exact worker termination and conservative teardown. Without a retained candidate, it removes only owned checkouts still clean and unchanged from their pinned base, including ignored-file checks. Active productive execution defers cleanup until it settles. Repeating abort on an aborted request reconciles pending cleanup without replaying uncertain termination. Dirty or committed work and uncertain allocations stay retained with visible blockers; `/subagent recover` includes aborted requests with retained resources.
+
+`/subagent prune` reviews every `pi-subagent/subagent-<24 hex>` branch in the repository and its `.worktrees/` checkout. An item is removable only when its tip is an ancestor of Main's HEAD or the local `origin` default-branch ref (no fetch), the checkout is still on its own branch (a detached or switched owned checkout is found by path and blocks), has no tracked or untracked changes, no initialized submodules, and no in-progress Git operation, no non-terminal or unreadable state in any of the repository's checkouts records its name (a non-regular state entry counts as unreadable and may own any name), no productive lease is live, and no Herdr pane works inside the checkout (unavailable Herdr refuses). Removal needs interactive confirmation; checkouts with ignored files need a second confirmation that names each ignored entry in full, and a checkout whose list does not fit is left out; that approval covers each entry with all its contents, and a new or changed top-level ignored entry skips the checkout. Prunable items are listed first, and only items shown in full in both dialogs can be removed; an over-long list ends with an explicit `+N more not shown` line instead of a silent cut. The confirming session's ownership is rechecked immediately before each `git worktree remove` and branch deletion. Each item is re-verified immediately before `git worktree remove`, and its branch is deleted with a compare-and-swap on the reviewed tip. Aborted requests that recorded a removed resource are then reconciled by the guarded abort path, which proves absence; requests it cannot reconcile are reported. State files are never edited directly.
 
 Text attempt history records dispatches, not pre-dispatch inspection failures. Such failures retain task-level attention without adding an attempt or rewriting earlier execution diagnostics. A recorded interrupted dispatch still consumes an attempt. Verification requires the same passing preliminary checks, judgment, and ownership as candidate retention; readiness and the verified candidate are saved together.