@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/src/runs/shared/subagent-control.ts

@@ -203,7 +203,8 @@ export function forgetControlNotifications(seenKeys: Set<string>, target: Pick<C
 export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
 	const childKey = controlNotificationChildKey(event, childIntercomTarget);
 	const contextHash = createHash("sha256").update(formatControlNudge(event)).digest("hex").slice(0, 8);
-	return `${childKey}:${event.type}:${event.reason ?? "idle"}:${contextHash}`;
+	const callKey = event.reason === "tool_open_threshold" && event.toolCallId ? `:${event.toolCallId}` : "";
+	return `${childKey}:${event.type}:${event.reason ?? "idle"}${callKey}:${contextHash}`;
 }
 
 export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
@@ -238,70 +239,70 @@ export function formatControlNudge(event: ControlEvent): string {
 
 export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
 	const runTarget = event.runId;
-	if (event.reason === "completion_guard") {
-		return [
-			`Subagent failed: ${event.agent}`,
-			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
-			`Signal: ${event.message}`,
-			"Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
-			childIntercomTarget ? `Run intercom target (may be inactive): ${childIntercomTarget}` : undefined,
-		].filter((line): line is string => Boolean(line)).join("\n");
-	}
-
 	const nudgeMessage = formatControlNudge(event);
 	const steerCommand = `subagent({ action: "steer", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: ${JSON.stringify(nudgeMessage)} })`;
 	const nestedResumeCommand = `subagent({ action: "resume", id: "${runTarget}", message: ${JSON.stringify(nudgeMessage)} })`;
+	const facts = formatLongRunningFacts(event);
+	const head = (title: string) => [
+		`${title}: ${event.agent}`,
+		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+		`Signal: ${event.message}`,
+		facts ? `Facts: ${facts}` : undefined,
+	];
+	const status = `Status: subagent({ action: "status", id: "${runTarget}" })`;
+	const lines = (items: Array<string | undefined>) => items.filter((line): line is string => Boolean(line)).join("\n");
 	if (event.type === "active_long_running") {
-		const facts = formatLongRunningFacts(event);
-		return [
-			`Subagent active but long-running: ${event.agent}`,
-			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
-			`Signal: ${event.message}`,
-			facts ? `Facts: ${facts}` : undefined,
+		return lines([
+			...head("Subagent active but long-running"),
 			"Hint: Inspect status first. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
 			`Top-level live async nudge: ${steerCommand}`,
 			`Routed live nested nudge: ${nestedResumeCommand}`,
 			childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
-			`Status: subagent({ action: "status", id: "${runTarget}" })`,
+			status,
 			`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
-		].filter((line): line is string => Boolean(line)).join("\n");
+		]);
+	}
+
+	if (event.reason === "tool_open_threshold" && event.currentTool === "bash") {
+		const command = (label: string, action: string) => `${label}: subagent(${JSON.stringify({ action, id: runTarget, ...(event.index !== undefined ? { index: event.index } : {}), toolCallId: event.toolCallId })})`;
+		return lines([
+			...head("Subagent needs attention"),
+			"Hint: Inspect the running command and recent output before nudging. A queued steer does not cancel an in-flight bash call. A dev server or watch command may intentionally never return. Elapsed time alone does not prove the command is stuck.",
+			"Recovery: For a local Pi child explicitly granted subagent_command, yield a needed persistent command or cancel the exact incorrect command, then steer the child. Query command.status to confirm the result. If command controls are unavailable, inspect partial changes and interruption scope before interrupt/resume; interrupt is run-scoped and may affect siblings.",
+			...(event.toolCallId ? [command("Command", "command.status"), command("Yield", "command.yield"), command("Cancel", "command.cancel")] : []),
+			status,
+			`Transcript: subagent({ action: "status", id: "${runTarget}", view: "transcript"${event.index !== undefined ? `, index: ${event.index}` : ""} })`,
+		]);
 	}
 
 	const supervisorHint = event.reason === "supervisor_request"
 		? "Supervisor request: reply to the pending request. If subagent_supervisor pending is empty, check intercom pending because an external intercom tool may own the request."
 		: undefined;
-	const facts = formatLongRunningFacts(event);
-	return [
-		`Subagent needs attention: ${event.agent}`,
-		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
-		`Signal: ${event.message}`,
-		facts ? `Facts: ${facts}` : undefined,
+	return lines([
+		...head("Subagent needs attention"),
 		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
 		supervisorHint,
 		"Hint: Inspect status first unless the run is clearly blocked. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
 		`Top-level live async nudge: ${steerCommand}`,
 		`Routed live nested nudge: ${nestedResumeCommand}`,
 		childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
-		`Status: subagent({ action: "status", id: "${runTarget}" })`,
+		status,
 		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
-	].filter((line): line is string => Boolean(line)).join("\n");
+	]);
 }
 
+
 export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string): string {
-	const statusLabel = event.reason === "completion_guard"
-		? "subagent failed"
-		: event.type === "active_long_running"
+	const statusLabel = event.type === "active_long_running"
 			? "subagent active but long-running"
 			: "subagent needs attention";
 	return [
 		statusLabel,
 		"",
-		event.reason === "completion_guard"
-			? `${event.agent} failed in run ${event.runId}.`
-			: event.type === "active_long_running"
+		event.type === "active_long_running"
 				? `${event.agent} is still active but long-running in run ${event.runId}.`
 				: `${event.agent} needs attention in run ${event.runId}.`,
 		"",
 		formatControlNoticeMessage(event, childIntercomTarget),
 	].join("\n");
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/subagent-prompt-runtime.ts

@@ -11,14 +11,18 @@ import { validateAcceptanceReport } from "./acceptance.ts";
 import { formatChildToolDiagnostic } from "./tool-availability.ts";
 import { shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.ts";
 import type { ResolvedToolBudget, SubagentState } from "../../shared/types.ts";
+import { INTERCOM_SESSION_IDENTITY_EVENT } from "../../shared/types.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { getAgentDir } from "../../shared/utils.ts";
 import { registerChildWatchdog } from "../../watchdog/register-child.ts";
 import type { ChildWatchdogConfig } from "../../watchdog/child-status.ts";
 import { requestWatchdogPermission, type WatchdogPermissionRequest, type WatchdogPermissionResult } from "../../watchdog/permission-arbiter.ts";
 import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.ts";
+import { captureWatchdogDiffBaseline, createWatchdogDiffTool, WATCHDOG_DIFF_TOOL_NAME } from "../../watchdog/diff-tool.ts";
+import { inheritedNestedRouteOf } from "./nested-events.ts";
 import { registerWaitTool } from "../background/wait-tool.ts";
 import { drainOutstandingWork } from "../background/auto-drain.ts";
+import { MODEL_ONLY_TOOL } from "../../shared/extension-context.ts";
 import {
 	childSupervisorMetadata,
 	evaluateChildToolDiagnostic,
@@ -194,8 +198,8 @@ export function stripSubagentOrchestrationSkill(prompt: string): string {
 
 function stripChildBoundaryInstructions(prompt: string): string {
 	let rewritten = prompt;
-	for (const boundary of [CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS, CHILD_FANOUT_BOUNDARY_INSTRUCTIONS]) {
-		rewritten = rewritten.split(boundary).join("");
+	for (const instructions of [CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS, CHILD_FANOUT_BOUNDARY_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS]) {
+		rewritten = rewritten.split(`\n\n${instructions}`).join("").split(instructions).join("");
 	}
 	return rewritten.replace(/^(?:[ \t]*\r?\n)+/, "");
 }
@@ -218,7 +222,8 @@ export function rewriteSubagentPrompt(
 	rewritten = stripChildBoundaryInstructions(rewritten);
 	const boundary = options.fanoutChild ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
 	const structured = options.structuredOutput ? `\n\n${STRUCTURED_OUTPUT_INSTRUCTIONS}` : "";
-	return `${boundary}${structured}\n\n${rewritten}`;
+	// Pi's base prompt stays first so providers that recognize it by its opening still do.
+	return `${rewritten}\n\n${boundary}${structured}`;
 }
 
 function isParentOnlySubagentMessage(message: unknown): boolean {
@@ -264,17 +269,22 @@ export function rewriteForkCacheProviderRequest(event: BeforeProviderRequestEven
 	return { ...payload, prompt_cache_key: key };
 }
 
-function portableToolId(id: string): string {
+function portableToolId(id: string, preserveBoundedCompositeToolIds = false): string {
 	if (PORTABLE_TOOL_ID_PATTERN.test(id) && id.length <= MAX_PORTABLE_TOOL_ID_LENGTH) return id;
+	// Codex splits call_id|item_id on replay; each wire ID must remain portable and bounded.
+	if (preserveBoundedCompositeToolIds) {
+		const parts = id.split("|");
+		if (parts.length === 2 && parts.every((part) => PORTABLE_TOOL_ID_PATTERN.test(part) && part.length <= MAX_PORTABLE_TOOL_ID_LENGTH)) return id;
+	}
 	const encoded = `tool_${Buffer.from(id).toString("base64url") || "empty"}`;
 	if (encoded.length <= MAX_PORTABLE_TOOL_ID_LENGTH) return encoded;
 	return `tool_${createHash("sha256").update(id).digest("base64url")}`;
 }
 
-function sanitizeToolHistoryMessage(message: unknown): unknown {
+function sanitizeToolHistoryMessage(message: unknown, preserveBoundedCompositeToolIds = false): unknown {
 	const m = message as { role?: string; content?: unknown; toolCallId?: unknown };
 	if (m?.role === "toolResult" && typeof m.toolCallId === "string") {
-		const toolCallId = portableToolId(m.toolCallId);
+		const toolCallId = portableToolId(m.toolCallId, preserveBoundedCompositeToolIds);
 		return toolCallId === m.toolCallId ? message : { ...m, toolCallId };
 	}
 	if (m?.role !== "assistant" || !Array.isArray(m.content)) return message;
@@ -282,7 +292,7 @@ function sanitizeToolHistoryMessage(message: unknown): unknown {
 	const content = m.content.map((block) => {
 		const b = block as { type?: string; id?: unknown };
 		if (b?.type !== "toolCall" || typeof b.id !== "string") return block;
-		const id = portableToolId(b.id);
+		const id = portableToolId(b.id, preserveBoundedCompositeToolIds);
 		if (id === b.id) return block;
 		changed = true;
 		return { ...b, id };
@@ -299,7 +309,7 @@ function stripAssistantSubagentToolCallBlocks(message: unknown): unknown | undef
 	return { ...m, content: filteredContent };
 }
 
-export function stripParentOnlySubagentMessages(messages: unknown[], options: { sanitizeToolIds?: boolean; preserveFanoutToolHistory?: boolean } = {}): unknown[] {
+export function stripParentOnlySubagentMessages(messages: unknown[], options: { sanitizeToolIds?: boolean; preserveBoundedCompositeToolIds?: boolean; preserveFanoutToolHistory?: boolean } = {}): unknown[] {
 	const preserveCurrentFanoutToolHistory = options.preserveFanoutToolHistory === true;
 	const sanitizeToolIds = options.sanitizeToolIds ?? true;
 	let changed = false;
@@ -314,7 +324,7 @@ export function stripParentOnlySubagentMessages(messages: unknown[], options: {
 			changed = true;
 			continue;
 		}
-		const sanitized = sanitizeToolIds ? sanitizeToolHistoryMessage(stripped) : stripped;
+		const sanitized = sanitizeToolIds ? sanitizeToolHistoryMessage(stripped, options.preserveBoundedCompositeToolIds === true) : stripped;
 		if (stripped !== message || sanitized !== stripped) changed = true;
 		filtered.push(sanitized);
 	}
@@ -403,6 +413,7 @@ function registerToolBudget(pi: ExtensionAPI, budget: ResolvedToolBudget | undef
 }
 
 function registerStructuredOutputTool(pi: ExtensionAPI, structured: NonNullable<ChildRuntimeConfig["structuredOutput"]>): void {
+	const terminalState = structured.terminalState ??= { captured: false };
 	const required = structured.acceptanceReport === "required";
 	const parameters = createStructuredOutputToolParameters(structured.schema, { acceptanceReport: structured.acceptanceReport });
 	const registerTool = pi.registerTool as unknown as (tool: {
@@ -414,6 +425,7 @@ function registerStructuredOutputTool(pi: ExtensionAPI, structured: NonNullable<
 	}) => void;
 	registerTool({
 		name: "structured_output",
+		...MODEL_ONLY_TOOL,
 		label: "Structured Output",
 		description: "Submit the required final structured output for this subagent step. This terminates the step.",
 		parameters,
@@ -432,6 +444,7 @@ function registerStructuredOutputTool(pi: ExtensionAPI, structured: NonNullable<
 				}
 			}
 			structured.capture(params.value, structured.acceptanceReport ? params.acceptanceReport : undefined);
+			terminalState.captured = true;
 			return {
 				content: [{ type: "text", text: "Structured output captured." }],
 				details: {},
@@ -451,11 +464,20 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 	registerRuntimeExtensionAcknowledgements(pi, config.runtimeAcknowledgements);
 	registerPermissionGate(pi, config.permissions, config.childWatchdog);
 	registerToolBudget(pi, config.toolBudget);
-	registerChildWatchdog(pi, config.childWatchdog, config.watchdogStatus);
-	const waitState = {
+	if (config.structuredOutput && !config.structuredOutput.terminalState) config.structuredOutput.terminalState = { captured: false };
+	registerChildWatchdog(pi, config.childWatchdog, config.watchdogStatus, config.structuredOutput?.terminalState);
+	const requestedWatchdogDiff = config.requiredTools?.includes(WATCHDOG_DIFF_TOOL_NAME);
+	const reviewerLaunchBaseline = requestedWatchdogDiff && config.cwd
+		? captureWatchdogDiffBaseline(config.cwd)
+		: undefined;
+	if (requestedWatchdogDiff && typeof pi.registerTool === "function") {
+		pi.registerTool(createWatchdogDiffTool(reviewerLaunchBaseline, { workingTreeAtLaunch: true }));
+	}
+	const waitState = config.runtimeState ?? {
 		baseCwd: "",
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
 		cleanupTimers: new Map(),
@@ -466,7 +488,8 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 		watcherRestartTimer: null,
 		resultFileCoalescer: { schedule: () => false, clear: () => {} },
 	} as unknown as SubagentState;
-	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs);
+	const nestedRootRunId = inheritedNestedRouteOf(config)?.rootRunId;
+	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs, { nestedRootRunId });
 	const supervisorMetadata = childSupervisorMetadata(config);
 	let nativeSupervisorClientRegistered = false;
 	const registerNativeSupervisorClientOnce = (): void => {
@@ -487,13 +510,18 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 		if (diagnostic) throw new Error(formatChildToolDiagnostic(diagnostic));
 	});
 	onRuntimeEvent("agent_end", async (_event: unknown, ctx: unknown) => {
-		if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) { drainObservation?.deny(); return; }
+		if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) drainObservation?.deny();
 		if (drainObservation) {
 			try {
 				if ((ctx as ExtensionContext)?.sessionManager?.getSessionFile() !== waitState.currentSessionId) drainObservation.deny();
 			} catch { drainObservation.deny(); }
 		}
-		await drainOutstandingWork({ state: waitState, events: pi.events }, drainObservation);
+		config.holdFinalDrain?.(true);
+		try {
+			await drainOutstandingWork({ state: waitState, events: pi.events, nestedRootRunId, hasPendingSupervisorRequest: config.hasPendingSupervisorRequest }, drainObservation);
+		} finally {
+			config.holdFinalDrain?.(false);
+		}
 	});
 	if (config.structuredOutput) registerStructuredOutputTool(pi, config.structuredOutput);
 
@@ -503,19 +531,30 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 		if (!event || typeof event !== "object" || !("messages" in event) || !Array.isArray(event.messages)) return undefined;
 		const messages = stripParentOnlySubagentMessages(event.messages, {
 			sanitizeToolIds: !COMPOSITE_TOOL_ID_APIS.has(ctx?.model?.api ?? ""),
+			preserveBoundedCompositeToolIds: ctx?.model?.api === "openai-codex-responses",
 			preserveFanoutToolHistory: config.fanoutChild,
 		});
 		if (messages === event.messages) return undefined;
 		return { messages };
 	});
 
+	// pi-intercom asks at session start for this session's intercom ID. Claiming
+	// the route there frees the session name for the readable label. An older
+	// pi-intercom never asks and routes by name, so the route stays the name.
+	const routingName = config.intercomSessionName;
+	let intercomIdClaimed = false;
+	if (routingName) {
+		pi.events.on(INTERCOM_SESSION_IDENTITY_EVENT, (request: unknown) => {
+			if (!request || typeof request !== "object" || !("version" in request) || request.version !== 1 || !("claim" in request) || typeof request.claim !== "function") return;
+			request.claim(routingName);
+			intercomIdClaimed = true;
+		});
+	}
+
 	onRuntimeEvent("before_agent_start", async (event: unknown) => {
 		if (!event || typeof event !== "object" || !("systemPrompt" in event) || typeof event.systemPrompt !== "string") return undefined;
 		registerNativeSupervisorClientOnce();
-		// The intercom target is a routing address and always wins; the display
-		// name (agent + task excerpt, computed by the parent at launch) only
-		// applies when the bridge is not addressing this child.
-		const childSessionName = config.intercomSessionName || config.sessionName;
+		const childSessionName = intercomIdClaimed ? config.sessionName || routingName : routingName || config.sessionName;
 		if (childSessionName && typeof pi.setSessionName === "function") {
 			pi.setSessionName(childSessionName);
 		}
@@ -535,4 +574,4 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 		if (rewritten === event.systemPrompt) return;
 		return { systemPrompt: rewritten };
 	});
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/tool-availability.ts

@@ -21,7 +21,7 @@ export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic, optio
 			...(diagnostic.missingMcpDirectTools?.length
 				? [`MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}.`]
 				: []),
-			"Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) or models from a provider extension must run as background children (`async: true`), which load the ambient extensions.",
+			"MCP tools require background children (`async: true`) because only they load ambient extensions.",
 			"For extension tools a foreground child can load, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
 		].join("\n");
 	}
@@ -29,7 +29,7 @@ export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic, optio
 		`${subject} requested unavailable child tools: ${diagnostic.missing.join(", ")}.`,
 		"The `tools` field is a strict allowlist; it does not load extension code.",
 		...(diagnostic.missingMcpDirectTools?.length
-			? [`Resolved MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}. This indicates a host/pi-mcp-adapter registration problem, not a tool-call failure.`]
+			? [`Resolved MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}. Resolved names must match what the host or pi-mcp-adapter registers; check the MCP direct-tool registration before treating this as a tool-call failure.`]
 			: []),
 		"For extension tools, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
 		"For MCP tools, verify the MCP adapter configuration and selected tool names. For builtin tools, verify the name against the installed Pi version.",

package/dist/extensions/pi-subagents/src/runs/shared/tool-budget.ts

@@ -64,3 +64,24 @@ export function toolBudgetSoftNudge(budget: ResolvedToolBudget, toolCount: numbe
 export function toolBudgetBlockedMessage(budget: ResolvedToolBudget, toolName: string, toolCount: number): string {
 	return `Tool budget hard limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (hard ${budget.hard}). The '${toolName}' tool is blocked so you can finalize from the context you already have.`;
 }
+
+const TOOL_BUDGET_BLOCKED_MESSAGE = /^Tool budget hard limit reached after (\d+) tool calls? \(hard (\d+)\)\. The '([^']+)' tool is blocked so you can finalize from the context you already have\.$/;
+
+/**
+ * Recognizes a hard-block reason generated by toolBudgetBlockedMessage for this exact budget
+ * and tool. A tool result only counts as a budget block when the entire message matches the
+ * runtime format and the embedded hard limit and tool name belong to this run; incidental
+ * occurrences of the phrase inside ordinary tool output are rejected.
+ */
+export function isToolBudgetBlockedMessage(
+	budget: ResolvedToolBudget,
+	resultText: string,
+	blockedTool: string | undefined,
+): boolean {
+	const tool = blockedTool?.trim();
+	if (!tool) return false;
+	const match = TOOL_BUDGET_BLOCKED_MESSAGE.exec(resultText.trim());
+	if (!match) return false;
+	const [, blockedToolCount, hard, namedTool] = match;
+	return Number(hard) === budget.hard && Number(blockedToolCount) > budget.hard && namedTool === tool;
+}

package/dist/extensions/pi-subagents/src/runs/shared/usage-reconciliation.ts

@@ -0,0 +1,73 @@
+import type { Usage } from "../../shared/types.ts";
+
+type UsageMessage = { role?: unknown; timestamp?: unknown; usage?: object };
+
+const usageFields = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const;
+type UsageField = typeof usageFields[number];
+
+const aliases: Record<Exclude<UsageField, "cost">, readonly string[]> = {
+	input: ["input", "inputTokens"],
+	output: ["output", "outputTokens"],
+	cacheRead: ["cacheRead", "cacheReadTokens"],
+	cacheWrite: ["cacheWrite", "cacheWriteTokens"],
+};
+
+function validNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function fieldValue(usage: object | undefined, field: UsageField): number | undefined {
+	if (!usage) return undefined;
+	const values = usage as Record<string, unknown>;
+	if (field === "cost") {
+		const direct = validNumber(values.cost);
+		if (direct !== undefined) return direct;
+		const cost = values.cost;
+		return cost && typeof cost === "object" && !Array.isArray(cost)
+			? validNumber((cost as { total?: unknown }).total)
+			: undefined;
+	}
+	for (const name of aliases[field]) {
+		const value = validNumber(values[name]);
+		if (value !== undefined) return value;
+	}
+	return undefined;
+}
+
+function validTimestamp(message: UsageMessage): string | number | undefined {
+	const value = message.timestamp;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.length > 0) return value;
+	return undefined;
+}
+
+export function reconcileAttemptUsage(live: Usage, messages: readonly UsageMessage[], baseline: number): Usage {
+	if (!Number.isInteger(baseline) || baseline < 0 || messages.length < baseline) return { ...live };
+
+	const persisted: Usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+	const complete: Record<UsageField, boolean> = { input: true, output: true, cacheRead: true, cacheWrite: true, cost: true };
+	let previous: UsageMessage | undefined;
+	for (let index = baseline; index < messages.length; index++) {
+		const message = messages[index]!;
+		if (message.role === "assistant") {
+			const timestamp = validTimestamp(message);
+			const duplicate = previous?.role === "assistant" && timestamp !== undefined && validTimestamp(previous) === timestamp;
+			if (!duplicate) {
+				persisted.turns++;
+				for (const field of usageFields) {
+					const value = fieldValue(message.usage, field);
+					if (value === undefined) complete[field] = false;
+					else persisted[field] += value;
+				}
+			}
+		}
+		previous = message;
+	}
+	if (persisted.turns === 0) return { ...live };
+
+	const reconciled = { ...live, turns: persisted.turns };
+	for (const field of usageFields) {
+		if (complete[field] && Number.isFinite(persisted[field])) reconciled[field] = persisted[field];
+	}
+	return reconciled;
+}

package/dist/extensions/pi-subagents/src/runs/shared/workflow-async-child-guidance.ts

@@ -0,0 +1,18 @@
+import type { AsyncStatus, SubagentState } from "../../shared/types.ts";
+
+/** Projection-only guidance, not a control route or proof of current child liveness. */
+export function workflowAsyncChildSteeringGuidance(status: AsyncStatus, state?: SubagentState): string[] {
+	if (status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")
+		|| !state?.currentSessionId || status.sessionId !== state.currentSessionId
+		|| !state.workflowControllers?.has(status.runId)) return [];
+	const ids = new Set((status.steps ?? []).flatMap((step) =>
+		step.async === true && step.status === "running"
+		&& step.runner?.type !== "external-cli" && step.runner?.type !== "external-job"
+		&& typeof step.runId === "string" && /^[A-Za-z0-9_-]+$/.test(step.runId) && step.runId !== status.runId
+			? [step.runId] : []));
+	if (ids.size === 0) return [];
+	return [
+		"Async children recorded as running; direct steering rechecks controls. Choose an exact child ID (queued does not mean consumed):",
+		...[...ids].map((id) => `  subagent({ action: "steer", id: "${id}", mode: "follow_up", message: "..." })`),
+	];
+}

package/dist/extensions/pi-subagents/src/runs/shared/worktree-cleanup-apply.ts

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
+import { readParallelHandoffManifest } from "./parallel-handoff.ts";
+import { buildWorktreeCleanupPlan, isRegisteredCleanupWorktree, resolveCleanupRepoRoot, samePath, worktreeCleanupContentPayload, worktreeCleanupPlanPath, WORKTREE_CLEANUP_PLAN_TTL_MS, type BuildWorktreeCleanupPlanInput, type WorktreeCleanupPlan, type WorktreeCleanupPlanEntry } from "./worktree-cleanup-plan.ts";
+import { withHandoffWriteLock, withRepositoryWorktreeLock } from "./worktree-lock.ts";
+import { withWorktreeTransaction } from "./worktree.ts";
+
+export type CleanupReceipt = {
+	version: 1; planId: string; repoRoot: string; contentHash: string;
+	state: "applying" | "complete" | "partial";
+	startedAt: number; completedAt?: number; error?: string;
+	entries: Array<{ path: string; branch: string; state: "removing" | "removed" | "kept" | "failed"; reason: string }>;
+};
+
+function assertContainedRealPath(repoRoot: string, candidate: string, create = false): void {
+	const relative = path.relative(repoRoot, candidate);
+	if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error("Cleanup evidence must be inside the selected repository.");
+	let current = repoRoot;
+	for (const segment of relative.split(path.sep)) {
+		current = path.join(current, segment);
+		if (!fs.existsSync(current) && create) fs.mkdirSync(current, { mode: 0o700 });
+		const stat = fs.lstatSync(current);
+		if (stat.isSymbolicLink()) throw new Error(`Cleanup evidence cannot use a symlink: ${current}`);
+	}
+}
+
+export function loadReviewedCleanupPlan(repo: string, planId: string, now = Date.now()): WorktreeCleanupPlan {
+	const repoRoot = resolveCleanupRepoRoot(repo);
+	const file = worktreeCleanupPlanPath(repoRoot, planId);
+	assertContainedRealPath(repoRoot, file);
+	const stat = fs.statSync(file);
+	if (!stat.isFile() || stat.size > 2 * 1024 * 1024) throw new Error("Cleanup plan is not a bounded regular file.");
+	const plan = JSON.parse(fs.readFileSync(file, "utf-8")) as WorktreeCleanupPlan;
+	if (plan.version !== 1 || plan.planId !== planId || plan.repoRoot !== repoRoot || !Number.isFinite(plan.createdAt) || !Number.isFinite(plan.expiresAt) || plan.createdAt > now || (plan.expiresAt <= now && !fs.existsSync(file.replace(/\.json$/, ".claim"))) || plan.expiresAt - plan.createdAt !== WORKTREE_CLEANUP_PLAN_TTL_MS) throw new Error("Cleanup plan is invalid, expired, or belongs to another repository.");
+	if (!Array.isArray(plan.entries) || plan.entries.length > 512 || !Array.isArray(plan.baseDirs) || plan.baseDirs.length !== 1 || !plan.baseDirs.every((item) => typeof item === "string" && path.isAbsolute(item)) || !Array.isArray(plan.metadataPaths) || !plan.metadataPaths.every((item) => typeof item === "string" && path.isAbsolute(item)) || !Array.isArray(plan.pruneCandidates)) throw new Error("Cleanup plan has invalid inventory fields.");
+	const paths = new Set<string>();
+	for (const entry of plan.entries) {
+		if (!entry || typeof entry.path !== "string" || !path.isAbsolute(entry.path) || typeof entry.branch !== "string" || !["remove", "keep", "unknown"].includes(entry.decision) || !entry.preconditions || entry.preconditions.path !== entry.path || entry.preconditions.branch !== entry.branch || !Array.isArray(entry.reasons) || !entry.reasons.every((reason) => typeof reason === "string") || paths.has(entry.path)) throw new Error("Cleanup plan has invalid or duplicate entries.");
+		paths.add(entry.path);
+	}
+	const hash = createHash("sha256").update(JSON.stringify(worktreeCleanupContentPayload(plan))).digest("hex");
+	if (plan.contentHash !== hash) throw new Error("Cleanup plan content hash does not match; create and review a fresh plan.");
+	return plan;
+}
+
+function recordRemoval(entry: WorktreeCleanupPlanEntry): void {
+	const manifest = readParallelHandoffManifest(entry.handoffPath!);
+	if (!manifest || manifest.runId !== entry.runId) throw new Error("Handoff ownership changed before recording removal.");
+	const tasks = manifest.groups.flatMap((group) => group.cleanup.tasks).filter((task) => task.index === entry.taskIndex && samePath(path.resolve(path.dirname(entry.handoffPath!), task.path), entry.path) && task.branch === entry.branch);
+	if (tasks.length !== 1) throw new Error("Handoff task no longer identifies exactly one removed worktree.");
+	if (tasks[0]!.worktreeRemoved) return;
+	tasks[0]!.worktreeRemoved = true;
+	tasks[0]!.branchRemoved = false;
+	tasks[0]!.preserved = true;
+	tasks[0]!.reason = "reviewed cleanup removed worktree; local branch retained";
+	manifest.updatedAt = Date.now();
+	writePrivateAtomicJson(entry.handoffPath!, manifest);
+}
+
+export async function applyReviewedCleanupPlan(input: {
+	repo: string; planId: string; authorized: boolean; signal?: AbortSignal;
+	foregroundRunOwnership?: BuildWorktreeCleanupPlanInput["foregroundRunOwnership"];
+	/** Internal retention seam: shrink the reviewed batch while holding the repository lock. */
+	select?: (plan: WorktreeCleanupPlan) => Set<string>;
+}): Promise<{ receipt: CleanupReceipt; receiptPath: string; reused: boolean }> {
+	if (!input.authorized) throw new Error("Worktree cleanup requires discardWorktree authorization.");
+	return withWorktreeTransaction(() => withRepositoryWorktreeLock(input.repo, async () => {
+		const plan = loadReviewedCleanupPlan(input.repo, input.planId);
+		const claimPath = worktreeCleanupPlanPath(plan.repoRoot, plan.planId).replace(/\.json$/, ".claim");
+		const receiptPath = path.join(claimPath, "receipt.json");
+		assertContainedRealPath(plan.repoRoot, path.dirname(claimPath));
+		try { fs.mkdirSync(claimPath, { mode: 0o700 }); }
+		catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			assertContainedRealPath(plan.repoRoot, receiptPath);
+			// A claimed plan is never destructively replayed, even after interruption.
+			const receipt = JSON.parse(fs.readFileSync(receiptPath, "utf-8")) as CleanupReceipt;
+			if (receipt.version !== 1 || receipt.planId !== plan.planId || receipt.repoRoot !== plan.repoRoot || receipt.contentHash !== plan.contentHash || !Array.isArray(receipt.entries) || !["applying", "complete", "partial"].includes(receipt.state)) throw new Error("Claimed cleanup plan has an invalid receipt; inspect it before creating a fresh plan.");
+			// Reconcile only a journaled attempt whose directory and Git registration
+			// are both gone. A recreated path is never changed or removed on replay.
+			for (const entry of plan.entries.filter((entry) => receipt.state !== "complete" && entry.decision === "remove" && receipt.entries.some((item) => (item?.state === "removing" || item?.state === "removed") && item.path === entry.path && item.branch === entry.branch))) {
+				await new Promise<void>((resolve) => setImmediate(resolve));
+				input.signal?.throwIfAborted();
+				try { fs.lstatSync(entry.path); continue; }
+				catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+				if (!isRegisteredCleanupWorktree(plan.repoRoot, entry.path) && entry.handoffPath) {
+					const item = receipt.entries.find((item) => item.path === entry.path && item.branch === entry.branch)!;
+					if (item.state === "removing") {
+						item.state = "removed";
+						item.reason = "interrupted removal reconciled; local branch retained";
+						writePrivateAtomicJson(receiptPath, receipt);
+					}
+					withHandoffWriteLock(entry.handoffPath, () => recordRemoval(entry));
+				}
+			}
+			return { receipt, receiptPath, reused: true };
+		}
+		const receipt: CleanupReceipt = { version: 1, planId: plan.planId, repoRoot: plan.repoRoot, contentHash: plan.contentHash, state: "applying", startedAt: Date.now(), entries: [] };
+		writePrivateAtomicJson(receiptPath, receipt);
+		try {
+			const selected = input.select?.(plan);
+			for (const entry of plan.entries.filter((item) => item.decision === "remove")) {
+				await new Promise<void>((resolve) => setImmediate(resolve));
+				input.signal?.throwIfAborted();
+				if (selected && !selected.has(entry.path)) {
+					receipt.entries.push({ path: entry.path, branch: entry.branch, state: "kept", reason: "outside the current retention excess" });
+				} else {
+					try {
+						if (!entry.handoffPath) throw new Error("Reviewed entry has no handoff ownership.");
+						withHandoffWriteLock(entry.handoffPath, () => {
+							const manifest = readParallelHandoffManifest(entry.handoffPath!);
+							if (!manifest || manifest.runId !== entry.runId) throw new Error("Handoff ownership changed before cleanup validation.");
+							const fresh = buildWorktreeCleanupPlan({ repo: plan.repoRoot, candidatePaths: [entry.path], handoffPaths: plan.metadataPaths, worktreeBaseDir: path.dirname(plan.baseDirs[0]!), foregroundRunOwnership: input.foregroundRunOwnership });
+							const candidate = fresh.entries.find((item) => item.path === entry.path);
+							if (fresh.warnings?.some((warning) => /capped|failed to inspect/.test(warning)) || !candidate || candidate.decision !== "remove" || candidate.handoffPath !== entry.handoffPath || candidate.runId !== entry.runId || candidate.taskIndex !== entry.taskIndex || candidate.patchPath !== entry.patchPath || JSON.stringify(candidate.preconditions) !== JSON.stringify(entry.preconditions)) {
+								receipt.entries.push({ path: entry.path, branch: entry.branch, state: "kept", reason: candidate?.reasons.join("; ") || "reviewed ownership or Git facts changed" });
+								return;
+							}
+							input.signal?.throwIfAborted();
+							const journalEntry: CleanupReceipt["entries"][number] = { path: entry.path, branch: entry.branch, state: "removing", reason: "removal prepared; outcome not yet recorded" };
+							receipt.entries.push(journalEntry);
+							writePrivateAtomicJson(receiptPath, receipt); // Admit the attempt before Git can remove anything.
+							const removed = spawnSync("git", ["-C", plan.repoRoot, "worktree", "remove", "--", entry.path], { encoding: "utf-8", windowsHide: true });
+							if (removed.status !== 0) throw new Error(removed.error?.message || removed.stderr.trim() || "git worktree remove failed");
+							journalEntry.state = "removed";
+							journalEntry.reason = "worktree removed; local branch retained";
+							writePrivateAtomicJson(receiptPath, receipt); // Evidence precedes secondary manifest bookkeeping.
+							recordRemoval(entry);
+						});
+					} catch (error) {
+						const reason = error instanceof Error ? error.message : String(error);
+						const removed = receipt.entries.find((item) => item.path === entry.path && item.state === "removed");
+						if (removed) { removed.reason += `; removal bookkeeping failed: ${reason}`; receipt.error = reason; }
+						else {
+							const pending = receipt.entries.find((item) => item.path === entry.path && item.state === "removing");
+							if (pending) { pending.reason += `; operation failed: ${reason}`; receipt.error = reason; }
+							else receipt.entries.push({ path: entry.path, branch: entry.branch, state: "failed", reason });
+						}
+					}
+				}
+				writePrivateAtomicJson(receiptPath, receipt);
+			}
+			receipt.state = !receipt.error && receipt.entries.every((entry) => entry.state === "removed") ? "complete" : "partial";
+		} catch (error) {
+			receipt.state = "partial";
+			receipt.error = error instanceof Error ? error.message : String(error);
+		}
+		receipt.completedAt = Date.now();
+		writePrivateAtomicJson(receiptPath, receipt);
+		return { receipt, receiptPath, reused: false };
+	}, { signal: input.signal }));
+}
+
+export function formatCleanupReceipt(result: { receipt: CleanupReceipt; receiptPath: string; reused: boolean }): string {
+	const { receipt } = result;
+	return [`Worktree cleanup ${receipt.planId}: ${receipt.state}${result.reused ? " (previous receipt; plan not replayed)" : ""}`, "Local branches retained.", ...receipt.entries.map((entry) => `- ${entry.path}: ${entry.state}; ${entry.reason}`), ...(receipt.error ? [receipt.error] : []), `Receipt: ${result.receiptPath}`].join("\n");
+}