@henryqw/pi-subagent 27.4.5 → 27.5.1

package/README.md

@@ -29,7 +29,7 @@ Commands and UI are for you. Tools and the packaged skill are for Main, except `
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `/subagent` | command | Browse direct and isolated work. Stop or close owned direct workers, inspect isolated status, send follow-ups, or edit pending instructions. Requires interactive TUI or RPC. |
+| `/subagent` | command | Browse direct and isolated work, including requests whose parent checkout was removed. Stop direct workers, inspect isolated work, send follow-ups, or delete owned isolated worktrees after confirmation. Without interactive UI, only reports. |
 | `/subagent roles` | command | List Role sources, resources, resolved model and thinking level, route errors, and file errors. Read-only; requires no Herdr pane. |
 | `/subagent prune` | command | Review remaining worker and integration branches and worktrees. Remove merged resources after confirmation. Requires a running Herdr server; without interactive UI, only reports. |
 | `/subagent recover` | command | Classify orphaned isolated work in the canonical repository. Send Main request IDs, blockers, and next actions. Requires no UI or Herdr pane. |
@@ -131,6 +131,10 @@ The extension sends follow-ups when a candidate becomes ready, a worker needs at
 
 Open `/subagent` to browse direct work on this session branch and isolated requests in the current canonical Git checkout, including other sessions. **Refresh** reloads saved status without recovery or mutation. Invalid state IDs stay preserved with a warning. Direct recovery remains available outside Git or without isolated inventory.
 
+Requests whose parent checkout was removed show as **Isolated · orphaned** from any checkout of the same repository. Select **Close and delete worktrees (discard work)** to review owned resources and confirm deletion. **This permanently deletes committed, uncommitted, and ignored content in the listed checkouts.** Cancel makes no change.
+
+Only shown resources can be removed; live jobs, uncertain ownership, or other Herdr panes can block removal. Agents and tools cannot trigger this action. See [Close and delete isolated worktrees](./docs/orchestration.md#close-and-delete-isolated-worktrees) for guards and partial cleanup.
+
 Inspection needs a Herdr pane, the configured `scout` Role, and the `fast` route. If it cannot start, the request stays unchanged; Main can use `subagent_status` to read state. See [Inspect and revise active work](./docs/orchestration.md#inspect-and-revise-active-work) for inspection and follow-up details.
 
 See [Status widgets](./docs/orchestration.md#status-widgets) for reference numbering, token counts, and activity metrics, and [Choose a delegation mode](./docs/orchestration.md#choose-a-delegation-mode) for routing guidance.
@@ -146,7 +150,7 @@ Package-owned: `~/.pi/agent/config/pi-subagent/config.json`. Missing files silen
 | `maxSubagents` | Concurrent direct workers and ephemeral children | Safe integer ≥ 1 | `5` |
 | `maxTurns` | Provider turns per child | Safe integer ≥ 1 | `50` |
 | `maxTokens` | Optional tokens per child | Safe integer ≥ 1 | Unlimited |
-| `maxCorrections` | Same-worker automatic corrections per isolated request | Safe integer ≥ 0 | `1` |
+| `maxCorrections` | Same-worker corrections per isolated request, including Main's `revise` and `retry` corrections | Safe integer ≥ 0 | `1` |
 | `timeout.idleMinutes` | Direct worker and ephemeral child idle timeout | Positive; within Node's timer range | `10` |
 | `timeout.maxMinutes` | Ephemeral child hard runtime | Greater than idle; within Node's timer range | `30` |
 | `roleDefaults` | Shared resources for built-in and user Roles | Object with `extensions`, `tools`, or `skills` arrays; same validation as Role fields | — |

package/dist/discard.d.ts

@@ -0,0 +1,51 @@
+import { type GitRunner } from "./git-process.ts";
+import type { ChangesetTaskAttempt, ChangesetTaskState, IntegrationGeneration, RunState, TextTaskAttempt } from "./schema.ts";
+import type { RunStateHandle } from "./store.ts";
+import { type WorktreeInfo } from "./worktree.ts";
+import type { PruneGuards } from "./prune.ts";
+export interface DiscardItem {
+    key: string;
+    identity: string;
+    path?: string;
+    branch?: string;
+    tip?: string;
+    checkout: boolean;
+    commits?: number;
+    dirty?: boolean;
+    ignored: string[];
+    hosts: string[];
+    blockers: string[];
+}
+export interface DiscardPlan {
+    root: string;
+    directory: string;
+    requestId: string;
+    items: DiscardItem[];
+}
+export interface DiscardGuards {
+    panes: PruneGuards["panes"];
+    blocked(): Promise<string | undefined>;
+    current(): boolean;
+}
+export interface DiscardResource {
+    key: string;
+    worktree?: Omit<WorktreeInfo, "baseCommit"> & {
+        baseCommit?: string;
+    };
+    textAttempt?: TextTaskAttempt;
+    task?: ChangesetTaskState;
+    attempt?: ChangesetTaskAttempt;
+    generation?: IntegrationGeneration;
+}
+export type DiscardRemoval = {
+    key: string;
+    outcome: "removed" | "skipped" | "failed";
+    reason: string;
+};
+export declare function discardResources(state: RunState): DiscardResource[];
+export declare function primaryCheckout(root: string, run?: GitRunner): Promise<string>;
+/** Read-only evidence. A resource is one worker attempt or integration generation, including its host resources. */
+export declare function inspectDiscardResource(primary: string, mainCwd: string, resource: DiscardResource, guards: DiscardGuards, run?: GitRunner): Promise<DiscardItem>;
+export declare function inspectDiscard(primary: string, mainCwd: string, state: RunState, guards: DiscardGuards): Promise<DiscardItem[]>;
+/** Called only after the command's confirmation. Never exposed as an agent tool. */
+export declare function removeDiscardResources(handle: RunStateHandle, primary: string, mainCwd: string, reviewed: readonly DiscardItem[], guards: DiscardGuards, close: (resource: DiscardResource, check: () => Promise<void>) => Promise<void>, run?: GitRunner): Promise<DiscardRemoval[]>;

package/dist/discard.js

@@ -0,0 +1,224 @@
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+import { runGit } from "./git-process.js";
+import { inspectIndexFlags, OWNED_BRANCH_PATTERN, WORKTREES_DIRNAME } from "./worktree.js";
+export function discardResources(state) {
+    return [
+        ...state.tasks.flatMap((task) => task.kind === "changeset" ? task.attempts.map((attempt, index) => ({
+            key: `task/${task.taskId}/${index + 1}`, task, attempt,
+            worktree: attempt.allocations.filter((item) => item.kind === "worktree").at(-1)?.worktree,
+        })) : task.attempts.flatMap((attempt) => attempt.cleanup ? [{
+                key: `task/${task.taskId}/${attempt.number}`, textAttempt: attempt,
+                worktree: { path: attempt.cleanup.path, cwd: attempt.cleanup.path, branch: attempt.cleanup.branch,
+                    repoRoot: dirname(dirname(attempt.cleanup.path)) },
+            }] : [])),
+        ...state.integration.generations.map((generation) => ({ key: `integration/${generation.number}`, generation, worktree: generation.worktree })),
+    ];
+}
+async function git(args, root, run) {
+    const result = await run(args, root);
+    if (result.code !== 0)
+        throw new Error(`git ${args[0]} failed: ${result.stderr.trim().slice(0, 300)}`);
+    return result.stdout.trimEnd();
+}
+export async function primaryCheckout(root, run = runGit) {
+    const first = (await git(["worktree", "list", "--porcelain", "-z"], root, run)).split("\0")[0];
+    if (!first?.startsWith("worktree "))
+        throw new Error("Primary Git checkout is unavailable.");
+    return realpathSync.native(first.slice(9));
+}
+const within = (root, path) => path === root || path.startsWith(`${root}${sep}`);
+const identity = (resource) => JSON.stringify([resource.worktree, resource.attempt?.allocations]);
+/** Read-only evidence. A resource is one worker attempt or integration generation, including its host resources. */
+export async function inspectDiscardResource(primary, mainCwd, resource, guards, run = runGit) {
+    const { worktree, attempt } = resource;
+    const allocations = attempt?.allocations ?? [];
+    const item = {
+        key: resource.key, identity: identity(resource), checkout: false, ignored: [], blockers: [],
+        hosts: allocations.filter((allocation) => allocation.kind !== "worktree").map((allocation) => JSON.stringify(allocation)),
+    };
+    const blocked = await guards.blocked();
+    if (blocked)
+        item.blockers.push(blocked);
+    if (allocations.some((allocation) => allocation.status === "allocating" || allocation.status === "unknown")) {
+        item.blockers.push("Allocation ownership is uncertain; inspect the recorded resources.");
+    }
+    if (!worktree)
+        return item;
+    item.path = worktree.path;
+    item.branch = worktree.branch;
+    if (!OWNED_BRANCH_PATTERN.test(worktree.branch) || worktree.repoRoot !== primary
+        || worktree.path !== join(primary, WORKTREES_DIRNAME, basename(worktree.branch))) {
+        item.blockers.push("Checkout or branch is not at this repository's owned path.");
+        return item;
+    }
+    const ref = `refs/heads/${worktree.branch}`;
+    const branches = (await git(["for-each-ref", "--format=%(refname) %(objectname) %(symref)", ref], primary, run)).split("\n");
+    const branch = branches.find((line) => line.startsWith(`${ref} `))?.split(" ");
+    item.tip = branch?.[1];
+    if (branch?.[2])
+        item.blockers.push("Owned branch is a symbolic reference; inspect it manually.");
+    if (item.tip && worktree.baseCommit)
+        item.commits = Number(await git(["rev-list", "--count", `${worktree.baseCommit}..${item.tip}`], primary, run));
+    const records = (await git(["worktree", "list", "--porcelain", "-z"], primary, run)).split("\0\0");
+    const registered = records.filter((record) => record.split("\0").includes(`branch refs/heads/${worktree.branch}`));
+    const owned = records.find((record) => record.startsWith(`worktree ${worktree.path}\0`));
+    if (registered.some((record) => !record.startsWith(`worktree ${worktree.path}\0`)))
+        item.blockers.push("Branch is checked out at another path.");
+    item.checkout = existsSync(worktree.path);
+    const cleanup = attempt?.cleanup ?? resource.generation?.cleanup;
+    if (item.checkout && (resource.textAttempt?.cleanup?.outcome === "pruned" || cleanup?.some((step) => step.kind === "worktree" && step.status === "completed"))
+        || item.tip && (resource.textAttempt?.cleanup?.outcome === "pruned" || cleanup?.some((step) => step.kind === "branch" && step.status === "completed"))) {
+        item.blockers.push("A resource exists after completed cleanup; new ownership is unproved.");
+    }
+    if (allocations.filter((allocation) => allocation.kind === "worktree").at(-1)?.status === "absent"
+        && (item.checkout || item.tip))
+        item.blockers.push("Allocation was recorded absent; ownership of the existing resource is unproved.");
+    if (owned && !item.checkout)
+        item.blockers.push("Checkout registration remains but its directory is missing; inspect it manually.");
+    if (!item.checkout)
+        return item;
+    if (!owned || !owned.split("\0").includes(`branch refs/heads/${worktree.branch}`))
+        item.blockers.push("Checkout registration changed or checkout is detached.");
+    if (owned?.split("\0").some((field) => field === "locked" || field.startsWith("locked ")))
+        item.blockers.push("Checkout is locked.");
+    const real = realpathSync.native(worktree.path);
+    if (real !== worktree.path)
+        item.blockers.push("Owned checkout path is redirected.");
+    if (within(real, realpathSync.native(mainCwd)))
+        item.blockers.push("Main runs inside the checkout.");
+    const status = (await git(["--no-optional-locks", "status", "--porcelain=v1", "-z", "--ignored=matching", "--untracked-files=normal", "--ignore-submodules=none"], worktree.path, run)).split("\0").filter(Boolean);
+    item.ignored = status.filter((entry) => entry.startsWith("!! ")).map((entry) => entry.slice(3));
+    item.dirty = status.some((entry) => !entry.startsWith("!! "));
+    if (!item.dirty) {
+        const flags = await inspectIndexFlags(worktree.path, run);
+        if (flags.failure || flags.hidden) {
+            delete item.dirty;
+            item.blockers.push(flags.failure ?? "Index flags hide tracked files; dirty state cannot be proved.");
+        }
+    }
+    const submodules = await git(["submodule", "status", "--recursive"], worktree.path, run);
+    if (submodules.split("\n").some((line) => line && !line.startsWith("-"))) {
+        item.blockers.push("Initialized submodules require separate inspection of their commits and ignored files.");
+    }
+    try {
+        const ownPanes = allocations.flatMap((allocation) => allocation.status !== "owned" ? []
+            : allocation.kind === "workspace" ? [allocation.rootPaneId]
+                : allocation.kind === "worker_tab" || allocation.kind === "agent" ? [allocation.paneId] : []);
+        const foreign = (await guards.panes()).filter((pane) => !ownPanes.includes(pane.paneId)
+            && pane.cwds.some((cwd) => within(real, cwd) || within(worktree.path, cwd)));
+        if (foreign.length)
+            item.blockers.push(`Other Herdr panes use this checkout: ${foreign.map((pane) => pane.paneId).join(", ")}`);
+    }
+    catch (error) {
+        item.blockers.push(`Herdr cannot be inspected: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return item;
+}
+export async function inspectDiscard(primary, mainCwd, state, guards) {
+    const items = [];
+    for (const resource of discardResources(state)) {
+        try {
+            const item = await inspectDiscardResource(primary, mainCwd, resource, guards);
+            const complete = resource.textAttempt?.cleanup?.outcome === "pruned"
+                || (resource.attempt?.cleanup ?? resource.generation?.cleanup)?.every((step) => step.status === "completed");
+            if (!complete || item.checkout || item.tip || item.blockers.length)
+                items.push(item);
+        }
+        catch (error) {
+            items.push({ key: resource.key, identity: identity(resource), path: resource.worktree?.path,
+                branch: resource.worktree?.branch, checkout: false, ignored: [], hosts: [], blockers: [`Inspection failed: ${String(error)}`] });
+        }
+    }
+    return items;
+}
+/** Called only after the command's confirmation. Never exposed as an agent tool. */
+export async function removeDiscardResources(handle, primary, mainCwd, reviewed, guards, close, run = runGit) {
+    const results = [];
+    const removals = [];
+    for (const item of reviewed) {
+        const resource = discardResources(handle.state).find((resource) => resource.key === item.key);
+        if (!resource || identity(resource) !== item.identity || item.blockers.length) {
+            results.push({ key: item.key, outcome: "skipped", reason: "Ownership changed or the reviewed item is blocked." });
+            continue;
+        }
+        let checkoutRemoved = false;
+        const verify = async () => {
+            if (!guards.current())
+                throw new Error("Session changed; reopen /subagent.");
+            const fresh = await inspectDiscardResource(primary, mainCwd, resource, guards, run);
+            if (fresh.blockers.length)
+                throw new Error(fresh.blockers.join("; "));
+            if (fresh.tip !== item.tip)
+                throw new Error("Branch was deleted or moved since review; branch kept.");
+            if (fresh.checkout !== (checkoutRemoved ? false : item.checkout))
+                throw new Error("Checkout changed since review.");
+            if (fresh.ignored.some((entry) => !item.ignored.includes(entry)))
+                throw new Error("Ignored entries changed since review.");
+            const blocked = await guards.blocked();
+            if (blocked)
+                throw new Error(blocked);
+            if (!guards.current())
+                throw new Error("Session changed; reopen /subagent.");
+        };
+        try {
+            await verify();
+        }
+        catch (error) {
+            results.push({ key: item.key, outcome: "skipped", reason: String(error) });
+            continue;
+        }
+        const failed = async (error) => {
+            const pending = (resource.attempt?.cleanup ?? resource.generation?.cleanup)?.find((step) => step.status === "running");
+            if (pending) {
+                pending.failure = `User-confirmed discard failed: ${String(error)}`.slice(0, 500);
+                await handle.save();
+            }
+            results.push({ key: item.key, outcome: "failed", reason: `${checkoutRemoved ? "Checkout removed; " : ""}${String(error)}` });
+        };
+        try {
+            await close(resource, verify);
+        }
+        catch (error) {
+            await failed(error);
+            continue;
+        }
+        // Close all reviewed workers and host resources before any Git checkout is removed.
+        removals.push(async () => {
+            try {
+                const pending = [{ kind: "worktree", status: "pending" }, { kind: "branch", status: "pending" }];
+                const steps = resource.attempt?.cleanup ?? (resource.generation ? resource.generation.cleanup ??= pending : pending);
+                for (const kind of ["worktree", "branch"]) {
+                    const step = steps.find((step) => step.kind === kind);
+                    await verify();
+                    if (step.status === "completed")
+                        continue;
+                    step.status = "running";
+                    delete step.failure;
+                    await handle.save();
+                    await verify();
+                    if (kind === "worktree" && item.checkout) {
+                        await git(["worktree", "remove", "--force", item.path], primary, run);
+                        checkoutRemoved = true;
+                    }
+                    else if (kind === "branch" && item.tip) {
+                        await git(["update-ref", "--no-deref", "-d", `refs/heads/${item.branch}`, item.tip], primary, run);
+                    }
+                    step.status = "completed";
+                    if (resource.textAttempt)
+                        resource.textAttempt.cleanup = kind === "branch"
+                            ? { outcome: "pruned", path: item.path, branch: item.branch }
+                            : { outcome: "recovery", path: item.path, branch: item.branch, note: "User confirmed discard: checkout removed; branch cleanup pending." };
+                    await handle.save();
+                }
+                results.push({ key: item.key, outcome: "removed", reason: "Reviewed resources removed; cleanup saved." });
+            }
+            catch (error) {
+                await failed(error);
+            }
+        });
+    }
+    for (const remove of removals)
+        await remove();
+    return results;
+}

package/dist/runner.d.ts

@@ -1,9 +1,10 @@
+import { type DiscardGuards, type DiscardPlan } from "./discard.ts";
 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. */
+/** One durable follow-up per attempt; this instruction permits a worker commit, never discarded work. */
 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;
@@ -305,6 +306,8 @@ export declare class IsolatedRunner {
             id: string;
             name: string;
             status: string;
+            directory: string;
+            root: string;
             tasks: Array<{
                 id: string;
                 name: string;
@@ -346,6 +349,25 @@ export declare class IsolatedRunner {
     private releaseSuperseded;
     private cleanupPromoted;
     private requireExactIntegration;
+    listOrphanRequests(cwd: string): Promise<{
+        invalidIds: string[];
+        requests: {
+            id: string;
+            name: string;
+            status: string;
+            directory: string;
+            root: string;
+            orphaned: boolean;
+            tasks: never[];
+        }[];
+    }>;
+    private discardGuards;
+    discardPlan(cwd: string, id: string, directory: string | undefined, guards: DiscardGuards): Promise<DiscardPlan>;
+    /** Command-only explicit discard. No tool calls this method. */
+    discard(cwd: string, plan: DiscardPlan, guards: DiscardGuards): Promise<import("./discard.ts").DiscardRemoval[]>;
+    private terminateAbortedAttempt;
+    private cleanupAbortedHost;
+    private closeDiscardResource;
     abort(id: string, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
     /** Read-only proof that every retained candidate checkout and staged integration checkout is already gone. */
     private retainedWorkAbsent;

package/dist/runner.js

@@ -1,4 +1,6 @@
 import { readFileSync, realpathSync } from "node:fs";
+import { dirname } from "node:path";
+import { inspectDiscard, primaryCheckout, removeDiscardResources } from "./discard.js";
 import { utf8Prefix } from "./ephemeral.js";
 import { createChildWorktree, finalizeChildWorktree, inspectWorktreeDirty } from "./worktree.js";
 import { runGit } from "./git-process.js";
@@ -11,7 +13,7 @@ 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. */
+/** One durable follow-up per attempt; this instruction permits a worker commit, never discarded work. */
 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;
@@ -422,6 +424,14 @@ function correctionEligible(request, attempt) {
 function terminal(state) {
     return state.status === "completed" || state.status === "final_failed" || state.status === "superseded" || state.status === "aborted";
 }
+function inventoryStatus(state) {
+    const retained = state.tasks.some((task) => task.kind === "changeset"
+        ? task.attempts.some((attempt) => attempt.cleanup.some((step) => step.status !== "completed"))
+        : task.attempts.some((attempt) => attempt.cleanup && attempt.cleanup.outcome !== "pruned"))
+        || state.integration.generations.some((generation) => generation.cleanup?.some((step) => step.status !== "completed")
+            || (generation.worktree && generation.cleanup?.every((step) => step.status === "completed") !== true));
+    return ["completed", "aborted"].includes(state.status) && retained ? `${state.status} · retained` : state.status;
+}
 /** Build one bounded changeset assignment. Call this before acquiring its Role launch. */
 export function buildChangesetTaskPrompt(input) {
     if (input.kind === "correction"
@@ -551,14 +561,9 @@ export class IsolatedRunner {
     }
     async listRequests(root) {
         const { states: entries, invalidIds } = await this.store.list(root);
-        return { invalidIds, states: entries.map(({ state }) => state), requests: entries.map(({ state }) => ({
-                id: state.request.id, name: state.request.goal,
-                status: ["completed", "aborted"].includes(state.status) && (state.tasks.some((task) => task.kind === "changeset"
-                    ? task.attempts.some((attempt) => attempt.cleanup.some((step) => step.status !== "completed"))
-                    : task.attempts.some((attempt) => attempt.cleanup && attempt.cleanup.outcome !== "pruned"))
-                    || state.integration.generations.some((generation) => generation.cleanup?.some((step) => step.status !== "completed")
-                        || (generation.worktree && generation.cleanup?.every((step) => step.status === "completed") !== true)))
-                    ? `${state.status} · retained` : state.status,
+        return { invalidIds, states: entries.map(({ state }) => state), requests: entries.map(({ state, path }) => ({
+                id: state.request.id, name: state.request.goal, directory: dirname(path), root: state.root,
+                status: inventoryStatus(state),
                 tasks: state.request.tasks.map((task) => ({
                     id: task.id, name: task.requirements, kind: task.kind,
                     status: state.tasks.find((item) => item.taskId === task.id).status,
@@ -1657,6 +1662,136 @@ export class IsolatedRunner {
         if (!sameIdentity(main, generation.expectedMain))
             throw new Error("Main changed or became dirty before promotion.");
     }
+    async listOrphanRequests(cwd) {
+        const primary = await primaryCheckout(cwd);
+        const { states, invalidIds } = await this.store.listOrphans(primary);
+        return { invalidIds, requests: states.map((handle) => ({
+                id: handle.state.request.id, name: handle.state.request.goal, status: inventoryStatus(handle.state),
+                directory: dirname(handle.path), root: handle.state.root, orphaned: true, tasks: [],
+            })) };
+    }
+    discardGuards(directory, root, guards) {
+        return { ...guards, blocked: async () => {
+                if (this.productiveLifecycles.has(root))
+                    return "A local productive job is active.";
+                if (await this.store.hasProductiveRunLeaseInDirectory(directory))
+                    return "A live productive lease owns this request root.";
+                return await guards.blocked();
+            } };
+    }
+    async discardPlan(cwd, id, directory, guards) {
+        const primary = await primaryCheckout(cwd);
+        directory ??= this.store.stateDirectory(realpathSync.native(cwd));
+        const handle = await this.store.loadFromDirectory(directory, id);
+        return { directory, root: handle.state.root, requestId: id, items: await inspectDiscard(primary, cwd, handle.state, this.discardGuards(directory, handle.state.root, guards)) };
+    }
+    /** Command-only explicit discard. No tool calls this method. */
+    async discard(cwd, plan, guards) {
+        const primary = await primaryCheckout(cwd);
+        return await this.store.withDirectoryLock(plan.directory, async () => {
+            const handle = await this.store.loadFromDirectory(plan.directory, plan.requestId);
+            const state = handle.state;
+            if (state.root !== plan.root)
+                throw new Error("Request root changed since review.");
+            const checked = this.discardGuards(plan.directory, state.root, guards);
+            const blocked = await checked.blocked();
+            if (blocked || !checked.current())
+                throw new Error(blocked ?? "Session changed; reopen /subagent.");
+            const removals = await removeDiscardResources(handle, primary, cwd, plan.items, checked, async (resource, verify) => {
+                await verify();
+                state.status = "aborted";
+                state.accepted = false;
+                delete state.acceptedAt;
+                if (state.final.status === "passed") {
+                    state.final.status = "superseded";
+                    state.final.failure = "User confirmed discard from /subagent.";
+                }
+                delete state.recovery;
+                state.updatedAt = this.coordinatorRuntime.now();
+                // Invalidate readiness before termination or supersession; rejected candidates retain exact accounting.
+                for (const candidate of state.integration.candidates) {
+                    candidate.decision = "rejected";
+                    const task = changesetTaskState(state, candidate.taskId);
+                    if (candidate.attempt !== task.attempts.length)
+                        continue;
+                    if (candidate.worker !== "retained") {
+                        task.status = "rejected";
+                        delete task.failure;
+                    }
+                    else
+                        this.attention(task, "User confirmed discard of this request.");
+                }
+                for (const generation of state.integration.generations) {
+                    if (generation.status === "superseded")
+                        continue;
+                    generation.status = "superseded";
+                    generation.supersededFrom = "discarded";
+                    generation.failure = "User confirmed discard from /subagent.";
+                    delete generation.promotion;
+                    delete generation.supersededPromotion;
+                    delete generation.combinedTip;
+                    delete generation.checks;
+                    delete generation.review;
+                }
+                await handle.save();
+                await this.closeDiscardResource(handle, resource, verify);
+            });
+            for (const candidate of state.integration.candidates) {
+                const task = changesetTaskState(state, candidate.taskId);
+                const attempt = task.attempts[candidate.attempt - 1];
+                if (candidate.decision !== "rejected" || attempt.termination?.status !== "terminated"
+                    || attempt.cleanup.some((step) => step.status !== "completed"))
+                    continue;
+                candidate.worker = "released";
+                if (attempt === task.attempts.at(-1)) {
+                    task.status = "rejected";
+                    delete task.failure;
+                }
+            }
+            await handle.save();
+            return removals;
+        });
+    }
+    async terminateAbortedAttempt(handle, task, attempt, signal, deadline = this.coordinatorRuntime.now() + TERMINATION_SAFETY_BUDGET_MS) {
+        if (!allocationByKind(attempt, "agent")?.agentName || attempt.termination?.status === "terminated")
+            return;
+        await this.proveTermination(handle, task, attempt, this.terminationCandidate(attempt), async () => await handle.save(), signal, deadline);
+    }
+    async cleanupAbortedHost(handle, task, attempt, kind, scope) {
+        const result = await scope.call((context) => this.hostRuntime.cleanupHost({
+            requestId: handle.state.request.id, kind, task: changesetTaskRequest(handle.state, task.taskId), attempt,
+        }, context));
+        if (result.outcome === "blocked")
+            throw new Error(result.failure);
+    }
+    async closeDiscardResource(handle, resource, verify) {
+        const { task, attempt } = resource;
+        if (!task || !attempt)
+            return;
+        await verify();
+        await this.terminateAbortedAttempt(handle, task, attempt);
+        if (allocationByKind(attempt, "agent") && attempt.termination?.status !== "terminated")
+            throw new Error("Worker termination remains unproved.");
+        const scope = new DeadlineScope(this.coordinatorRuntime.now() + CLEANUP_SAFETY_BUDGET_MS, () => this.coordinatorRuntime.now());
+        try {
+            for (const step of attempt.cleanup) {
+                if (step.kind !== "worker_tab" && step.kind !== "workspace" || step.status === "completed")
+                    continue;
+                await verify();
+                step.status = "running";
+                delete step.failure;
+                await handle.save();
+                await verify();
+                if (allocationByKind(attempt, step.kind))
+                    await this.cleanupAbortedHost(handle, task, attempt, step.kind, scope);
+                step.status = "completed";
+                await handle.save();
+            }
+        }
+        finally {
+            scope.close();
+        }
+    }
     async abort(id, root, outerSignal) {
         root = realpathSync.native(root);
         return await this.store.withLock(root, async (lifecycle) => {
@@ -1695,10 +1830,8 @@ export class IsolatedRunner {
                 if (task.kind !== "changeset")
                     continue;
                 for (const attempt of task.attempts) {
-                    if (!allocationByKind(attempt, "agent")?.agentName || attempt.termination?.status === "terminated")
-                        continue;
                     try {
-                        await this.proveTermination(handle, task, attempt, this.terminationCandidate(attempt), async () => await handle.save(), outerSignal, safetyDeadline);
+                        await this.terminateAbortedAttempt(handle, task, attempt, outerSignal, safetyDeadline);
                     }
                     catch (error) {
                         this.attention(task, errorText(error));
@@ -1767,12 +1900,7 @@ export class IsolatedRunner {
                             delete step.failure;
                             await handle.save();
                             if ((kind === "worker_tab" || kind === "workspace") && allocationByKind(attempt, kind)) {
-                                const result = await scope.call((context) => this.hostRuntime.cleanupHost({
-                                    requestId: state.request.id, kind,
-                                    task: changesetTaskRequest(state, task.taskId), attempt,
-                                }, context));
-                                if (result.outcome === "blocked")
-                                    throw new Error(result.failure);
+                                await this.cleanupAbortedHost(handle, task, attempt, kind, scope);
                             }
                             else if ((kind === "worktree" || kind === "branch") && worker && expected) {
                                 const result = await scope.call((context) => this.integrationGit.release(state.root, worker, expected, kind, context.signal));

package/dist/schema.d.ts

@@ -1430,7 +1430,7 @@ declare const IntegrationGenerationSchema: Type.TObject<{
         status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"completed">]>;
         failure: Type.TOptional<Type.TString>;
     }>>>;
-    supersededFrom: Type.TOptional<Type.TUnion<[Type.TLiteral<"staging">, Type.TLiteral<"conflict">, Type.TLiteral<"validation_failed">, Type.TLiteral<"ready">, Type.TLiteral<"promotion_failed">]>>;
+    supersededFrom: Type.TOptional<Type.TUnion<[Type.TLiteral<"staging">, Type.TLiteral<"conflict">, Type.TLiteral<"validation_failed">, Type.TLiteral<"ready">, Type.TLiteral<"promotion_failed">, Type.TLiteral<"discarded">]>>;
     failure: Type.TOptional<Type.TString>;
 }>;
 export declare const IntegrationStateSchema: Type.TObject<{
@@ -1670,7 +1670,7 @@ export declare const IntegrationStateSchema: Type.TObject<{
             status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"completed">]>;
             failure: Type.TOptional<Type.TString>;
         }>>>;
-        supersededFrom: Type.TOptional<Type.TUnion<[Type.TLiteral<"staging">, Type.TLiteral<"conflict">, Type.TLiteral<"validation_failed">, Type.TLiteral<"ready">, Type.TLiteral<"promotion_failed">]>>;
+        supersededFrom: Type.TOptional<Type.TUnion<[Type.TLiteral<"staging">, Type.TLiteral<"conflict">, Type.TLiteral<"validation_failed">, Type.TLiteral<"ready">, Type.TLiteral<"promotion_failed">, Type.TLiteral<"discarded">]>>;
         failure: Type.TOptional<Type.TString>;
     }>>;
     refresh: Type.TOptional<Type.TObject<{
@@ -2231,7 +2231,7 @@ declare const RunStateSchema: Type.TObject<{
                 status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"completed">]>;
                 failure: Type.TOptional<Type.TString>;
             }>>>;
-            supersededFrom: Type.TOptional<Type.TUnion<[Type.TLiteral<"staging">, Type.TLiteral<"conflict">, Type.TLiteral<"validation_failed">, Type.TLiteral<"ready">, Type.TLiteral<"promotion_failed">]>>;
+            supersededFrom: Type.TOptional<Type.TUnion<[Type.TLiteral<"staging">, Type.TLiteral<"conflict">, Type.TLiteral<"validation_failed">, Type.TLiteral<"ready">, Type.TLiteral<"promotion_failed">, Type.TLiteral<"discarded">]>>;
             failure: Type.TOptional<Type.TString>;
         }>>;
         refresh: Type.TOptional<Type.TObject<{

package/dist/schema.js

@@ -387,7 +387,7 @@ const IntegrationGenerationSchema = Type.Object({
     cleanup: Type.Optional(Type.Array(CleanupStepSchema, { minItems: 2, maxItems: 2 })),
     supersededFrom: Type.Optional(Type.Union([
         Type.Literal("staging"), Type.Literal("conflict"), Type.Literal("validation_failed"),
-        Type.Literal("ready"), Type.Literal("promotion_failed"),
+        Type.Literal("ready"), Type.Literal("promotion_failed"), Type.Literal("discarded"),
     ])),
     failure: OptionalRuntimeTextSchema,
 }, { additionalProperties: false });
@@ -978,6 +978,9 @@ export function parseRunState(value) {
     const state = value;
     const request = parseExecuteRequest(state.request);
     parseIntegrationState(state.integration, request);
+    if (state.status !== "aborted" && state.integration.generations.some((generation) => generation.supersededFrom === "discarded")) {
+        throw new Error("User-discarded generations require an aborted request.");
+    }
     const refresh = state.integration.refresh;
     if (refresh && (refresh.generation === 1 && !sameIdentity(refresh.from, state.requestStartMain)
         || (state.integration.generations.at(-1)?.status !== "promoted" && !sameIdentity(refresh.to, state.main)))) {

package/dist/store.d.ts

@@ -41,6 +41,16 @@ export declare class FileRunStore {
     withLock<T>(root: string, operation: (lifecycle: LifecycleLock) => Promise<T>, options?: LifecycleLockOptions): Promise<T>;
     create(state: RunState): Promise<RunStateHandle>;
     load(root: string, id: string): Promise<RunStateHandle>;
+    /** Address saved state without resolving a parent checkout that may no longer exist. */
+    private validateDirectory;
+    loadFromDirectory(directory: string, id: string): Promise<RunStateHandle>;
+    hasProductiveRunLeaseInDirectory(directory: string): Promise<boolean>;
+    withDirectoryLock<T>(directory: string, operation: () => Promise<T>): Promise<T>;
+    /** Missing roots only; repoRoot records the stable primary checkout, not the removed parent. */
+    listOrphans(primary: string): Promise<{
+        states: RunStateHandle[];
+        invalidIds: string[];
+    }>;
     private stateEntries;
     /** Read only version and request status; never migrate or interpret v4 worker evidence. */
     assertLegacyAdmissionSafe(root: string): Promise<void>;

package/dist/store.js

@@ -5,6 +5,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { extensionConfigDir, readTextFileBounded, writePrivateTextFileAtomically } from "@henryqw/pi-config-store";
 import { check, lock } from "proper-lockfile";
 import { parseRunState, RUN_STATE_VERSION } from "./schema.js";
+import { discardResources } from "./discard.js";
 const INITIAL_STATE_MAX_BYTES = 2 * 1024 * 1024;
 /*
  * create() caps the complete initial serialization at 2 MiB. Loaded requests
@@ -117,7 +118,7 @@ export class FileRunStore {
         return join(this.stateDirectory(root), "productive-run");
     }
     async assertSafeDestination(root, destination) {
-        if (isWithin(realpathSync.native(root), await canonicalPlannedPath(destination))) {
+        if (isWithin(await canonicalPlannedPath(root), await canonicalPlannedPath(destination))) {
             throw new Error("Pi Subagent state directory must be outside the Git workspace.");
         }
     }
@@ -216,6 +217,91 @@ export class FileRunStore {
         }
         return this.handle(state, path);
     }
+    /** Address saved state without resolving a parent checkout that may no longer exist. */
+    async validateDirectory(directory) {
+        const parent = join(extensionConfigDir("pi-subagent", this.agentDir), "state");
+        if (dirname(directory) !== parent || !/^[a-f0-9]{64}$/.test(basename(directory))
+            || !(await lstat(directory)).isDirectory() || await realpath(directory) !== join(await realpath(parent), basename(directory))) {
+            throw new Error("Invalid Pi Subagent state directory.");
+        }
+    }
+    async loadFromDirectory(directory, id) {
+        await this.validateDirectory(directory);
+        if (basename(id) !== id || !id || id === "." || id === "..")
+            throw new Error("Invalid request ID.");
+        const path = join(directory, `${id}.json`);
+        if (!(await lstat(path)).isFile())
+            throw new Error("State is not a regular file.");
+        const state = parseRunState(JSON.parse(await readTextFileBounded(path, STATE_MAX_BYTES)));
+        if (state.request.id !== id || !isAbsolute(state.root)
+            || createHash("sha256").update(state.root).digest("hex") !== basename(directory)) {
+            throw new Error("pi-subagent state identity does not match its directory and filename.");
+        }
+        await this.assertSafeDestination(state.root, path);
+        return this.handle(state, path);
+    }
+    async hasProductiveRunLeaseInDirectory(directory) {
+        await this.validateDirectory(directory);
+        const path = join(directory, "productive-run");
+        return await check(path, { realpath: false, stale: LOCK_OPTIONS.stale, lockfilePath: `${path}.lock` });
+    }
+    async withDirectoryLock(directory, operation) {
+        await this.validateDirectory(directory);
+        const path = join(directory, "lifecycle.lock");
+        const release = await lock(path, { ...LIFECYCLE_LOCK_OPTIONS, lockfilePath: `${path}.lock` });
+        try {
+            return await operation();
+        }
+        finally {
+            await release();
+        }
+    }
+    /** Missing roots only; repoRoot records the stable primary checkout, not the removed parent. */
+    async listOrphans(primary) {
+        const parent = join(extensionConfigDir("pi-subagent", this.agentDir), "state");
+        let directories;
+        try {
+            directories = await readdir(parent, { withFileTypes: true });
+        }
+        catch (error) {
+            if (isMissing(error))
+                return { states: [], invalidIds: [] };
+            throw error;
+        }
+        const states = [];
+        const invalidIds = [];
+        for (const entry of directories) {
+            const directory = join(parent, entry.name);
+            try {
+                await this.validateDirectory(directory);
+                for (const file of await readdir(directory)) {
+                    if (!file.endsWith(".json"))
+                        continue;
+                    try {
+                        const handle = await this.loadFromDirectory(directory, file.slice(0, -5));
+                        try {
+                            await lstat(handle.state.root);
+                            continue;
+                        }
+                        catch (error) {
+                            if (!isMissing(error))
+                                throw error;
+                        }
+                        const worktrees = discardResources(handle.state).flatMap((resource) => resource.worktree ? [resource.worktree] : []);
+                        if (worktrees.length && worktrees.every((item) => item.repoRoot === primary))
+                            states.push(handle);
+                    }
+                    catch {
+                        invalidIds.push(join(directory, file));
+                    }
+                }
+            }
+            catch {
+                invalidIds.push(directory);
+            }
+        }
+        return { states, invalidIds };
+    }
     async stateEntries(root) {
         try {
             return (await readdir(this.stateDirectory(root), { withFileTypes: true }))

package/docs/orchestration.md

@@ -251,6 +251,8 @@ After readiness, use `subagent_stage revise` with the exact candidate, generatio
 
 To select work by label, open `/subagent` without arguments. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout. This includes requests launched in other sessions. Select an isolated request. Then select **Inspect status and recovery**.
 
+The menu also shows **Isolated · orphaned** requests whose saved parent checkout no longer exists. You can open this view from any checkout of the same repository. The saved worker or integration path identifies the primary repository. Orphaned requests have the same **Close and delete worktrees (discard work)** action, but no inspection or follow-up actions. The extension reads their original state directories; it does not recreate the removed parent checkout. Unreadable files stay preserved and are reported.
+
 This launches a Herdr tab without focus, with the configured `scout` Role on the configured `fast` route. The tab runs a read-access task with the resources of the Role. Its prompt contains bounded saved status, including retained paths, but not the raw launch environment or session transcripts. The analysis stays in that tab and does not queue a Main turn. The tab shows in the direct list with its own reference and name, such as `D9.1 · scout · Inspect <request ID>`. The extension records the tab and session file for recovery, even if the launch becomes uncertain.
 
 Before any stage or recovery action, the read-only `subagent_status` tool stays Main's authority for exact identities. If Herdr, the `scout` Role, or the fast route is not available, inspection fails and does not change the request. Main can then use `subagent_status`.
@@ -357,6 +359,20 @@ If another productive run holds the lease, the command only reads status and rep
 
 Main uses `subagent_status` for exact identities. Main uses the recovery tools in the interface table above for deliberate decisions. The command never stages or promotes. Direct Herdr tab recovery stays in `/subagent`.
 
+### Close and delete isolated worktrees
+
+Open `/subagent`, select an isolated request, then select **Close and delete worktrees (discard work)**. This is a user action, not an agent tool. Without interactive UI, `/subagent` only reports requests.
+
+The read-only review groups resources by worker attempt or integration generation. It shows each recorded checkout path, branch, tip, commits ahead of the recorded base, dirty state, ignored entries, and Herdr resources. Text attempts do not save their base; their commit count is shown as unknown. The review also includes owned branches with no checkout. If a complete resource group does not fit, the report gives the number of groups not shown. Those groups are not removed.
+
+One confirmation permits permanent deletion of committed, uncommitted, and ignored content in the listed checkouts. It also permits closure of the listed Herdr tabs and workspaces. Cancel makes no change. The command uses the existing abort termination and host cleanup paths before forced checkout removal. It deletes a branch only at its reviewed tip. It saves each completed cleanup step.
+
+Each resource is checked again before removal. A live productive lease or local job blocks the action. Uncertain allocations, changed branch tips, locked or redirected checkouts, and other Herdr panes inside a checkout block that resource. Initialized submodules and index flags that hide clean-state evidence also require separate inspection. If Herdr cannot be inspected, checkouts stay in place.
+
+Main cannot run inside a checkout selected for deletion. A session change stops further removal. Only this request's recorded `pi-subagent/subagent-<24hex>` branches and their exact primary `.worktrees/` paths can be removed. The primary checkout is never removed.
+
+The report lists removed, skipped, and failed resources. After complete cleanup, the request is `aborted`, candidates are `released`, and integration generations are superseded with completed cleanup. Partial cleanup remains visible as retained work. Reopen the request to review the remaining resources. Abort, prune, and release keep their existing preservation rules.
+
 ### Prune leftover worktrees
 
 Run `/subagent prune` to clean up leftover worker and integration checkouts under `.worktrees/`. Their branches have the name `pi-subagent/subagent-` plus 24 hex characters. The command also cleans up such branches that have no checkout. The review lists each item with its path, branch, and tip. For each item, it also shows why the command can remove the item, or it shows every exact blocker. The command can remove an item only when all of these conditions are true:

package/extensions/isolated.ts

@@ -38,7 +38,8 @@ import {
 } from "../dist/schema.js";
 import { FileRunStore } from "../dist/store.js";
 import { workerOutputForMain } from "./result-transport.ts";
-import type { IsolatedInventory, PrunePlan } from "./subagent-command.ts";
+import type { IsolatedInventory, IsolatedRequest, PrunePlan } from "./subagent-command.ts";
+import type { DiscardPlan } from "../dist/discard.js";
 
 const LOOKUP_ROOT_TIMEOUT_MS = 5_000;
 const PUBLIC_EVIDENCE_MAX_BYTES = 512;
@@ -471,6 +472,8 @@ export interface IsolatedSurface {
 	inventory(cwd: string, current?: () => boolean): Promise<IsolatedInventory>;
 	recover(cwd: string): Promise<string>;
 	prunePlan(cwd: string): Promise<PrunePlan>;
+	discardPlan(cwd: string, request: IsolatedRequest): Promise<DiscardPlan>;
+	discard(cwd: string, plan: DiscardPlan, current: () => boolean): Promise<string>;
 	prune(cwd: string, items: readonly PruneItem[], allowIgnored: boolean, current: () => boolean): Promise<string>;
 	inspect(root: string, requestId: string): Promise<readonly string[]>;
 	canFollowup(root: string, requestId: string, taskId: string): boolean;
@@ -790,7 +793,8 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 				try { renderWorkspaceWidget(latestContext(), workspaceRowsByRequest); }
 				catch (error) { console.error("Pi Subagent workspace widget update failed.", error); }
 			}
-			return { root, requests, invalidIds };
+			const orphans = await getComponents().runner.listOrphanRequests(root);
+			return { root, requests: [...requests, ...orphans.requests], invalidIds: [...new Set([...invalidIds, ...orphans.invalidIds])] };
 		},
 		async recover(cwd) {
 			const root = await lookupRoot(cwd);
@@ -823,6 +827,22 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			];
 			return boundedReport(lines, "recovery report lines omitted; use subagent_status for exact request evidence.");
 		},
+		async discardPlan(cwd, request) {
+			return await getComponents().runner.discardPlan(cwd, request.id, request.directory, {
+				panes: () => listHerdrPanes(cwd), current: () => !sessionClosed,
+				blocked: async () => jobOwners.has(`${request.root}\0${request.id}`) ? "A local job is active for this request." : undefined,
+			});
+		},
+		async discard(cwd, plan, current) {
+			requireCurrent(current);
+			const removals = await getComponents().runner.discard(cwd, plan, {
+				panes: () => listHerdrPanes(cwd), current: () => current() && !sessionClosed,
+				blocked: async () => jobOwners.has(`${plan.root}\0${plan.requestId}`) ? "A local job is active for this request." : undefined,
+			});
+			return boundedReport([`Close and delete ${plan.requestId}:`,
+				...removals.map((item) => `${item.outcome}: ${item.key}: ${item.reason}`),
+			], "removal report lines omitted; reopen /subagent to inspect retained resources.");
+		},
 		async prunePlan(cwd) {
 			const root = await lookupRoot(cwd);
 			return { root, items: await inspectPruneCandidates(root, cwd, pruneGuards(root)) };

package/extensions/subagent-command.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { DiscardPlan } from "../dist/discard.js";
 
 /** Saved before launch for user matching only; never ownership or mutation authority. */
 export interface DirectDisplay {
@@ -39,6 +40,10 @@ export interface IsolatedTask {
 }
 export interface IsolatedRequest {
 	id: string;
+	/** Saved state address for a removed parent checkout. */
+	directory?: string;
+	root?: string;
+	orphaned?: boolean;
 	name: string;
 	status: string;
 	tasks: readonly IsolatedTask[];
@@ -75,6 +80,8 @@ export interface SubagentCommandAdapter {
 	recover(cwd: string): Promise<string>;
 	/** Read-only review of pi-subagent worktrees and branches in the canonical repository. */
 	prunePlan(cwd: string): Promise<PrunePlan>;
+	discardPlan(cwd: string, request: IsolatedRequest): Promise<DiscardPlan>;
+	discard(cwd: string, plan: DiscardPlan, current: () => boolean): Promise<string>;
 	/** Re-verify and remove reviewed prunable items; returns a bounded report. */
 	prune(cwd: string, items: readonly PruneItem[], allowIgnored: boolean, current: () => boolean): Promise<string>;
 	/** Read-only Role catalog report with routes and per-file load errors. */
@@ -99,11 +106,11 @@ const PRUNE_IGNORED_CONFIRM_CODE_POINTS = 4_000;
 const NOT_SHOWN = "they are not removed in this run; run /subagent prune again after this run.";
 
 /** Fit whole item lines within `max` code points; never cut silently, and report exactly which items were shown. */
-function fitItems<T>(header: string, items: readonly T[], line: (item: T) => string, max: number): { text: string; shown: T[] } {
+function fitItems<T>(header: string, items: readonly T[], line: (item: T) => string, max: number, omitted = NOT_SHOWN): { text: string; shown: T[] } {
 	const lines = [header];
 	const shown: T[] = [];
 	let size = [...header].length;
-	const reserve = [...NOT_SHOWN].length + 32;
+	const reserve = [...omitted].length + 32;
 	for (const item of items) {
 		const text = line(item);
 		const length = [...text].length + 1;
@@ -112,7 +119,7 @@ function fitItems<T>(header: string, items: readonly T[], line: (item: T) => str
 		size += length;
 		shown.push(item);
 	}
-	if (shown.length < items.length) lines.push(`+${items.length - shown.length} more not shown; ${NOT_SHOWN}`);
+	if (shown.length < items.length) lines.push(`+${items.length - shown.length} more not shown; ${omitted}`);
 	return { text: lines.join("\n"), shown };
 }
 
@@ -126,6 +133,18 @@ function pruneReview({ root, items }: PrunePlan): { text: string; shown: PruneIt
 		ROLES_REPORT_CODE_POINTS);
 }
 
+function discardReview(plan: DiscardPlan) {
+	if (!plan.items.length) return { text: `No remaining owned resources for ${plan.requestId}.`, shown: [] };
+	return fitItems(`Close and delete request ${plan.requestId}:`, plan.items, (item) => clean([
+		`${item.key}: ${item.blockers.length ? `blocked: ${item.blockers.join("; ")}` : "can delete"}`,
+		`path: ${item.path ?? "none"}; checkout: ${item.checkout ? "yes" : "no"}; branch: ${item.branch ?? "none"}; tip: ${item.tip ?? "none"}`,
+		`commits ahead of recorded base: ${item.commits ?? "unknown"}; dirty: ${item.dirty === undefined ? "not inspected" : item.dirty ? "yes" : "no"}`,
+		`ignored entries (including all content inside them): ${item.ignored.length ? item.ignored.join(", ") : "none"}`,
+		`Herdr resources: ${item.hosts.length ? item.hosts.join("; ") : "none"}`,
+	].join("\n"), Number.MAX_SAFE_INTEGER, true), ROLES_REPORT_CODE_POINTS,
+	"they are not removed; reopen this request to review them.");
+}
+
 type Choice<T> = { label: string; value: T };
 async function choose<T>(ctx: ExtensionContext, title: string, items: readonly Choice<T>[]): Promise<T | undefined> {
 	// Numeric suffixes are UI-only. Never parse display text into an identity.
@@ -147,7 +166,7 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				else pi.sendMessage({ customType: "pi-subagent-roles", content: report, display: true });
 				return;
 			}
-			if (!command && !ctx.hasUI) throw new Error("/subagent requires interactive UI (TUI or RPC); use the subagent agent tools in non-interactive mode.");
+
 			const manager = ctx.sessionManager;
 			const session = manager.getSessionId();
 			const file = manager.getSessionFile();
@@ -207,6 +226,14 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				} catch (error) { if (valid()) ctx.ui.notify(`Prune failed: ${errorText(error)}`, "error"); }
 				return;
 			}
+			if (!ctx.hasUI) {
+				const inventory = await adapter.isolated(ctx.cwd, current);
+				const report = fitItems("Isolated requests (report only):", inventory.requests,
+					(request) => clean(`${request.orphaned ? "orphaned · " : ""}${request.name} · ${request.status} · ${request.id}`, 500), ROLES_REPORT_CODE_POINTS,
+					"open /subagent with interactive UI to inspect them.");
+				pi.sendMessage({ customType: "pi-subagent-discard", content: `${report.text}\nUnreadable state files preserved: ${inventory.invalidIds.length}.\nRemoval requires interactive confirmation.`, display: true });
+				return;
+			}
 			let history = false;
 			for (;;) {
 				if (!valid()) return;
@@ -223,7 +250,7 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				const selections: Choice<Selection>[] = [
 					// One row per workflow; new records keep opaque IDs in details. Status is last so clipping preserves the reference.
 					...direct.filter((task) => history || !completed(task.status)).map((task) => ({ label: `Direct · ${directLabel(task)} · ${task.status}${task.workers.length || task.name === task.id ? "" : ` · ${task.id}`}`, value: { kind: "direct" as const, task } })),
-					...(inventory?.requests ?? []).filter((request) => history || !completed(request.status) || /retained/i.test(request.status)).map((request) => ({ label: `Isolated · ${request.name} · ${request.status} · ${request.id}`, value: { kind: "isolated" as const, request, root: inventory!.root } })),
+					...(inventory?.requests ?? []).filter((request) => request.orphaned || history || !completed(request.status) || /retained/i.test(request.status)).map((request) => ({ label: `Isolated · ${request.orphaned ? "orphaned · " : ""}${request.name} · ${request.status} · ${request.id}`, value: { kind: "isolated" as const, request, root: inventory!.root } })),
 					{ label: "Refresh", value: { kind: "refresh" as const } },
 					{ label: history ? "Active work" : "Completed / history (including retained work)", value: { kind: "history" as const } },
 					{ label: "Close", value: { kind: "close" as const } },
@@ -275,16 +302,35 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				const { root, request } = selected;
 				for (;;) {
 					if (!valid()) return;
-					type Action = "inspect" | "send" | "edit" | "back";
+					type Action = "inspect" | "send" | "edit" | "discard" | "back";
 					const eligible = request.tasks.filter((task) => task.kind === "changeset" && adapter.canFollowup(root, request.id, task.id));
 					const actions: Choice<Action>[] = [
-						{ label: "Inspect status and recovery", value: "inspect" },
+						...(!request.orphaned ? [{ label: "Inspect status and recovery", value: "inspect" as const }] : []),
+						{ label: "Close and delete worktrees (discard work)", value: "discard" },
 						...(eligible.length ? [{ label: "Send follow-up instructions", value: "send" as const }, { label: "Edit queued instructions (withdraw ALL pending; Cancel leaves withdrawn)", value: "edit" as const }] : []),
 						{ label: "Back / refresh", value: "back" },
 					];
 					const action = await choose(ctx, `Isolated · ${clean(request.name)} · ${request.id}`, actions);
 					if (!valid() || !action) return;
 					if (action === "back") break;
+					if (action === "discard") {
+						try {
+							const plan = await adapter.discardPlan(ctx.cwd, request);
+							const reviewed = discardReview(plan);
+							if (!valid()) return;
+							ctx.ui.notify(reviewed.text, "warning");
+							const items = reviewed.shown.filter((item) => !item.blockers.length);
+							if (!items.length) continue;
+							const confirmed = await ctx.ui.confirm("Close and delete worktrees (discard work)",
+								`Stop the listed workers and delete the ${items.length} unblocked resource group(s) shown above? Committed, uncommitted, and ignored content in the listed checkouts is permanently deleted. Their listed branches, Herdr tabs, and workspaces are removed. Items not shown or blocked are kept.`);
+							if (!valid()) return;
+							if (confirmed) {
+								const report = await adapter.discard(ctx.cwd, { ...plan, items }, current);
+								if (valid()) ctx.ui.notify(clean(report, ROLES_REPORT_CODE_POINTS, true), "info");
+							}
+						} catch (error) { if (valid()) ctx.ui.notify(`Close and delete failed: ${errorText(error)}`, "error"); }
+						break;
+					}
 					if (action === "inspect") {
 						try {
 							const tab = await adapter.inspectInTab(root, request.id, ctx, current);

package/extensions/subagent.ts

@@ -331,6 +331,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		isolated: isolatedSurface.inventory,
 		recover: (cwd) => isolatedSurface.recover(cwd),
 		prunePlan: (cwd) => isolatedSurface.prunePlan(cwd),
+		discardPlan: (cwd, request) => isolatedSurface.discardPlan(cwd, request),
+		discard: (cwd, plan, current) => isolatedSurface.discard(cwd, plan, current),
 		prune: (cwd, items, allowIgnored, current) => isolatedSurface.prune(cwd, items, allowIgnored, current),
 		async inspectInTab(root, id, ctx, current) {
 			const notices = await isolatedSurface.inspect(root, id);

package/package.json

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

package/skills/pi-subagent/SKILL.md

@@ -32,10 +32,10 @@ To build on a finished direct worker, add `continueFrom` with its reference (suc
 
 Give the request a unique ID and goal. Give each task a unique ID, kind, Role, model class, bounded requirements, deliverable, `dependsOn`, and `contextFrom`. Changesets require focused task checks, and a graph containing changesets requires final checks. The root must have a `package.json` test script; `pnpm test` is added to final checks if missing and runs against the combined tip before Main promotion. Text context may name only completed text tasks, preserves declared order, and implies a scheduling dependency; do not repeat an edge in `dependsOn` and `contextFrom`.
 
-Every changeset advances automatically after preliminary checks pass. While a locally owned changeset task is actively working, the user may open `/subagent` to queue bounded same-worker revisions or withdraw all still-pending instructions into the native editor and submit one replacement. Cancellation after withdrawal leaves the originals removed; already-claimed instructions cannot be recalled. Each revision must produce a new clean commit and rerun preliminary checks. If a worker's turn ends with uncommitted changes, the runner sends it one commit reminder per attempt; this uses no correction, and a worktree still dirty afterwards needs attention. When no queued revision remains, the runner seals and durably records the exact ready candidate without waiting for sibling workers. There is no guaranteed post-completion editing window, and late follow-ups fail visibly.
+Every changeset becomes ready automatically after preliminary checks pass. While a locally owned changeset task is actively working, the user may open `/subagent` to queue bounded same-worker revisions or withdraw all still-pending instructions into the native editor and submit one replacement. Cancellation after withdrawal leaves the originals removed; already-claimed instructions cannot be recalled. Each revision must produce a new clean commit and rerun preliminary checks. If a worker's turn ends with uncommitted changes, the runner sends it one commit reminder per attempt; this uses no correction, and a worktree still dirty afterwards needs attention. When no queued revision remains, the runner seals and durably records the exact ready candidate without waiting for sibling workers. There is no guaranteed post-completion editing window, and late follow-ups fail visibly.
 
 A ready candidate does not integrate automatically. Each checked worker triggers a follow-up while its siblings continue; inspect `subagent_status` and immediately use `subagent_stage` with the exact `generation`, `taskId`, `attempt`, candidate `tip`, and `expectedTip` to select and merge it into the owned integration checkout. Stage and resolve are available during the active wave; wait for the wave to settle before rejecting or revising. Resolve conflicts in the integration checkout and verify with `resolve`; never edit Main to resolve them. For dependents, `subagent_integrate advance` acknowledges a durable background wave, then reports checked candidates as they finish. When selected work is staged and the wave settles, use `subagent_integrate validate` on the exact `combinedTip`: it acknowledges saved intent, runs full root checks and optional final judgment in the session-owned background, then sends a follow-up. Acknowledgement is not passing evidence; `promote` requires passing evidence and unchanged Main. One Main-authored committed correction to a definitively failed combined validation can be recorded with `correct`, then revalidated. Only proven promotion triggers selected-worker termination and verified cleanup. Failures, ambiguity, conflicts, interruption, child-limit exhaustion, or Main drift retain work and never waive checks or identity guards. The extension never pushes, opens a pull request, publishes, or deploys.
 
-After a coordinator interruption in the canonical repository, ask the user to run `/subagent recover` once: it acquires the productive lease, classifies orphaned interruptions, preserves invalid files and retained work, and sends Main one follow-up with blockers and next actions. A live productive lease is read-only and cannot be taken over. Recovery never replays prompts, merges, promotion, or cleanup. For leftover merged worker or integration checkouts, ask the user to run `/subagent prune`; it removes only reviewed, confirmed, merged, clean, unowned items. Use `subagent_status` to inspect exact durable state without mutation, including candidate identities, generations, and retained resources. `subagent_resume` handles only the reported retry/verify/finalize continuation; it cannot replace Main's stage/integrate decisions or reset policy/corrections. For a retry that sends a same-worker correction, pass `instruction` to name the exact fixes, including the review or check findings the worker must address; the correction prompt carries only a short saved failure. Follow-ups show a short preview of a failed review verdict; `subagent_status` returns it in full. `subagent_stage reject` or `revise` freezes a generation containing the candidate and invalidates dependent attempts; restage chosen work in a new generation. If Main advances cleanly before promotion, use `subagent_integrate refresh` with exact old/new Main and combined-tip identities; restage immutable candidates into the new generation and rerun combined validation. Dirty or divergent Main blocks refresh. For interrupted validation, prove old coordinator/check processes stopped, then guarded `reconcile` classifies the exact generation; never resume a live lease. A `validation_failed` generation without checks, review, or a prior combined correction can `refresh` with identical `expectedMain`/`newMain`, the old exact combined `expectedTip`, and the next generation number. Main and the retained integration tip must be exact and clean. Restage immutable candidates explicitly and rerun all final gates in the new checkout; never replay old uncertain checks, infer passing evidence, or reset correction allowances. At most two unreleased integration worktrees may coexist. Rejected candidates and superseded generations remain retained until Main explicitly calls `subagent_integrate release` with the exact generation and tip; for a rejected worker include its task ID and attempt after releasing all generations using it. Dirty/conflicted or unproved resources block release without force deletion. Impossible fresh dependent work after rejection needs a new request. `subagent_abort` cannot discard retained candidates or integration generations; release them first. For workers without candidates, abort cleans only proven unchanged, clean owned resources. If cleanup is deferred or blocked, inspect status and repeat abort after resolving the blocker. Dirty or committed work and uncertain allocations remain for manual recovery. Old v4 state is rejected (current state is v5), not migrated. Status, abort, process I/O, termination, and verified post-promotion cleanup keep finite safety budgets.
+After a coordinator interruption in the canonical repository, ask the user to run `/subagent recover` once; if another productive run holds the lease, wait and run it again. It acquires the productive lease, classifies orphaned interruptions, preserves invalid files and retained work, and sends Main one follow-up with blockers and next actions. A live productive lease is read-only and cannot be taken over. Recovery never replays prompts, merges, promotion, or cleanup. For leftover merged worker or integration checkouts, ask the user to run `/subagent prune`; it removes only reviewed, confirmed, merged, clean, unowned items. Use `subagent_status` to inspect exact durable state without mutation, including candidate identities, generations, and retained resources. `subagent_resume` handles only the reported retry/verify/finalize continuation; it cannot replace Main's stage/integrate decisions or reset policy/corrections. For a retry that sends a same-worker correction, pass `instruction` to name the exact fixes, including the review or check findings the worker must address; the correction prompt carries only a short saved failure. Follow-ups show a short preview of a failed review verdict; `subagent_status` returns it in full. `subagent_stage reject` or `revise` freezes a generation containing the candidate and invalidates dependent attempts; restage chosen work in a new generation. If Main advances cleanly before promotion, use `subagent_integrate refresh` with exact old/new Main and combined-tip identities; restage immutable candidates into the new generation and rerun combined validation. Dirty or divergent Main blocks refresh. For interrupted validation, prove old coordinator/check processes stopped, then guarded `reconcile` classifies the exact generation; never resume a live lease. A `validation_failed` generation without checks, review, or a prior combined correction can `refresh` with identical `expectedMain`/`newMain`, the old exact combined `expectedTip`, and the next generation number. Main and the retained integration tip must be exact and clean. Restage immutable candidates explicitly and rerun all final gates in the new checkout; never replay old uncertain checks, infer passing evidence, or reset correction allowances. At most two unreleased integration worktrees may coexist. Rejected candidates and superseded generations remain retained until Main explicitly calls `subagent_integrate release` with the exact generation and tip; for a rejected worker include its task ID and attempt after releasing all generations using it. Dirty/conflicted or unproved resources block release without force deletion. Impossible fresh dependent work after rejection needs a new request. `subagent_abort` cannot discard retained candidates or integration generations; release them first. For workers without candidates, abort cleans only proven unchanged, clean owned resources. If cleanup is deferred or blocked, inspect status and repeat abort after resolving the blocker. Dirty or committed work and uncertain allocations remain for manual recovery. Old v4 state is rejected (current state is v5), not migrated. Status, abort, process I/O, termination, and verified post-promotion cleanup keep finite safety budgets.
 
 All launches use the global policy in `config/pi-subagent/config.json`: productive concurrency, per-child turns/tokens, and idle timeout. Ephemeral children also have a hard runtime limit; isolated requests have a correction cap. Productive requests have no whole-run wall-clock deadline. Request fields cannot replenish or override limits.