pi-subagents 0.59.0 → 0.61.0

package/src/runs/shared/acceptance.ts

@@ -678,7 +678,15 @@ function parseAcceptanceReportBody(body: string): { report?: AcceptanceReport; e
 	return validateAcceptanceReport(parseReportJson(body));
 }
 
-function parseUnterminatedAcceptanceReportFence(output: string): { report?: AcceptanceReport; error?: string } {
+interface AcceptanceReportParseResult {
+	report?: AcceptanceReport;
+	error?: string;
+	/** True when an acceptance-report signal was found but its envelope was invalid. */
+	malformed?: boolean;
+	sourcePath?: string;
+}
+
+function parseUnterminatedAcceptanceReportFence(output: string): AcceptanceReportParseResult {
 	const opener = /```acceptance[-_]report\b[^\n]*\n/gi.exec(output);
 	if (!opener) return {};
 	const bodyStart = opener.index + opener[0].length;
@@ -687,13 +695,13 @@ function parseUnterminatedAcceptanceReportFence(output: string): { report?: Acce
 		const validation = validateAcceptanceReport(JSON.parse(output.slice(bodyStart).trim()) as unknown);
 		return validation.report
 			? { report: validation.report }
-			: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+			: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
 	} catch (error) {
-		return { error: `Failed to parse acceptance-report: ${error instanceof Error ? error.message : String(error)}` };
+		return { error: `Failed to parse acceptance-report: ${error instanceof Error ? error.message : String(error)}`, malformed: true };
 	}
 }
 
-function parseGenericJsonAcceptanceReportBody(body: string): { report?: AcceptanceReport; error?: string } {
+function parseGenericJsonAcceptanceReportBody(body: string): AcceptanceReportParseResult {
 	const parsed = parseReportJson(body);
 	const normalized = normalizeAcceptanceReportValue(parsed);
 	const hasCriteriaMarker = normalized.value !== null
@@ -704,12 +712,12 @@ function parseGenericJsonAcceptanceReportBody(body: string): { report?: Acceptan
 	const validation = validateAcceptanceReport(parsed);
 	return validation.report
 		? { report: validation.report }
-		: { error: `Invalid acceptance-report: ${validation.errors.join("; ")}` };
+		: { error: `Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
 }
 
 export const ACCEPTANCE_REPORT_NOT_FOUND = "Structured acceptance report not found.";
 
-export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
+export function parseAcceptanceReport(output: string): AcceptanceReportParseResult {
 	const explicitFencePresent = /```acceptance[-_]report\b/i.test(output);
 	const fenced = fencedBlocks(output, "acceptance[-_]report");
 	const parseErrors: string[] = [];
@@ -722,17 +730,17 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
 			parseErrors.push(error instanceof Error ? error.message : String(error));
 		}
 	}
-	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
+	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}`, malformed: true };
 	if (explicitFencePresent) {
 		const recovered = parseUnterminatedAcceptanceReportFence(output);
 		if (recovered.report || recovered.error) return recovered;
-		return { error: "Failed to parse acceptance-report: Empty or unterminated acceptance-report fence." };
+		return { error: "Failed to parse acceptance-report: Empty or unterminated acceptance-report fence.", malformed: true };
 	}
 	for (const body of fencedBlocks(output, "(?:json|jsonc|json5)")) {
 		try {
 			const parsed = parseGenericJsonAcceptanceReportBody(body);
 			if (parsed.report) return { report: parsed.report };
-			if (parsed.error) return { error: `Failed to parse acceptance-report: ${parsed.error}` };
+			if (parsed.error) return { error: `Failed to parse acceptance-report: ${parsed.error}`, malformed: parsed.malformed };
 		} catch {
 			// Ignore unrelated malformed generic JSON. A recognizable report shape
 			// returns exact validation errors above instead of being mistaken for prose.
@@ -742,20 +750,20 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
 	if (markerIndex !== -1) {
 		const jsonStart = output.indexOf("{", markerIndex);
 		if (jsonStart === -1) {
-			return { error: "Failed to parse acceptance-report: Expected a JSON object after ACCEPTANCE_REPORT:." };
+			return { error: "Failed to parse acceptance-report: Expected a JSON object after ACCEPTANCE_REPORT:.", malformed: true };
 		}
 		const json = extractBalancedJson(output, jsonStart);
 		if (!json) {
-			return { error: "Failed to parse acceptance-report: Unterminated JSON object after ACCEPTANCE_REPORT:." };
+			return { error: "Failed to parse acceptance-report: Unterminated JSON object after ACCEPTANCE_REPORT:.", malformed: true };
 		}
 		try {
 			const parsed = JSON.parse(json) as unknown;
 			const validation = validateAcceptanceReport(parsed);
 			if (validation.report) return { report: validation.report };
-			return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+			return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			return { error: `Failed to parse acceptance-report: ${message}` };
+			return { error: `Failed to parse acceptance-report: ${message}`, malformed: true };
 		}
 	}
 	return { error: ACCEPTANCE_REPORT_NOT_FOUND };
@@ -764,14 +772,18 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
 function parseAcceptanceReportSources(
 	output: string,
 	fileOutput: { content: string; path: string; authoritative?: boolean } | undefined,
-): { report?: AcceptanceReport; error?: string } {
+): AcceptanceReportParseResult {
 	const fromText = () => parseAcceptanceReport(output);
 	const fromFile = () => {
 		if (!fileOutput) return { error: ACCEPTANCE_REPORT_NOT_FOUND };
 		const parsed = parseAcceptanceReport(fileOutput.content);
 		return parsed.report || parsed.error === ACCEPTANCE_REPORT_NOT_FOUND
 			? parsed
-			: { error: `${parsed.error} (in configured output ${fileOutput.path})` };
+			: {
+				...parsed,
+				error: `${parsed.error} (in configured output ${fileOutput.path})`,
+				sourcePath: fileOutput.path,
+			};
 	};
 	const [primary, secondary] = fileOutput?.authoritative ? [fromFile, fromText] : [fromText, fromFile];
 	const first = primary();
@@ -1272,7 +1284,7 @@ export async function evaluateAcceptance(input: {
 	 * be misattributed). Searched for the acceptance report; searched before
 	 * the assistant output when `authoritative` (outputMode "file-only").
 	 */
-	fileOutput?: { content: string; path: string; authoritative?: boolean };
+	fileOutput?: { content: string; path: string; authoritative?: boolean; durable?: boolean };
 	report?: AcceptanceReport;
 	reportError?: string;
 	reviewResult?: AcceptanceReviewResult;
@@ -1296,16 +1308,25 @@ export async function evaluateAcceptance(input: {
 	};
 	if (acceptance.level === "none") return ledger;
 
-	const parsed = input.reportError
+	const parsed: AcceptanceReportParseResult = input.reportError
 		? { error: input.reportError }
 		: input.report
 		? (() => {
 			const validation = validateAcceptanceReport(input.report);
 			return validation.report
 				? { report: validation.report }
-				: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+				: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
 		})()
 		: parseAcceptanceReportSources(input.output, input.fileOutput);
+	const durableFileOutput = input.fileOutput?.authoritative && input.fileOutput.durable ? input.fileOutput : undefined;
+	if (parsed.malformed && parsed.sourcePath && durableFileOutput) {
+		ledger.recovery = {
+			status: "available-for-review",
+			reason: "acceptance-metadata-rejected",
+			reportPath: parsed.sourcePath,
+			reportHash: hash(durableFileOutput.content),
+		};
+	}
 	const needsReport = acceptanceRequiresChildReport(acceptance);
 	if (parsed.report) {
 		ledger.childReport = parsed.report;
@@ -1314,6 +1335,10 @@ export async function evaluateAcceptance(input: {
 	} else if (!input.reportOptional || needsReport || parsed.error !== ACCEPTANCE_REPORT_NOT_FOUND) {
 		ledger.childReportParseError = parsed.error;
 		ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
+		if (ledger.recovery) {
+			ledger.status = "rejected";
+			ledger.evidenceStatus = "rejected";
+		}
 		if (!input.reportOptional) {
 			ledger.status = "rejected";
 			ledger.evidenceStatus = "rejected";

package/src/runs/shared/async-status-projection.ts

@@ -2,6 +2,7 @@ import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-t
 import { formatModelThinking } from "../../shared/formatters.ts";
 import type { AsyncJobState, AsyncJobStep, HostStepFreshnessV1, HostStepMonitorKind, HostStepNodeV1, HostStepState, HostStepVerdict, NestedRunSummary, NestedStepSummary, SubagentRunMode, WorkflowGraphSnapshot, WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../../shared/types.ts";
 import { HOST_STEP_MAX_COUNT, HOST_STEP_MAX_DETAIL_CHARS, HOST_STEP_MAX_LABEL_CHARS, HOST_STEP_MAX_PROVIDER_CHARS, HOST_STEP_MAX_REASON_CHARS, HOST_STEP_MAX_REF_CHARS, HOST_STEP_MAX_ROLE_CHARS, HOST_STEP_MAX_TARGET_CHARS, hostStepReportName, parseHostStepNode, validHostStepNodes } from "./host-step-status.ts";
+import { workflowGraphStageNodes } from "./workflow-graph.ts";
 
 export const ASYNC_STATUS_SNAPSHOT_KIND = "pi-subagents.async-status-snapshot";
 export const ASYNC_STATUS_SNAPSHOT_VERSION = 1;
@@ -15,6 +16,21 @@ const DEFAULT_MAX_SERIALIZED_BYTES = 32 * 1024;
 export type AsyncStatusSnapshotState = "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
 export type AsyncStatusSnapshotKind = "subagent" | "workflow" | "step";
 
+const ASYNC_STATUS_SNAPSHOT_STATES: Record<AsyncStatusSnapshotState, true> = {
+	queued: true,
+	running: true,
+	complete: true,
+	failed: true,
+	partial: true,
+	paused: true,
+	stopped: true,
+	rejected: true,
+};
+
+function isAsyncStatusSnapshotState(value: string): value is AsyncStatusSnapshotState {
+	return Object.hasOwn(ASYNC_STATUS_SNAPSHOT_STATES, value);
+}
+
 export interface AsyncStatusSnapshotActivityV1 {
 	state?: string;
 	currentTool?: string;
@@ -87,6 +103,7 @@ export interface AsyncStatusWorkflowRow {
 	state: AsyncJobStep["status"] | HostStepState | "planned";
 	/** Present only for typed host-owned monitor rows; legacy child rows omit it. */
 	kind?: HostStepMonitorKind;
+	context?: AsyncJobStep["context"];
 	modelThinking?: string;
 	activity?: string;
 	startedAt?: number;
@@ -155,7 +172,8 @@ function publicCount(value: unknown): number | undefined {
 function normalizeState(value: string): AsyncStatusSnapshotState {
 	if (value === "completed") return "complete";
 	if (value === "pending") return "queued";
-	return value as AsyncStatusSnapshotState;
+	if (isAsyncStatusSnapshotState(value)) return value;
+	return "partial";
 }
 
 function terminalState(state: AsyncStatusSnapshotState): boolean {
@@ -230,6 +248,16 @@ function projectStep(step: AsyncJobStep | NestedStepSummary, index: number, dept
 	return node;
 }
 
+function projectWorkflowGraphNode(node: WorkflowGraphSnapshot["nodes"][number], index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNodeV1 {
+	const step: AsyncJobStep = {
+		agent: node.agent ?? node.label,
+		status: workflowGraphStepStatus(node.status),
+		workflowKey: node.id,
+		label: node.label,
+	};
+	return projectStep(step, node.flatIndex ?? index, depth, ctx);
+}
+
 function projectNestedRun(child: NestedRunSummary, index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNodeV1 {
 	const state = normalizeState(child.state);
 	const startedAt = publicTime(child.startedAt);
@@ -310,9 +338,14 @@ function projectRun(job: AsyncJobState, ctx: ProjectionContext): AsyncStatusSnap
 	};
 	if (ctx.caps.maxDepth > 0) {
 		const stepChildren = job.steps?.map((step, index) => projectStep(step, step.index ?? index, 1, ctx)) ?? [];
+		const loadedKeys = new Set(job.steps?.flatMap((step) => step.workflowKey ? [step.workflowKey] : []) ?? []);
+		const graphStages = job.mode === "workflow" ? workflowGraphStageNodes(job.workflowGraph) : [];
+		const graphChildren = graphStages
+			.filter((graphNode) => !loadedKeys.has(graphNode.id))
+			.map((graphNode, index) => projectWorkflowGraphNode(graphNode, index, 1, ctx));
 		const nestedChildren = job.nestedChildren?.map((child, index) => projectNestedRun(child, index, 1, ctx)) ?? [];
 		const hostStepChildren = validHostStepList(job.hostSteps).map((hostStep) => projectHostStep(hostStep, ctx));
-		const ordinaryChildren = [...stepChildren, ...nestedChildren];
+		const ordinaryChildren = [...stepChildren, ...graphChildren, ...nestedChildren];
 		const retainedHostSteps = hostStepChildren.slice(0, ctx.caps.maxChildrenPerNode);
 		const retainedOrdinaryChildren = ordinaryChildren.slice(0, ctx.caps.maxChildrenPerNode - retainedHostSteps.length);
 		const bounded: AsyncStatusSnapshotNodeV1[] = [];
@@ -320,7 +353,10 @@ function projectRun(job: AsyncJobState, ctx: ProjectionContext): AsyncStatusSnap
 		ctx.omitted.children += ordinaryChildren.length - retainedOrdinaryChildren.length + hostStepChildren.length - retainedHostSteps.length;
 		if (bounded.length) node.children = bounded;
 	} else {
-		ctx.omitted.children += (job.steps?.length ?? 0) + (job.nestedChildren?.length ?? 0) + validHostStepList(job.hostSteps).length;
+		const loadedKeys = new Set(job.steps?.flatMap((step) => step.workflowKey ? [step.workflowKey] : []) ?? []);
+		const graphStages = job.mode === "workflow" ? workflowGraphStageNodes(job.workflowGraph) : [];
+		const graphCount = graphStages.filter((graphNode) => !loadedKeys.has(graphNode.id)).length;
+		ctx.omitted.children += (job.steps?.length ?? 0) + graphCount + (job.nestedChildren?.length ?? 0) + validHostStepList(job.hostSteps).length;
 	}
 	return node;
 }
@@ -392,6 +428,50 @@ function isWorkflowPreflight(value: readonly HostStepNodeV1[] | WorkflowGraphSna
 	return value !== undefined && !Array.isArray(value) && "lanes" in value;
 }
 
+function isWorkflowGraph(value: readonly HostStepNodeV1[] | WorkflowGraphSnapshot | WorkflowPreflightV1 | undefined): value is WorkflowGraphSnapshot {
+	return value !== undefined && !Array.isArray(value) && "nodes" in value;
+}
+
+function workflowGraphRowState(status: WorkflowGraphSnapshot["nodes"][number]["status"]): AsyncStatusWorkflowRow["state"] {
+	switch (status) {
+		case "pending":
+			return "planned";
+		case "completed":
+			return "complete";
+		case "detached":
+			return "paused";
+		default:
+			return status;
+	}
+}
+
+function workflowGraphStepStatus(status: WorkflowGraphSnapshot["nodes"][number]["status"]): AsyncJobStep["status"] {
+	switch (status) {
+		case "completed":
+			return "complete";
+		case "detached":
+			return "paused";
+		default:
+			return status;
+	}
+}
+
+function workflowGraphRowName(node: WorkflowGraphSnapshot["nodes"][number]): string {
+	const key = publicText(node.id, "stage", HOST_STEP_MAX_LABEL_CHARS);
+	const label = publicOptionalText(node.label, HOST_STEP_MAX_LABEL_CHARS);
+	const phase = publicOptionalText(node.phase, HOST_STEP_MAX_LABEL_CHARS);
+	const agent = publicOptionalText(node.agent, HOST_STEP_MAX_LABEL_CHARS);
+	return `${phase ? `${phase}: ` : ""}${key}${label && label !== node.id ? ` · ${label}` : ""}${agent ? ` (${agent})` : ""}`;
+}
+
+function projectWorkflowGraphRow(node: WorkflowGraphSnapshot["nodes"][number], preflight?: WorkflowPreflightLaneV1): AsyncStatusWorkflowRow {
+	return {
+		name: workflowGraphRowName(node),
+		state: workflowGraphRowState(node.status),
+		...(preflight ? { preflight } : {}),
+	};
+}
+
 /** Project loaded workflow child facts plus stored preflight hints into compact rows. */
 export function projectAsyncWorkflowRows(
 	steps: readonly AsyncJobStep[] | undefined,
@@ -399,9 +479,62 @@ export function projectAsyncWorkflowRows(
 	preflightOverride?: WorkflowPreflightV1,
 ): AsyncStatusWorkflowRow[] {
 	const preflight = preflightOverride ?? (isWorkflowPreflight(hostStepsOrPreflight) ? hostStepsOrPreflight : undefined);
-	const hostSteps = isWorkflowPreflight(hostStepsOrPreflight) ? undefined : hostStepsOrPreflight;
+	const graph = isWorkflowGraph(hostStepsOrPreflight) ? hostStepsOrPreflight : undefined;
+	const hostSteps = isWorkflowPreflight(hostStepsOrPreflight) || graph ? undefined : hostStepsOrPreflight;
 	const loaded = steps ?? [];
 	const declared = new Map<string, WorkflowPreflightLaneV1>();
+	if (graph) {
+		const loadedIndexesByKey = new Map<string, number[]>();
+		for (const [index, step] of loaded.entries()) {
+			if (!step.workflowKey) continue;
+			const indexes = loadedIndexesByKey.get(step.workflowKey) ?? [];
+			indexes.push(index);
+			loadedIndexesByKey.set(step.workflowKey, indexes);
+		}
+		const consumed = new Set<number>();
+		const childRows: AsyncStatusWorkflowRow[] = [];
+		for (const lane of preflight?.lanes ?? []) declared.set(lane.key, lane);
+		const graphStages = workflowGraphStageNodes(graph);
+		const graphKeys = new Set(graphStages.map((node) => node.id));
+		const graphPhaseByNodeId = new Map<string, string>();
+		for (const phase of graph.phases) {
+			for (const nodeId of phase.nodeIds) {
+				if (graphKeys.has(nodeId) && !graphPhaseByNodeId.has(nodeId)) graphPhaseByNodeId.set(nodeId, phase.title);
+			}
+		}
+		const graphLaneKeys = new Set(graphPhaseByNodeId.values());
+		const preflightForNode = (node: WorkflowGraphSnapshot["nodes"][number]): WorkflowPreflightLaneV1 | undefined => {
+			const phaseTitle = graphPhaseByNodeId.get(node.id);
+			return declared.get(node.id) ?? (node.phase ? declared.get(node.phase) : undefined) ?? (phaseTitle ? declared.get(phaseTitle) : undefined);
+		};
+		for (const node of graphStages) {
+			const indexes = (loadedIndexesByKey.get(node.id) ?? []).filter((index) => !consumed.has(index));
+			if (indexes.length > 0) {
+				for (const index of indexes) {
+					consumed.add(index);
+					childRows.push(projectLoadedWorkflowRow(loaded[index]!, index, preflightForNode(node)));
+				}
+			} else {
+				childRows.push(projectWorkflowGraphRow(node, preflightForNode(node)));
+			}
+		}
+		for (const lane of preflight?.lanes ?? []) {
+			if (graphKeys.has(lane.key) || graphLaneKeys.has(lane.key)) continue;
+			const indexes = (loadedIndexesByKey.get(lane.key) ?? []).filter((index) => !consumed.has(index));
+			if (indexes.length > 0) {
+				for (const index of indexes) {
+					consumed.add(index);
+					childRows.push(projectLoadedWorkflowRow(loaded[index]!, index, lane));
+				}
+			} else {
+				childRows.push({ name: lane.key, state: "planned", preflight: lane });
+			}
+		}
+		for (const [index, step] of loaded.entries()) {
+			if (!consumed.has(index)) childRows.push(projectLoadedWorkflowRow(step, index, step.workflowKey ? declared.get(step.workflowKey) : undefined));
+		}
+		return [...childRows, ...validHostStepList(graph).map(hostStepRow)];
+	}
 	const loadedIndexByKey = new Map<string, number>();
 	for (const [index, step] of loaded.entries()) {
 		if (step.workflowKey !== undefined && !loadedIndexByKey.has(step.workflowKey)) loadedIndexByKey.set(step.workflowKey, index);
@@ -431,6 +564,7 @@ function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?:
 	return {
 		name: workflowStepName(step, index),
 		state: step.status,
+		...(step.context ? { context: step.context } : {}),
 		...(modelThinking ? { modelThinking } : {}),
 		...(activity ? { activity } : {}),
 		...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),

package/src/runs/shared/background-process-options.ts

@@ -0,0 +1,9 @@
+export function backgroundProcessOptions(platform: NodeJS.Platform = process.platform): {
+	detached: boolean;
+	windowsHide: true;
+} {
+	return {
+		detached: platform !== "win32",
+		windowsHide: true,
+	};
+}

package/src/runs/shared/host-step-status.ts

@@ -144,6 +144,7 @@ export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): Ho
 export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | undefined, source = "status", expectedRunId?: string): void {
 	if (!graph) return;
 	if (expectedRunId !== undefined && graph.runId !== expectedRunId) throw new Error(`Invalid host step '${source}': workflowGraph.runId does not match the status run id.`);
+	if (!Array.isArray(graph.nodes)) throw new Error(`Invalid host step '${source}.workflowGraph': nodes must be an array.`);
 	const hostStepCount = graph.nodes.filter((node) => node.kind === "host-step").length;
 	if (hostStepCount > HOST_STEP_MAX_COUNT) throw new Error(`Invalid host step '${source}': workflowGraph contains more than ${HOST_STEP_MAX_COUNT} host steps.`);
 	const hostSteps: HostStepNodeV1[] = [];

package/src/runs/shared/mcp-direct-tool-grant.ts

@@ -125,11 +125,8 @@ export function formatUnresolvedMcpDirectToolSelectors(selectors: readonly strin
 
 function getServerPrefix(serverName: string, mode: McpToolPrefix): string {
 	if (mode === "none") return "";
-	if (mode === "short") {
-		const short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
-		return short || "mcp";
-	}
-	return serverName.replace(/-/g, "_");
+	if (mode === "short") return serverName.replace(/-?mcp$/i, "") || "mcp";
+	return serverName;
 }
 
 function formatToolName(toolName: string, serverName: string, prefix: McpToolPrefix): string {

package/src/runs/shared/model-fallback.ts

@@ -321,15 +321,23 @@ export function resolveSubagentModelOverride(
 	const explicit = trimmed && trimmed !== INHERIT_MODEL ? trimmed : undefined;
 	if (!parentModel) throwForUnresolvedEnforcedInheritScope(options?.scope, explicit === undefined || options?.source === "inherited");
 	let resolved: string | undefined;
+	let resolvedFromRegistry = explicit === undefined;
 	if (explicit === undefined) {
 		resolved = parentModel ? `${parentModel.provider}/${parentModel.id}` : undefined;
 	} else {
-		resolved = resolveRequiredSubagentModelCandidate(explicit, availableModels, preferredProvider);
-	}
-	if (resolved && explicit !== undefined && options?.source === "explicit") {
-		throwForExplicitModelExclusion(resolved);
+		const candidate = resolveSubagentModelCandidate(explicit, availableModels, preferredProvider);
+		if (options?.source === "explicit") {
+			resolved = candidate ?? resolveRequiredSubagentModelCandidate(explicit, availableModels, preferredProvider);
+			throwForExplicitModelExclusion(resolved);
+			resolvedFromRegistry = true;
+		} else if (candidate) {
+			resolved = candidate;
+			resolvedFromRegistry = true;
+		} else {
+			resolved = explicit;
+		}
 	}
-	if (resolved && options?.scope) {
+	if (resolved && options?.scope && resolvedFromRegistry) {
 		const source: ModelSource = explicit === undefined ? "inherited" : (options.source ?? "inherited");
 		enforceModelScopes(resolved, options.scope, source, options.onWarn);
 	}
@@ -362,12 +370,33 @@ export function resolveEffectiveSubagentModel(
 	);
 }
 
+export type ModelOrigin = ModelSource | "configured";
+
 export interface BuildModelCandidatesOptions {
 	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
 	scope?: ModelScopeCheckRule | ModelScopeCheckRule[];
 	onWarn?: (violation: ModelScopeViolation) => void;
 	/** The primary model came from the running parent session, not configuration. */
 	primaryModelFromParent?: boolean;
+	/** How the primary model was selected. Explicit stays strict and does not rotate to fallbacks. */
+	origin?: ModelOrigin;
+}
+
+const ZERO_USABLE_MODEL_CANDIDATES_ERROR =
+	"No usable subagent models remain after registry, scope, and cached-exclusion filtering.";
+
+export function resolveModelOrigin(input: {
+	explicitModel?: string | boolean;
+	agentModel?: string | boolean;
+	parentModel?: ParentModel;
+	fromParent?: boolean;
+	storedOrigin?: ModelOrigin;
+}): ModelOrigin {
+	if (input.storedOrigin) return input.storedOrigin;
+	if (input.fromParent) return "inherited";
+	if (inheritsParentModel(input.explicitModel, input.agentModel, input.parentModel)) return "inherited";
+	const trimmed = typeof input.explicitModel === "string" ? input.explicitModel.trim() : "";
+	return trimmed && trimmed !== INHERIT_MODEL ? "explicit" : "configured";
 }
 
 export function inheritsParentModel(
@@ -388,36 +417,51 @@ export function buildModelCandidates(
 	options?: BuildModelCandidatesOptions,
 ): string[] {
 	if (!primaryModel) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
+	const origin = options?.origin ?? (options?.primaryModelFromParent ? "inherited" : "configured");
+	const scopes = configuredScopes(options?.scope);
+	const warnCachedExclusion = (candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>) => {
+		const reason = redactSecretValues((exclusion.reason ?? "runtime-failure").replace(/[\u0000-\u001f\u007f]+/g, " ")).slice(0, 240);
+		console.warn(`[pi-subagents] Skipping model '${candidate}' due to a cached exclusion (reason: ${reason}; expires: ${new Date(exclusion.expiresAt).toISOString()}).`);
+	};
+	if (origin === "explicit" && primaryModel) {
+		const normalized = resolveRequiredSubagentModelCandidate(primaryModel.trim(), availableModels, preferredProvider);
+		throwForExplicitModelExclusion(normalized);
+		enforceModelScopes(normalized, scopes, "explicit", options?.onWarn);
+		primaryModel = normalized;
+	}
 	const seen = new Set<string>();
 	const candidates: string[] = [];
 	const rawCandidates = [primaryModel, ...(fallbackModels ?? [])];
+	let skippedPrimary: string | undefined;
 	for (let index = 0; index < rawCandidates.length; index++) {
 		const raw = rawCandidates[index];
 		if (!raw) continue;
 		const model = raw.trim();
-		const normalized = index === 0
-			? options?.primaryModelFromParent
-				? model
-				: resolveRequiredSubagentModelCandidate(model, availableModels, preferredProvider)
+		const normalized = index === 0 && (origin === "inherited" || origin === "explicit" || options?.primaryModelFromParent)
+			? model
 			: resolveSubagentModelCandidate(model, availableModels, preferredProvider);
 		if (!normalized) {
-			console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
+			if (index === 0) skippedPrimary = model;
+			else console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
 			continue;
 		}
 		if (seen.has(normalized)) continue;
-		const scopes = configuredScopes(options?.scope);
 		if (index > 0 || scopes.some((scope) => scope.enforce === true && scope.strict === true)) {
 			enforceModelScopes(normalized, scopes, "inherited", options?.onWarn);
 		}
 		seen.add(normalized);
 		candidates.push(normalized);
 	}
-	return filterFallbackCandidates(candidates, {
-		onExcluded(candidate, exclusion) {
-			const reason = redactSecretValues((exclusion.reason ?? "runtime-failure").replace(/[\u0000-\u001f\u007f]+/g, " ")).slice(0, 240);
-			console.warn(`[pi-subagents] Skipping model '${candidate}' due to a cached exclusion (reason: ${reason}; expires: ${new Date(exclusion.expiresAt).toISOString()}).`);
-		},
-	});
+	const resolved = filterFallbackCandidates(candidates, { onExcluded: warnCachedExclusion });
+	if (resolved.length === 0) {
+		if (skippedPrimary) resolveRequiredSubagentModelCandidate(skippedPrimary, availableModels, preferredProvider);
+		if (candidates.length > 0) throw new Error(ZERO_USABLE_MODEL_CANDIDATES_ERROR);
+		return resolved;
+	}
+	if (skippedPrimary) {
+		console.warn(`[pi-subagents] Skipping primary model '${skippedPrimary}' because it is unavailable in this environment.`);
+	}
+	return resolved;
 }
 
 const RETRYABLE_MODEL_FAILURE_PATTERNS = [

package/src/runs/shared/mutation-evidence.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { ArtifactPaths, TimeoutRecoverySummary, TrackedMutationEvidence, TrackedMutationFingerprint, TrackedMutationSnapshot } from "../../shared/types.ts";
+import type { ArtifactPaths, TimeoutRecoveryProjection, TimeoutRecoverySummary, TrackedMutationEvidence, TrackedMutationFingerprint, TrackedMutationSnapshot } from "../../shared/types.ts";
 
 const MAX_TRACKED_PATHS = 500;
 const MAX_HASH_BYTES = 1024 * 1024;
@@ -15,7 +15,7 @@ function gitArguments(args: string[]): string[] {
 }
 
 function gitOutput(cwd: string, args: string[], maxBuffer = MAX_HASH_BYTES): string {
-	return execFileSync("git", gitArguments(args), { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer });
+	return execFileSync("git", gitArguments(args), { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer, windowsHide: true });
 }
 
 function splitNul(output: string): string[] {
@@ -26,7 +26,7 @@ function hashLargeDiff(cwd: string, relativePath: string): string {
 	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tracked-diff-"));
 	const diffPath = path.join(tempDir, "diff.patch");
 	try {
-		execFileSync("git", gitArguments(["diff", "--no-ext-diff", "--binary", `--output=${diffPath}`, "HEAD", "--", relativePath]), { cwd, stdio: "ignore" });
+		execFileSync("git", gitArguments(["diff", "--no-ext-diff", "--binary", `--output=${diffPath}`, "HEAD", "--", relativePath]), { cwd, stdio: "ignore", windowsHide: true });
 		const hash = createHash("sha256");
 		const buffer = Buffer.allocUnsafe(64 * 1024);
 		const fd = fs.openSync(diffPath, "r");
@@ -110,9 +110,48 @@ function formatPathList(paths: string[]): string {
 	return paths.length > MAX_TIMEOUT_FILES ? `${shown}, ... (${paths.length - MAX_TIMEOUT_FILES} more)` : shown;
 }
 
+/** Keep status and completion details to bounded routing evidence, not raw output or effects. */
+export function projectTimeoutRecovery(value: unknown): TimeoutRecoveryProjection | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const source = value as Record<string, unknown>;
+	const termination = source.termination === "timed-out" || source.termination === "stopped" ? source.termination : undefined;
+	if (!termination || !Array.isArray(source.changedFiles)) return undefined;
+	const allChangedFiles = source.changedFiles.filter((file): file is string => typeof file === "string");
+	const changedFiles = allChangedFiles.slice(0, MAX_TIMEOUT_FILES);
+	const reportStatus = source.reportStatus === "missing"
+		|| source.reportStatus === "written"
+		|| source.reportStatus === "not-requested"
+		|| source.reportStatus === "unknown"
+		? source.reportStatus
+		: undefined;
+	return {
+		termination,
+		changedFiles,
+		...(source.truncated === true || allChangedFiles.length > changedFiles.length ? { truncated: true } : {}),
+		...(source.recoveryNeeded === true ? { recoveryNeeded: true } : {}),
+		...(source.reason === "timed-out-with-dirty-worktree" ? { reason: source.reason } : {}),
+		...(reportStatus ? { reportStatus } : {}),
+	};
+}
+
+/** Render only the bounded recovery route needed by a parent/operator. */
+export function formatTimeoutRecoveryLines(value: unknown, indent = ""): string[] {
+	const recovery = projectTimeoutRecovery(value);
+	if (!recovery?.recoveryNeeded) return [];
+	const changedFiles = recovery.changedFiles.length > 0
+		? `${recovery.changedFiles.join(", ")}${recovery.truncated ? ", …" : ""}`
+		: "none";
+	const changedFileCount = recovery.changedFiles.length > 0 ? `${recovery.changedFiles.length}${recovery.truncated ? "+" : ""}` : "0";
+	return [
+		`${indent}Recovery needed: review the diff and artifacts before resuming or launching dependent stages.`,
+		`${indent}Recovery evidence: requested report: ${recovery.reportStatus ?? "unknown"}; changed tracked files: ${changedFiles} (${changedFileCount}); classification: ${recovery.reason ?? recovery.termination}`,
+	];
+}
+
 export function buildTimeoutRecoverySummary(input: {
 	termination: "timed-out" | "stopped";
 	evidence: TrackedMutationEvidence;
+	requiredOutputMissing?: boolean;
 	currentTool?: string;
 	currentToolArgs?: string;
 	currentPath?: string;
@@ -122,11 +161,19 @@ export function buildTimeoutRecoverySummary(input: {
 }): TimeoutRecoverySummary {
 	const warning = "Inspect partial changes before retrying or resuming the child.";
 	const changedFiles = input.evidence.changedFiles.slice(0, MAX_TIMEOUT_FILES);
+	let reportStatus: "missing" | "written" | "not-requested" = "not-requested";
+	if (input.requiredOutputMissing === true) reportStatus = "missing";
+	else if (input.requiredOutputMissing === false) reportStatus = "written";
+	const recoveryNeeded = input.termination === "timed-out"
+		&& reportStatus === "missing"
+		&& input.evidence.changedFiles.length > 0;
 	const lines = [
 		"Recovery summary:",
 		`- termination: ${input.termination}`,
 		`- changed tracked files: ${input.evidence.unavailable ? `unavailable (${input.evidence.unavailable})` : formatPathList(input.evidence.changedFiles)}`,
 	];
+	if (input.requiredOutputMissing !== undefined) lines.push(`- requested report: ${reportStatus}`);
+	if (recoveryNeeded) lines.push("- Recovery needed: review the diff and artifacts before resuming or launching dependent stages.");
 	if (input.currentTool) lines.push(`- active tool: ${input.currentTool}${input.currentToolArgs ? ` — ${input.currentToolArgs}` : ""}`);
 	if (input.currentPath) lines.push(`- active path: ${input.currentPath}`);
 	if (input.sessionFile) lines.push(`- session file: ${input.sessionFile}`);
@@ -138,6 +185,8 @@ export function buildTimeoutRecoverySummary(input: {
 		termination: input.termination,
 		changedFiles,
 		truncated: input.evidence.changedFiles.length > changedFiles.length || input.evidence.truncated || undefined,
+		...(recoveryNeeded ? { recoveryNeeded: true, reason: "timed-out-with-dirty-worktree" as const } : {}),
+		reportStatus,
 		currentTool: input.currentTool,
 		currentToolArgs: input.currentToolArgs,
 		currentPath: input.currentPath,

package/src/runs/shared/permissions.ts

@@ -7,7 +7,7 @@ export interface PermissionConfig { rules?: PermissionRules }
 
 export const PERMISSION_POLICY_ENV = "PI_SUBAGENT_PERMISSION_POLICY";
 export const PERMISSION_AUDIT_PATH_ENV = "PI_SUBAGENT_PERMISSION_AUDIT_PATH";
-const INTERNAL_TOOLS = new Set(["contact_supervisor", "intercom", "subagent_wait", "structured_output"]);
+const INTERNAL_TOOLS = new Set(["contact_supervisor", "intercom", "bg_wait", "subagent_wait", "structured_output"]);
 const DECISIONS = new Set<PermissionDecision>(["allow", "ask", "deny"]);
 const MAX_POLICY_BYTES = 16 * 1024;
 const MAX_PREVIEW_BYTES = 2048;