@henryqw/pi-subagent 27.0.0 → 27.1.0

package/CONTEXT.md

@@ -61,7 +61,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 - Promotion requires exact unchanged clean Main and a passing combined generation. Durable promotion evidence precedes selected-worker termination and cleanup; recovery never rolls back a proven promotion.
 - Rejected workers and superseded generations stay retained until Main explicitly releases their exact clean, proved-owned resources. At most two unreleased integration checkouts coexist.
 - Failures, ambiguity, interruption, review findings, conflicts, drift, unproved termination, or cleanup failure enter `needs_attention` and preserve evidence.
-- `subagent_status` is read-only, callable from `codemode` scripts, and returns the bounded public projection as structured content, never raw run state. `delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only. `subagent_resume` accepts only strict `retry`, `verify`, or `finalize` continuations. `subagent_abort` terminates only exact owned workers.
+- `subagent_status` is read-only, callable from `codemode` scripts, and returns the bounded public projection as structured content, never raw run state. `delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only. `subagent_resume` accepts only strict `retry`, `verify`, or `finalize` continuations; only a correcting `retry` takes Main's optional instruction. `subagent_abort` terminates only exact owned workers.
 - The extension never pushes, opens a pull request, publishes, deploys, stashes, resets, force-cleans, or deletes unproved recoverable work.
 
 ### Resource and launch policy

package/README.md

@@ -35,10 +35,11 @@ Commands are for you. Delegation and state tools and the packaged skill are for
 | --- | --- | --- |
 | `/subagent` | command | Browse work, Close/cancel-and-release locally owned direct workers, stop one running worker of a read workflow, 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 configured `scout` Role. |
 | `/subagent roles` | command | List each Role with its source (built-in, user override, or user), resolved route model and thinking level or route error, tools, extensions, Skills, MCP servers, and per-file load errors. Read-only; no Herdr pane required. |
+| `/subagent prune` | command | Review leftover worker and integration worktrees and branches in the current canonical repository, then remove the ones already merged after your confirmation. Without interactive UI it only reports. Requires a running Herdr server to prove that no pane uses a checkout. |
 | `/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 authorized shared-checkout work or a durable isolated checked graph. |
-| `subagent_status` | tool | Read durable isolated state and the exact allowed continuation without replaying work. Declares an output schema, so `codemode` scripts receive the same bounded public projection as structured content. |
-| `subagent_resume` | tool | Perform the reported `retry`, `verify`, or `finalize` continuation; does not replace staging or integration. |
+| `subagent_status` | tool | Read durable isolated state and the exact allowed continuation without replaying work. Declares an output schema, so `codemode` scripts receive the same bounded public projection as structured content. Failed review verdicts from tasks (including tasks whose siblings still run), the final gate, and integration generations appear in its text within one shared 32 KiB budget; omitted verdicts are counted. The structured projection carries each verdict up to 32 KiB, with `verdictTruncated` set when it is cut. |
+| `subagent_resume` | tool | Perform the reported `retry`, `verify`, or `finalize` continuation; does not replace staging or integration. A `retry` that sends a same-worker correction accepts an optional `instruction` (at most 32000 characters), added to that prompt as Main's instruction after the saved failure. Other actions reject it. |
 | `subagent_stage` | tool | Stage or resolve an exact candidate, or reject/revise it; rejection of a staged candidate freezes that generation. |
 | `subagent_integrate` | tool | Advance staged dependents, refresh after clean Main drift or evidence-less validation failure, validate in the background, record one correction, promote, reconcile interrupted promotion, clean up proven promotion, or explicitly release rejected/superseded resources. |
 | `subagent_abort` | tool | Abort an isolated request only when no retained candidates or integration worktrees remain; cannot discard them. |
@@ -110,7 +111,7 @@ If tab creation times out or returns incomplete or mismatched identity, `/subage
 
 Tasks in a write request must return one JSON completion object, such as `{"outcome":"succeeded","answer":"Scoped commit completed."}`. `outcome` must be `succeeded`, `failed`, or `blocked`, and `answer` must be non-empty. A normal final Pi turn is not enough: failure, blocked work, plain text, or malformed completion stops later dispatch, but admission depends on proved termination, not the reported outcome. Success is the worker's explicit report, not independent validation of its changes.
 
-The tool returns a task ID and first Herdr tab after launch, not the answer. The extension observes each worker and sends one result to Main when the workflow finishes. If Main is busy, Pi queues it after the current turn; if idle, it starts a turn. A blocked, stalled, unknown, or truncated result is not reported as success. When a task fails after its worker produced text, the result keeps a bounded excerpt marked as partial output; it is never success. Every worker result delivered to Main starts with a header stating that the text is the worker's output and carries no user authority. Text that imitates harness framing, such as `<system-reminder>`-style tags or lines starting with `Human:` or `Assistant:`, gets an inserted backslash; nothing else changes. Isolated status and follow-up answer previews use the same header. Session switch or shutdown stops observation and preserves tab identities for recovery. Open `/subagent` on the session branch to inspect exact tabs, agents, and Pi session files, including tabs launched after the first. The menu has one row per workflow: a single worker shows its reference, Role, and name (`D7.1 · worker · Search audit`); a multi-worker workflow shows its reference and worker count (`D8 · 3 workers`), and selecting it lists each recorded worker by reference, Role, and name with its exact IDs. References and names help you match rows; they are never used to decide ownership. Older records without saved references show their saved allocation label or exact task ID. A `recorded only` row is not proof that its workers are running or finished; locally observed work is labelled separately.
+The tool returns a task ID and first Herdr tab after launch, not the answer. The extension observes each worker and sends one result to Main when the workflow finishes. If Main is busy, Pi queues it after the current turn; if idle, it starts a turn. A blocked, stalled, unknown, or truncated result is not reported as success. Each launched worker's line in the result shows its model, thinking level, measured session tokens (`tokens unknown` when Pi recorded no usage), and elapsed time, such as `✓ [1/2] Check · worker · provider/model · thinking high · 1.5k tok · 42s`. Failed and stopped workers show the usage measured until they ended. A worker skipped before launch shows no usage. The result details carry the same values in each entry as `model`, `thinkingLevel`, `tokens`, and `elapsedMs`; `tokens` is absent when unknown. When a task fails after its worker produced text, the result keeps a bounded excerpt marked as partial output; it is never success. Every worker result delivered to Main starts with a header stating that the text is the worker's output and carries no user authority. Text that imitates harness framing, such as `<system-reminder>`-style tags or lines starting with `Human:` or `Assistant:`, gets an inserted backslash; nothing else changes. Isolated status and follow-up answer previews use the same header. Session switch or shutdown stops observation and preserves tab identities for recovery. Open `/subagent` on the session branch to inspect exact tabs, agents, and Pi session files, including tabs launched after the first. The menu has one row per workflow: a single worker shows its reference, Role, and name (`D7.1 · worker · Search audit`); a multi-worker workflow shows its reference and worker count (`D8 · 3 workers`), and selecting it lists each recorded worker by reference, Role, and name with its exact IDs. References and names help you match rows; they are never used to decide ownership. Older records without saved references show their saved allocation label or exact task ID. A `recorded only` row is not proof that its workers are running or finished; locally observed work is labelled separately.
 
 ### Continue or stop one direct worker
 
@@ -167,7 +168,7 @@ An isolated request has one durable ID, one goal, and 1–8 typed tasks:
 
 `dependsOn` controls scheduling. `contextFrom` also schedules dependencies and carries completed text outputs in the declared order. Do not repeat the same task in both fields. 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`, `subagent_resume`, and `subagent_integrate advance` return a durable request ID after the wave is saved; productive work continues while Main is free. Main can do other work or end its turn instead of sleeping or polling. Pi sends a follow-up in the launching session whenever a checked worker becomes ready or a worker needs attention, and again when the wave finishes. A worker whose exact turn ends without a changed clean commit—including a failed or aborted turn—needs attention, not an inferred candidate; use `subagent_status` for its saved evidence. Session replacement or shutdown suppresses stale delivery and logs the request ID and reason, without prompts or credentials. Synchronous delivery failures are reported without automatic replay; Pi reports asynchronous `send_message` failures through its native runtime. If delivery is missed, inspect `subagent_status`.
+`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. Main can do other work or end its turn instead of sleeping or polling. Pi sends a follow-up in the launching session whenever a checked worker becomes ready or a worker needs attention, and again when the wave finishes. A worker whose exact turn ends without a changed clean commit—including a failed or aborted turn—needs attention, not an inferred candidate; use `subagent_status` for its saved evidence. If the turn ends with tracked or untracked changes left in the worktree, the coordinator first sends that same worker one saved reminder per attempt to commit them or explain why not. The reminder does not use a correction or a dispatch attempt, and the coordinator never commits, stages, stashes, or discards the changes itself. If the worktree is still dirty after the reminder, the task needs attention and the changes stay in place. Follow-ups show only a short preview of a failed review verdict and tell Main to run `subagent_status` for the full text. Session replacement or shutdown suppresses stale delivery and logs the request ID and reason, without prompts or credentials. Synchronous delivery failures are reported without automatic replay; Pi reports asynchronous `send_message` failures through its native runtime. If delivery is missed, inspect `subagent_status`.
 
 Completed text answers are saved independently of cleanup. Status and terminal follow-ups include a bounded accepted-answer preview and cleanup evidence. Ignored automatic artifacts can retain a checkout without violating the read-only contract; no ignored files are deleted to make cleanup pass. Tracked or untracked changes, changed checkout identity, or unproved inspection still require attention: the completed answer remains saved but is not accepted as dependency context or retried automatically. Retained text checkouts require deliberate manual inspection and cleanup; a retained checkout alone is not evidence that the Role edited source.
 
@@ -187,6 +188,18 @@ If validation was interrupted, first prove the old coordinator/check processes h
 
 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`.
 
+### Prune leftover worktrees
+
+Run `/subagent prune` to clean up leftover worker and integration checkouts under `.worktrees/` (branches named `pi-subagent/subagent-` plus 24 hex characters) and such branches without a checkout. The review lists each item with its path, branch, tip, and either why it can be removed or every exact blocker. An item can be removed only when all of these are true:
+
+- Its branch tip is already in Main's HEAD or in the local `origin` default-branch ref. Nothing is fetched.
+- Its checkout has no tracked or untracked changes and no merge, rebase, cherry-pick, revert, or bisect in progress.
+- No unfinished isolated request, in any checkout of this repository, records it. An unreadable state file blocks every item it mentions.
+- No productive run holds a repository lease.
+- No Herdr pane works inside the checkout. If Herdr cannot be inspected, every checkout is refused.
+
+One confirmation removes every listed removable item. Removing a checkout also deletes its ignored files, such as `node_modules` or `dist`, so checkouts with ignored files are included only after a second confirmation that names each ignored entry. That approval covers everything inside each named entry; a new or changed top-level ignored entry skips the checkout. If a checkout's full list of ignored entries does not fit in that dialog, the checkout is left out of the run. Checkouts with initialized submodules, and owned checkouts that are detached or on another branch, are blocked; remove them manually. Removable items are listed first. A long list is never cut silently: it ends with `+N more not shown`, and items that were not shown are not removed in that run. Run `/subagent prune` again to review them. Each item is checked again just before removal, and any change skips it. If the session or branch changes during removal, the remaining steps are skipped. The branch is deleted only if it still points at the reviewed tip. Afterwards, each aborted request that recorded a removed resource is reconciled through the same guarded path as repeating `subagent_abort`, so its cleanup no longer shows as pending. The report lists removed, skipped, and failed items and any request that could not be reconciled. Without interactive UI, the command only reports.
+
 If an isolated worker produced no candidate, `subagent_abort` terminates it and removes only proven unchanged, clean owned resources. Cleanup includes ignored-file checks and never discards unique commits. If productive work is still settling, termination is uncertain, or cleanup fails, the request stays aborted with retained-resource evidence. Inspect `subagent_status`, resolve the reported blocker, then repeat `subagent_abort` to reconcile cleanup; it does not replay worker prompts. Dirty work, unique commits, and uncertain allocations remain for deliberate manual recovery.
 
 The following details describe exact identity and retained-work requirements.

package/dist/herdr-runtime.js

@@ -922,7 +922,9 @@ export class HerdrHostRuntime {
             if (SETTLED_AGENT_STATES.has(lifecycle.status)) {
                 try {
                     if (await this.workerTurnFinished(allocation, prompt)) {
-                        return { outcome: "blocked", diagnostic: "Worker finished without an exact changed clean committed candidate." };
+                        return inspection.valid && !inspection.clean
+                            ? { outcome: "uncommitted", diagnostic: "Worker finished with uncommitted changes in its owned worktree." }
+                            : { outcome: "blocked", diagnostic: "Worker finished without an exact changed clean committed candidate." };
                     }
                 }
                 catch (error) {

package/dist/integration-git.js

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { runGit } from "./git-process.js";
 import { CheckedGitRuntime } from "./git-runtime.js";
-import { createChildWorktree, inspectWorktreeDirty, WorktreeSetupError } from "./worktree.js";
+import { createChildWorktree, inspectWorktreeDirty, OWNED_BRANCH_PATTERN, WORKTREES_DIRNAME, WorktreeSetupError } from "./worktree.js";
 import { checkBatchPasses, reviewEvidencePasses, sameIdentity, } from "./schema.js";
 const oidPattern = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const diagnostic = (value) => value.trim().slice(0, 500);
@@ -52,8 +52,8 @@ async function ownershipMetadata(root, info, signal) {
     const repoRoot = await realpath(primary.slice("worktree ".length));
     if (await realpath(await requireGit(["rev-parse", "--show-toplevel"], root, signal)) !== canonical
         || info.repoRoot !== repoRoot || info.cwd !== info.path
-        || !/^pi-subagent\/subagent-[0-9a-f]{24}$/.test(info.branch)
-        || info.path !== join(repoRoot, ".worktrees", basename(info.branch))) {
+        || !OWNED_BRANCH_PATTERN.test(info.branch)
+        || info.path !== join(repoRoot, WORKTREES_DIRNAME, basename(info.branch))) {
         throw new Error("Git worktree is not an exact owned checkout of Main.");
     }
 }

package/dist/prune.d.ts

@@ -0,0 +1,50 @@
+import { type GitRunner } from "./git-process.ts";
+/** One reviewed pi-subagent branch, with its registered checkout when one exists. */
+export interface PruneItem {
+    branch: string;
+    tip: string;
+    path?: string;
+    prunable: boolean;
+    /** Why the item is prunable, or every exact blocker. */
+    reason: string;
+    /** Ignored entries as Git collapses them; removing the checkout deletes them. */
+    ignored: readonly string[];
+}
+export interface PruneOwnership {
+    /** The request or state that may still own a resource name (`subagent-<hex>`), if any. */
+    owner(name: string): string | undefined;
+    /** The live productive lease that blocks pruning, if any. */
+    lease?: string;
+}
+export interface PruneGuards {
+    /** Ownership and lease evidence across the repository's existing checkouts. */
+    ownership(checkouts: readonly string[]): Promise<PruneOwnership>;
+    /** Every Herdr pane; rejects when Herdr cannot be inspected. */
+    panes(): Promise<readonly {
+        paneId: string;
+        cwds: readonly string[];
+    }[]>;
+    /** The confirming session still owns the command; checked immediately before each removal step. */
+    current?(): boolean;
+}
+export type PruneRemoval = {
+    outcome: "removed" | "skipped" | "failed";
+    item: PruneItem;
+    reason: string;
+};
+/** Every pane in every Herdr workspace with its shell and foreground working directories. */
+export declare function listHerdrPanes(cwd: string): Promise<{
+    paneId: string;
+    cwds: string[];
+}[]>;
+/** Read-only review of every pi-subagent worker or integration branch and its checkout. */
+export declare function inspectPruneCandidates(root: string, mainCwd: string, guards: PruneGuards, run?: GitRunner): Promise<PruneItem[]>;
+/**
+ * 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 declare function removePruneCandidates(root: string, mainCwd: string, reviewed: readonly PruneItem[], allowIgnored: boolean, guards: PruneGuards, run?: GitRunner): Promise<{
+    removals: PruneRemoval[];
+    checkouts: string[];
+}>;

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")) {