@henryqw/pi-subagent 27.0.0 → 27.1.1

package/extensions/isolated.ts

@@ -1,3 +1,4 @@
+import { basename } from "node:path";
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
@@ -12,6 +13,7 @@ import {
 	type DirectProcessRunner,
 } from "../dist/git-runtime.js";
 import { HerdrHostRuntime } from "../dist/herdr-runtime.js";
+import { inspectPruneCandidates, listHerdrPanes, removePruneCandidates, type PruneGuards, type PruneItem } from "../dist/prune.js";
 import { runProcess as directRunProcess } from "../dist/process.js";
 import { RoleLaunchRuntime, type LaunchRuntimeOptions } from "../dist/launch-runtime.js";
 import { IsolatedRunner, type OperationContext, type RunResponse } from "../dist/runner.js";
@@ -36,10 +38,12 @@ import {
 } from "../dist/schema.js";
 import { FileRunStore } from "../dist/store.js";
 import { workerOutputForMain } from "./result-transport.ts";
-import type { IsolatedInventory } from "./subagent-command.ts";
+import type { IsolatedInventory, PrunePlan } from "./subagent-command.ts";
 
 const LOOKUP_ROOT_TIMEOUT_MS = 5_000;
 const PUBLIC_EVIDENCE_MAX_BYTES = 512;
+/** Tool results return failed review verdicts in full up to this bound; follow-ups keep the short preview. */
+const PUBLIC_REVIEW_VERDICT_MAX_BYTES = 32 * 1024;
 const WORKSPACE_WIDGET_KEY = "pi-subagent-workspaces";
 const WIDGET_FIELD_MAX_CHARS = 32;
 const MAX_WORKSPACE_WIDGET_LINES = 6;
@@ -175,10 +179,25 @@ function updateWorkspaceWidgetSafely(ctx: ExtensionContext, state: RunState, row
 	}
 }
 
-function boundedPublicText(value: string): string {
-	if (Buffer.byteLength(value, "utf8") <= PUBLIC_EVIDENCE_MAX_BYTES) return value;
-	let end = Math.min(value.length, PUBLIC_EVIDENCE_MAX_BYTES);
-	while (end > 0 && Buffer.byteLength(value.slice(0, end), "utf8") > PUBLIC_EVIDENCE_MAX_BYTES) end -= 1;
+/** Join report lines within a follow-up budget, naming how many were omitted. */
+function boundedReport(lines: readonly string[], omitted: string): string {
+	const report: string[] = [];
+	let bytes = 0;
+	let skipped = 0;
+	for (const line of lines.flatMap((entry) => entry.split("\n"))) {
+		const size = Buffer.byteLength(`${line}\n`, "utf8");
+		if (bytes + size > 7_900) { skipped++; continue; }
+		report.push(line);
+		bytes += size;
+	}
+	if (skipped) report.push(`[${skipped} ${omitted}]`);
+	return report.join("\n");
+}
+
+function boundedPublicText(value: string, maxBytes = PUBLIC_EVIDENCE_MAX_BYTES): string {
+	if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+	let end = Math.min(value.length, maxBytes);
+	while (end > 0 && Buffer.byteLength(value.slice(0, end), "utf8") > maxBytes) end -= 1;
 	return `${value.slice(0, end)}\n[truncated]`;
 }
 
@@ -199,16 +218,18 @@ function publicFailedCheck(evidence: CheckBatchEvidence | undefined) {
 	};
 }
 
-function publicFailedReview(evidence: ReviewEvidence | undefined) {
+function publicFailedReview(evidence: ReviewEvidence | undefined, verdictMaxBytes: number) {
 	if (!evidence || evidence.passed) return undefined;
+	const verdict = boundedPublicText(evidence.verdict, verdictMaxBytes);
 	return {
 		phase: evidence.phase,
-		verdict: boundedPublicText(evidence.verdict),
+		verdict,
+		verdictTruncated: verdict !== evidence.verdict,
 		identityChanged: !sameIdentity(evidence.tip, evidence.identityAfter),
 	};
 }
 
-function publicTaskRecovery(task: RunState["tasks"][number]) {
+function publicTaskRecovery(task: RunState["tasks"][number], verdictMaxBytes: number) {
 	if (task.kind === "text") {
 		const attempt = task.attempts.at(-1);
 		return {
@@ -225,7 +246,7 @@ function publicTaskRecovery(task: RunState["tasks"][number]) {
 
 	const attempt = task.attempts.at(-1);
 	const failedCheck = publicFailedCheck(attempt?.preliminaryChecks);
-	const failedReview = publicFailedReview(attempt?.preliminaryReview);
+	const failedReview = publicFailedReview(attempt?.preliminaryReview, verdictMaxBytes);
 	const cleanup = attempt?.cleanup
 		.filter((step) => step.status !== "completed")
 		.map((step) => ({
@@ -254,14 +275,14 @@ function publicTaskRecovery(task: RunState["tasks"][number]) {
 	};
 }
 
-function publicNeedsAttention(state: RunState, preferredTaskId?: string) {
+function publicNeedsAttention(state: RunState, verdictMaxBytes: number, preferredTaskId?: string) {
 	if (state.status !== "needs_attention") return undefined;
 	const task = state.tasks.find((candidate) => candidate.status === "needs_attention" && candidate.taskId === preferredTaskId)
 		?? state.tasks.find((candidate) => candidate.status === "needs_attention");
-	if (task) return publicTaskRecovery(task);
+	if (task) return publicTaskRecovery(task, verdictMaxBytes);
 	if (state.final.failure || state.final.checks?.passed === false || state.final.review?.passed === false) {
 		const failedCheck = publicFailedCheck(state.final.checks);
-		const failedReview = publicFailedReview(state.final.review);
+		const failedReview = publicFailedReview(state.final.review, verdictMaxBytes);
 		return {
 			scope: "final" as const,
 			...(state.final.failure ? { failure: boundedPublicText(state.final.failure) } : {}),
@@ -275,8 +296,8 @@ function publicNeedsAttention(state: RunState, preferredTaskId?: string) {
 	};
 }
 
-function publicState(state: RunState, preferredTaskId?: string) {
-	const needsAttention = publicNeedsAttention(state, preferredTaskId);
+function publicState(state: RunState, verdictMaxBytes: number, preferredTaskId?: string) {
+	const needsAttention = publicNeedsAttention(state, verdictMaxBytes, preferredTaskId);
 	return {
 		version: state.version,
 		id: state.request.id,
@@ -313,7 +334,7 @@ function publicState(state: RunState, preferredTaskId?: string) {
 				...(combinedTip ? { combinedTip } : {}),
 				...(correction ? { correction } : {}),
 				...(checks ? { checked: checks.passed, failedCheck: publicFailedCheck(checks) } : {}),
-				...(review ? { reviewed: review.passed, failedReview: publicFailedReview(review) } : {}),
+				...(review ? { reviewed: review.passed, failedReview: publicFailedReview(review, verdictMaxBytes) } : {}),
 				...(promotion ? { promotion: promotion.status, ...(promotion.mainAfter ? { mainAfter: promotion.mainAfter } : {}),
 					...(promotion.failure ? { promotionFailure: boundedPublicText(promotion.failure) } : {}) } : {}),
 				...(failure ? { failure: boundedPublicText(failure) } : {}),
@@ -329,6 +350,42 @@ function publicState(state: RunState, preferredTaskId?: string) {
 	};
 }
 
+/** Model-visible failed review verdicts from every task, the final gate, and each generation, within one shared budget.
+ * Pi shows the model `content`, not `structuredContent`; task reviews appear even while sibling tasks still run. */
+function failedReviewText(state: RunState): string {
+	const reviews = [
+		...state.tasks.flatMap((task) => {
+			const review = task.kind === "changeset" ? task.attempts.at(-1)?.preliminaryReview : undefined;
+			return review && !review.passed ? [{ label: `Task ${task.taskId}`, review }] : [];
+		}),
+		...(state.final.review && !state.final.review.passed ? [{ label: "Final", review: state.final.review }] : []),
+		...state.integration.generations.flatMap(({ number, review }) => review && !review.passed ? [{ label: `Integration generation ${number}`, review }] : []),
+	].reduce<{ label: string; review: ReviewEvidence }[]>((merged, entry) => {
+		// Show an identical verdict once, but keep every scope that failed with it.
+		const same = merged.find(({ review }) => review.verdict === entry.review.verdict);
+		if (same) same.label = `${same.label}, ${entry.label}`;
+		else merged.push({ ...entry });
+		return merged;
+	}, []);
+	let budget = PUBLIC_REVIEW_VERDICT_MAX_BYTES;
+	let omitted = 0;
+	const parts: string[] = [];
+	for (const { label, review } of reviews) {
+		if (budget <= 0) { omitted++; continue; }
+		const verdict = boundedPublicText(review.verdict, budget);
+		budget -= Buffer.byteLength(verdict, "utf8");
+		parts.push(`\n\n${label}: failed ${review.phase} review verdict${verdict !== review.verdict ? " (truncated)" : ""}:\n${workerOutputForMain(verdict)}`);
+	}
+	if (omitted) parts.push(`\n\n${omitted} more failed review verdict(s) omitted from this text; structuredContent lists each one.`);
+	return parts.join("");
+}
+
+function hasTruncatedVerdict(state: ReturnType<typeof publicState>): boolean {
+	const attention = state.needsAttention;
+	return Boolean(attention && "failedReview" in attention && attention.failedReview?.verdictTruncated)
+		|| state.integration.generations.some((generation) => generation.failedReview?.verdictTruncated);
+}
+
 function inspectionNotices({ state, main, continuation }: RunResponse): string[] {
 	const lines = [
 		`Isolated request ${state.request.id}: ${state.status}; accepted: ${state.accepted}; final: ${state.final.status}; Main: ${main?.status ?? "not checked"}.`,
@@ -338,7 +395,7 @@ function inspectionNotices({ state, main, continuation }: RunResponse): string[]
 		? `Main inspection unavailable: ${boundedPublicText(main.failure)}; expected: ${JSON.stringify(main.expected)}`
 		: `Main ${main.status}: ${JSON.stringify({ expected: main.expected, actual: main.actual })}`);
 	if (state.integration.refresh) lines.push(`Integration refresh: ${state.integration.refresh.status}${state.integration.refresh.failure ? `; blockage: ${boundedPublicText(state.integration.refresh.failure)}` : ""}.`);
-	const attention = publicNeedsAttention(state);
+	const attention = publicNeedsAttention(state, PUBLIC_EVIDENCE_MAX_BYTES);
 	if (attention) lines.push(`Reported blockage: ${JSON.stringify({ scope: attention.scope, failure: attention.failure, failedCheck: "failedCheck" in attention ? attention.failedCheck : undefined, failedReview: "failedReview" in attention ? attention.failedReview : undefined })}`);
 	if (state.final.failure) lines.push(`Final blockage: ${boundedPublicText(state.final.failure)}`);
 	for (const task of state.tasks) {
@@ -404,7 +461,7 @@ function toolResult(response: RunResponse, ctx: ExtensionContext, rowsByRequest:
 	return {
 		content: [{ type: "text" as const, text }],
 		details: {
-			state: publicState(response.state, preferredTaskId),
+			state: publicState(response.state, PUBLIC_REVIEW_VERDICT_MAX_BYTES, preferredTaskId),
 			...(response.main ? { main: response.main } : {}),
 			...(response.continuation ? { continuation: response.continuation } : {}),
 		},
@@ -415,6 +472,8 @@ export interface IsolatedSurface {
 	execute(request: ExecuteRequest, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof toolResult>>;
 	inventory(cwd: string, current?: () => boolean): Promise<IsolatedInventory>;
 	recover(cwd: string): Promise<string>;
+	prunePlan(cwd: string): Promise<PrunePlan>;
+	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;
 	enqueue(root: string, requestId: string, taskId: string, text: string, current: () => boolean): string;
@@ -487,6 +546,10 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 	pi.on("model_select", (event, ctx) => { latestCtx = { ...ctx, model: event.model } as ExtensionContext; });
 	pi.on("agent_settled", (_event, ctx) => { latestCtx = ctx; });
 
+	const pruneGuards = (root: string): PruneGuards => ({
+		ownership: async (checkouts) => await getComponents().runner.pruneOwnership(checkouts),
+		panes: async () => await listHerdrPanes(root),
+	});
 	const requireCurrent = (current: () => boolean) => {
 		if (!current() || sessionClosed) throw new Error("Session or branch changed; reopen /subagent.");
 	};
@@ -551,14 +614,17 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			}
 			const state = response?.state ?? latestState;
 			try {
-				const details = state ? {
-					state: publicState(state, response?.continuation && "taskId" in response.continuation
-						? response.continuation.taskId : undefined),
+				const preview = state ? publicState(state, PUBLIC_EVIDENCE_MAX_BYTES, response?.continuation && "taskId" in response.continuation
+					? response.continuation.taskId : undefined) : undefined;
+				const details = preview ? {
+					state: preview,
 					...(response?.continuation ? { continuation: response.continuation } : {}),
 				} : { id };
 				pi.sendMessage({
 					customType: "pi-subagent-isolated-result",
-					content: text,
+					content: preview && hasTruncatedVerdict(preview)
+						? `${text}\n\nReview verdicts here are previews; run subagent_status for the full verdict.`
+						: text,
 					display: true,
 					details,
 				}, { triggerTurn: true, deliverAs: "followUp" });
@@ -597,7 +663,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 					reject(new Error(`Pi Subagent ${id} finished without a durable acknowledgement.`));
 					return;
 				}
-				deliver("terminal", `${response.text}\n\nState: ${JSON.stringify(publicState(response.state))}`, response);
+				deliver("terminal", `${response.text}\n\nState: ${JSON.stringify(publicState(response.state, PUBLIC_EVIDENCE_MAX_BYTES))}`, response);
 			},
 			(error: unknown) => {
 				finish();
@@ -628,15 +694,17 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
 			const root = await lookupRoot(ctx.cwd, signal);
-			const result = toolResult(await getComponents().runner.status(params.id, root, signal), ctx, workspaceRowsByRequest);
+			const response = await getComponents().runner.status(params.id, root, signal);
+			const result = toolResult(response, ctx, workspaceRowsByRequest);
+			const content = [{ type: "text" as const, text: `${result.content[0]!.text}${failedReviewText(response.state)}` }];
 			// The projection is plain JSON; its conditional fields are typed optional rather than absent.
-			return { ...result, structuredContent: result.details as JsonValue };
+			return { ...result, content, structuredContent: result.details as JsonValue };
 		},
 	});
 	pi.registerTool({
 		name: "subagent_resume",
 		label: "Subagent resume",
-		description: "Resume one unfinished isolated request without resetting its recorded policy or correction count.",
+		description: "Resume one unfinished isolated request without resetting its recorded policy or correction count. For a retry that sends a same-worker correction, optional instruction (at most 32000 characters) is appended to that prompt as Main's instruction after the saved check or review failure; use it to name the exact fixes, including the review findings the worker must address. Other actions reject instruction.",
 		parameters: ResumeRequestParameters,
 		prepareArguments: parseResumeRequest,
 		exposure: "model-only",
@@ -748,17 +816,26 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			leaseBusy ? "Wait for the active productive run; use subagent_status to inspect its current state. No work was taken over."
 				: "Main: inspect subagent_status for exact identities and blockers before deciding stage, promote, resume, or guarded release. No worker prompt, merge, promotion, or cleanup was replayed.",
 			];
-			const report: string[] = [];
-			let bytes = 0;
-			let omitted = 0;
-			for (const line of lines.flatMap((entry) => entry.split("\n"))) {
-				const size = Buffer.byteLength(`${line}\n`, "utf8");
-				if (bytes + size > 7_900) { omitted++; continue; }
-				report.push(line);
-				bytes += size;
-			}
-			if (omitted) report.push(`[${omitted} recovery report lines omitted; use subagent_status for exact request evidence.]`);
-			return report.join("\n");
+			return boundedReport(lines, "recovery report lines omitted; use subagent_status for exact request evidence.");
+		},
+		async prunePlan(cwd) {
+			const root = await lookupRoot(cwd);
+			return { root, items: await inspectPruneCandidates(root, cwd, pruneGuards(root)) };
+		},
+		async prune(cwd, items, allowIgnored, current) {
+			requireCurrent(current);
+			const root = await lookupRoot(cwd);
+			const { removals, checkouts } = await removePruneCandidates(root, cwd, items, allowIgnored,
+				{ ...pruneGuards(root), current: () => current() && !sessionClosed });
+			const removed = removals.filter(({ outcome }) => outcome === "removed");
+			const reconciled = removed.length
+				? await getComponents().runner.reconcilePrunedAborts(checkouts, removed.map(({ item }) => basename(item.branch))) : [];
+			const count = (outcome: string) => removals.filter((item) => item.outcome === outcome).length;
+			return boundedReport([
+				`Pi Subagent prune in ${root}: ${removed.length} removed, ${count("skipped")} skipped, ${count("failed")} failed.`,
+				...removals.map(({ outcome, item, reason }) => `${outcome}: ${item.path ?? "(no checkout)"} · ${item.branch} · ${reason}`),
+				...reconciled,
+			], "prune report lines omitted.");
 		},
 		async inspect(root, requestId) {
 			const response = await getComponents().runner.status(requestId, root);

package/extensions/result-transport.ts

@@ -1,4 +1,4 @@
-import { capEphemeralSubagentOutput } from "@henryqw/pi-subagent";
+import { capEphemeralSubagentOutput, formatDuration } from "@henryqw/pi-subagent";
 import type { WorkflowEntry, WorkflowMode } from "./workflow.ts";
 
 const EVIDENCE_PREVIEW_CODE_POINTS = 256;
@@ -22,6 +22,9 @@ export type WorkflowTransportEntry = {
 	role: WorkflowEntry["delegation"]["role"];
 	model?: string;
 	thinkingLevel?: string;
+	/** Measured session tokens; absent when usage was unavailable. */
+	tokens?: number;
+	elapsedMs?: number;
 	status: WorkflowTransportStatus;
 	assistantOutput?: string;
 	failure?: string;
@@ -76,6 +79,21 @@ export function displaySummary(text: string): string {
 	return Array.from(normalized).slice(0, 160).join("");
 }
 
+export function compactTokens(tokens: number): string {
+	return `${tokens < 1_000 ? tokens : `${(tokens / 1_000).toFixed(1).replace(/\.0$/, "")}k`} tok`;
+}
+
+/** Launched workers carry a model; workers that never launched show no usage. */
+function usageFor(entry: WorkflowTransportEntry): string {
+	if (entry.model === undefined) return "";
+	return [
+		entry.model,
+		...(entry.thinkingLevel === undefined ? [] : [`thinking ${entry.thinkingLevel}`]),
+		entry.tokens === undefined ? "tokens unknown" : compactTokens(entry.tokens),
+		...(entry.elapsedMs === undefined ? [] : [formatDuration(entry.elapsedMs)]),
+	].map((part) => ` · ${part}`).join("");
+}
+
 export type WorkflowEntryStatusPresentation = { glyph: string; fallback: string };
 
 export const ENTRY_STATUS_PRESENTATION = {
@@ -120,7 +138,7 @@ export function formatWorkflowResult(mode: WorkflowMode, entries: readonly Workf
 		...positioned.map(({ entry, position }) => {
 			const { glyph, fallback } = ENTRY_STATUS_PRESENTATION[entry.status];
 			const summary = displaySummary(sourceFor(entry) ?? "") || fallback;
-			return `${glyph} [${position}/${ordered.length}] ${entry.name} · ${entry.role} — ${summary}`;
+			return `${glyph} [${position}/${ordered.length}] ${entry.name} · ${entry.role}${usageFor(entry)} — ${summary}`;
 		}),
 		...(evidence.length ? [
 			"Results:",
@@ -146,6 +164,8 @@ export function formatWorkflowResult(mode: WorkflowMode, entries: readonly Workf
 					...(source === undefined ? {} : { summary: displaySummary(source) }),
 					...(entry.model === undefined ? {} : { model: entry.model }),
 					...(entry.thinkingLevel === undefined ? {} : { thinkingLevel: entry.thinkingLevel }),
+					...(entry.tokens === undefined ? {} : { tokens: entry.tokens }),
+					...(entry.elapsedMs === undefined ? {} : { elapsedMs: entry.elapsedMs }),
 				};
 			}),
 		},

package/extensions/subagent-command.ts

@@ -49,6 +49,22 @@ export interface IsolatedInventory {
 	invalidIds: readonly string[];
 }
 
+/** One pi-subagent branch and its checkout as reviewed by /subagent prune. */
+export interface PruneItem {
+	branch: string;
+	tip: string;
+	path?: string;
+	prunable: boolean;
+	/** Why the item is prunable, or every exact blocker. */
+	reason: string;
+	/** Ignored entries that removing the checkout deletes. */
+	ignored: readonly string[];
+}
+export interface PrunePlan {
+	root: string;
+	items: readonly PruneItem[];
+}
+
 /** Mutation adapters MUST check current() synchronously alongside their live ownership
  * validation and queue operation. They must not await between those operations. */
 export interface SubagentCommandAdapter {
@@ -57,6 +73,10 @@ export interface SubagentCommandAdapter {
 	stopDirect(task: DirectTask, entryId: string, current: () => boolean): Promise<string>;
 	isolated(cwd: string, current: () => boolean): Promise<IsolatedInventory>;
 	recover(cwd: string): Promise<string>;
+	/** Read-only review of pi-subagent worktrees and branches in the canonical repository. */
+	prunePlan(cwd: string): Promise<PrunePlan>;
+	/** 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. */
 	roles(ctx: ExtensionContext): string;
 	inspectInTab(root: string, requestId: string, ctx: ExtensionContext, current: () => boolean): Promise<{ ref: string; tabId: string; name: string; sessionFile: string }>;
@@ -73,6 +93,39 @@ const errorText = (error: unknown): string => clean(error instanceof Error ? err
 const completed = (status: string) => ["completed", "success", "failed", "failure", "aborted", "integrated"].includes(status);
 const priority = (status: string) => /attention|blocked|retained|failed/i.test(status) ? 0 : completed(status) ? 2 : 1;
 
+const ignoredSummary = ({ ignored }: PruneItem) => !ignored.length ? "none"
+	: `${ignored.length} (${ignored.slice(0, 5).join(", ")}${ignored.length > 5 ? `, +${ignored.length - 5} more` : ""})`;
+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[] } {
+	const lines = [header];
+	const shown: T[] = [];
+	let size = [...header].length;
+	const reserve = [...NOT_SHOWN].length + 32;
+	for (const item of items) {
+		const text = line(item);
+		const length = [...text].length + 1;
+		if (size + length + reserve > max) break;
+		lines.push(text);
+		size += length;
+		shown.push(item);
+	}
+	if (shown.length < items.length) lines.push(`+${items.length - shown.length} more not shown; ${NOT_SHOWN}`);
+	return { text: lines.join("\n"), shown };
+}
+
+/** Prunable items come first so a long blocked list cannot hide them; only shown items may be removed. */
+function pruneReview({ root, items }: PrunePlan): { text: string; shown: PruneItem[] } {
+	if (!items.length) return { text: `No pi-subagent worktrees or branches in ${root}.`, shown: [] };
+	const prunable = items.filter((item) => item.prunable).length;
+	return fitItems(`Subagent prune review in ${root}: ${prunable} prunable, ${items.length - prunable} blocked.`,
+		[...items.filter((item) => item.prunable), ...items.filter((item) => !item.prunable)],
+		(item) => clean(`${item.prunable ? "✓ prunable" : "✗ blocked"} · ${item.path ?? "(no checkout)"} · ${item.branch} · ${item.tip.slice(0, 12)} · ${item.reason} · ignored: ${ignoredSummary(item)}`, 600),
+		ROLES_REPORT_CODE_POINTS);
+}
+
 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.
@@ -84,10 +137,10 @@ async function choose<T>(ctx: ExtensionContext, title: string, items: readonly C
 
 export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentCommandAdapter): void {
 	pi.registerCommand("subagent", {
-		description: "Inspect direct and isolated work, list Roles with /subagent roles, or recover orphaned isolated requests with /subagent recover",
+		description: "Inspect direct and isolated work, list Roles with /subagent roles, recover orphaned isolated requests with /subagent recover, or remove merged leftover worktrees with /subagent prune",
 		handler: async (args, ctx) => {
 			const command = args.trim();
-			if (command && command !== "recover" && command !== "roles") throw new Error("Usage: /subagent [recover|roles]");
+			if (command && !["prune", "recover", "roles"].includes(command)) throw new Error("Usage: /subagent [prune|recover|roles]");
 			if (command === "roles") {
 				const report = clean(adapter.roles(ctx), ROLES_REPORT_CODE_POINTS, true);
 				if (ctx.hasUI) ctx.ui.notify(report, "info");
@@ -121,6 +174,39 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				ctx.ui.notify("Session or branch changed; reopen /subagent in the current context.", "warning");
 				return false;
 			};
+			if (command === "prune") {
+				const plan = await adapter.prunePlan(ctx.cwd);
+				const reviewed = pruneReview(plan);
+				const review = clean(reviewed.text, ROLES_REPORT_CODE_POINTS, true);
+				if (!ctx.hasUI) {
+					pi.sendMessage({ customType: "pi-subagent-prune", content: `${review}\nReport only: removal requires interactive confirmation.`, display: true });
+					return;
+				}
+				if (!valid()) return;
+				ctx.ui.notify(review, "info");
+				const prunable = reviewed.shown.filter((item) => item.prunable);
+				if (!prunable.length) return;
+				const confirmed = await ctx.ui.confirm("Prune subagent worktrees", `Remove all ${prunable.length} prunable item(s) listed above? Each is re-verified first; unique commits, tracked or untracked changes, and unlisted items are never removed.`);
+				if (!valid() || !confirmed) return;
+				const ignored = prunable.filter((item) => item.ignored.length);
+				// The header uses the full count's width so the shown count always fits.
+				const ignoredList = fitItems(`Also remove ${ignored.length} checkout(s) with ignored files? This permanently deletes these ignored entries and everything inside them:`,
+					// Approval names every ignored entry; a checkout whose full list does not fit is left out of this run.
+					ignored, (item) => clean(`${item.path}: ${item.ignored.join(", ")}`, Number.MAX_SAFE_INTEGER), PRUNE_IGNORED_CONFIRM_CODE_POINTS);
+				const approvable = ignoredList.shown;
+				const allowIgnored = approvable.length > 0 && await ctx.ui.confirm("Delete ignored content",
+					clean(ignoredList.text.replace(`Also remove ${ignored.length} checkout(s)`, `Also remove ${approvable.length} checkout(s)`), PRUNE_IGNORED_CONFIRM_CODE_POINTS, true));
+				if (!valid()) return;
+				const kept = ignored.length - (allowIgnored ? approvable.length : 0);
+				if (kept) ctx.ui.notify(`Kept ${kept} checkout(s) with ignored content; their deletion was not approved.`, "info");
+				const selected = prunable.filter((item) => !item.ignored.length || (allowIgnored && approvable.includes(item)));
+				if (!selected.length) return;
+				try {
+					const report = await adapter.prune(ctx.cwd, selected, allowIgnored, current);
+					if (valid()) ctx.ui.notify(clean(report, ROLES_REPORT_CODE_POINTS, true), "info");
+				} catch (error) { if (valid()) ctx.ui.notify(`Prune failed: ${errorText(error)}`, "error"); }
+				return;
+			}
 			let history = false;
 			for (;;) {
 				if (!valid()) return;

package/extensions/subagent.ts

@@ -8,7 +8,7 @@ import { registerCheckoutAdmission } from "./admission.ts";
 import { registerIsolatedExtension } from "./isolated.ts";
 import { directRef, registerSubagentCommand, type DirectDisplay, type DirectTask } from "./subagent-command.ts";
 import { MODEL_CLASS_GUIDANCE } from "./model-class-policy.ts";
-import { ENTRY_STATUS_PRESENTATION, formatWorkflowResult, workerOutputForMain, type BackgroundWorkflowTransportDetails, type WorkflowTransportEntry } from "./result-transport.ts";
+import { compactTokens, ENTRY_STATUS_PRESENTATION, formatWorkflowResult, workerOutputForMain, type BackgroundWorkflowTransportDetails, type WorkflowTransportEntry } from "./result-transport.ts";
 import { DelegateTaskParameters, identifyWorkflowEntries, parseDelegateTask, runForegroundWorkflow, writesCheckout, type ParsedWorkflow, type WorkflowEntry } from "./workflow.ts";
 import { assertSettledDirectSession, createDirectHerdr, DirectAllocationError, type DirectAllocation, type DirectHandle, type DirectTab, type DirectToolActivity } from "../dist/direct-herdr.js";
 import { materializeTransientLaunch } from "../dist/launch-runtime.js";
@@ -55,7 +55,7 @@ function statusLabel(status: WidgetStatus): string {
 }
 
 function tokenLabel(tokens: number | undefined): string {
-	return tokens === undefined ? "— tok" : `${tokens < 1_000 ? tokens : `${(tokens / 1_000).toFixed(1).replace(/\.0$/, "")}k`} tok`;
+	return tokens === undefined ? "— tok" : compactTokens(tokens);
 }
 
 function activityLabel(activity: DirectToolActivity | undefined): string | undefined {
@@ -304,6 +304,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		},
 		isolated: isolatedSurface.inventory,
 		recover: (cwd) => isolatedSurface.recover(cwd),
+		prunePlan: (cwd) => isolatedSurface.prunePlan(cwd),
+		prune: (cwd, items, allowIgnored, current) => isolatedSurface.prune(cwd, items, allowIgnored, current),
 		async inspectInTab(root, id, ctx, current) {
 			const notices = await isolatedSurface.inspect(root, id);
 			if (!current()) throw new Error("Session or branch changed before status inspection.");
@@ -654,6 +656,11 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				id, index, role: delegation.role, status: "pending",
 				name: delegation.continueFrom === undefined ? delegation.name : `${delegation.name} (continued from ${delegation.continueFrom})`,
 			}]));
+			const startedAt = new Map<string, number>();
+			const measured = (id: string, tokens: number | undefined) => ({
+				...(tokens === undefined ? {} : { tokens }),
+				...(startedAt.has(id) ? { elapsedMs: Date.now() - startedAt.get(id)! } : {}),
+			});
 			const taskId = `direct-${++directSequence}-${Date.now().toString(36)}`;
 			const workflowNumber = nextWorkflow(ctx);
 			const ref = `D${workflowNumber}`;
@@ -717,6 +724,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				const prepared = await prepareDirectLaunch(role, latestCtx ?? ctx, {
 					...(modelClass === undefined ? {} : { modelClass }), ...(model === undefined ? {} : { model }) });
 				states.set(entry.id, { ...states.get(entry.id)!, model: modelReference(prepared.model), thinkingLevel: prepared.thinkingLevel, status: "running", assistantOutput: "" });
+				startedAt.set(entry.id, Date.now());
 				const display = displayOf(entry);
 				startWidgetItem(entry.id, taskId, display, prepared.model.id, prepared.thinkingLevel, ctx);
 				const transient = await materializeTransientLaunch({ launch: prepared, prompt: prepared.systemPrompt,
@@ -795,24 +803,26 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 							if (writerFailed) throw new Error("Previous direct task did not complete exactly; inspect recorded tabs before new shared-checkout work.");
 							handle = entry.index === 0 ? first : await launch(entry, entrySignal(entry));
 							const answer = await handle.answer(Math.floor(40 * 1024 / entries.length));
+							let tokens: number | undefined;
 							try {
-								const tokens = await handle.usageTokens();
+								tokens = await handle.usageTokens();
 								const item = widgetItems.get(entry.id);
 								if (item) { item.tokens = tokens; item.activity = handle.activity; }
 							} catch { /* Optional telemetry. */ }
-							states.set(entry.id, { ...states.get(entry.id)!, status: "succeeded", assistantOutput: answer });
+							states.set(entry.id, { ...states.get(entry.id)!, status: "succeeded", assistantOutput: answer, ...measured(entry.id, tokens) });
 							finishWidgetItem(entry.id, "success");
 							return answer;
 						} catch (error) {
 							if (writes) writerFailed = true;
 							const { assistantOutput: _partial, ...base } = states.get(entry.id)!;
 							const partialOutput = await handle?.partialText(PARTIAL_OUTPUT_CHARS).catch(() => undefined);
+							const tokens = await handle?.usageTokens().catch(() => undefined);
 							const message = (value: unknown) => value instanceof Error ? value.message : String(value);
 							const stopped = await stopProofs.get(entry.id)?.then(() => STOPPED_BY_USER,
 								(stopError: unknown) => `${STOPPED_BY_USER}; termination unproved: ${message(stopError)}`);
 							const tab = tabByEntry.get(entry.id);
 							const recover = tab && stopped !== STOPPED_BY_USER ? `recover from Herdr tab ${tab.tabId}, agent ${tab.name}, session ${tab.sessionFile}: ` : "";
-							states.set(entry.id, { ...base, status: "rejected", ...(partialOutput ? { partialOutput } : {}), failure: `${recover}${capOutput(stopped ?? message(error))}` });
+							states.set(entry.id, { ...base, status: "rejected", ...(partialOutput ? { partialOutput } : {}), ...measured(entry.id, tokens), failure: `${recover}${capOutput(stopped ?? message(error))}` });
 							finishWidgetItem(entry.id, "failure");
 							throw error;
 						} finally { release(); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "27.0.0",
+  "version": "27.1.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. 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 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.
 
 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. Use `subagent_status` to inspect exact durable state without mutation, including candidate identities, generations, and retained resources. `subagent_resume` handles only the reported retry/verify/finalize continuation; it cannot replace Main's stage/integrate decisions or reset policy/corrections. `subagent_stage reject` or `revise` freezes a generation containing the candidate and invalidates dependent attempts; restage chosen work in a new generation. If Main advances cleanly before promotion, use `subagent_integrate refresh` with exact old/new Main and combined-tip identities; restage immutable candidates into the new generation and rerun combined validation. Dirty or divergent Main blocks refresh. 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: 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.