pi-subagents 0.65.1 → 0.66.0

package/src/runs/shared/child-launch.ts

@@ -6,12 +6,13 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ChildWatchdogConfig, ChildWatchdogStatusEvent } from "../../watchdog/child-status.ts";
 import type { ThinkingLevel } from "../../shared/model-info.ts";
 import { intersectThinkingCeilings } from "../../shared/thinking-ceiling.ts";
 import {
 	resolveChildDepth,
-	type LaunchResolvedChildExtensionsV1,
+	type LaunchResolvedChildExtensions,
 	type ResolvedToolBudget,
 	type RunFanoutBudgetDescriptor,
 } from "../../shared/types.ts";
@@ -20,8 +21,7 @@ import type { McpRuntimeSnapshotHost } from "./mcp-direct-tool-allowlist.ts";
 import type { PermissionRules } from "./permissions.ts";
 import type { StructuredOutputRuntime } from "./structured-output.ts";
 import type { ChildToolDiagnostic } from "./tool-availability.ts";
-import type { RuntimeAcknowledgedChildExtensionsV1 } from "../../shared/types.ts";
-import { projectRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
+import type { RuntimeAcknowledgedChildExtensions } from "../../shared/types.ts";
 import { encodeExtensionBindings, PI_SUBAGENT_EXTENSION_BINDINGS_ENV, type ExtensionBindings } from "./extension-bindings.ts";
 import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "./capability-ceiling.ts";
 import {
@@ -32,7 +32,8 @@ import {
 	type PiLaunchToolPlan,
 } from "./child-tool-plan.ts";
 import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
-import { createChildHooks } from "./child-hooks.ts";
+import { createCapturedChildHooks, withChildSessionErrorReporting } from "./child-hooks.ts";
+import type { ChildTranscriptWriter } from "../../shared/child-transcript.ts";
 import type { ChildSessionLaunch, ChildSessionStorage } from "./child-session.ts";
 
 /** Environment variable pi-mcp-adapter reads for the tools a child may expose. */
@@ -114,9 +115,10 @@ export interface BuildInProcessChildLaunchInput {
 }
 
 export interface InProcessChildCapture {
+	completionIntentContext?(): Pick<ExtensionContext, "model" | "modelRegistry"> | undefined;
 	structuredOutput(): { called: boolean; value?: unknown; acceptanceReport?: unknown; acceptanceReportProvided: boolean };
 	toolDiagnostic(): ChildToolDiagnostic | undefined;
-	runtimeAcknowledgedExtensions(): RuntimeAcknowledgedChildExtensionsV1 | undefined;
+	runtimeAcknowledgedExtensions(): RuntimeAcknowledgedChildExtensions | undefined;
 }
 
 export interface InProcessChildLaunch {
@@ -124,11 +126,16 @@ export interface InProcessChildLaunch {
 	config: ChildRuntimeConfig;
 	session: Omit<ChildSessionLaunch, "onExtensionError">;
 	capture: InProcessChildCapture;
-	launchResolvedExtensions: LaunchResolvedChildExtensionsV1;
+	launchResolvedExtensions: LaunchResolvedChildExtensions;
 	warnings: string[];
 	capabilityAudit?: SubagentCapabilityAudit;
 }
 
+/** Actual host create-input boundary. Evidence remains explicitly opt-in and dormant in production. */
+export function createReportedChildSessionInput(launch: InProcessChildLaunch, transcriptWriter?: ChildTranscriptWriter): ChildSessionLaunch {
+	return withChildSessionErrorReporting(launch.session, transcriptWriter);
+}
+
 /** Escape XML-significant characters in a string for safe attribute interpolation. */
 function escapeXmlAttr(value: string): string {
 	return value
@@ -214,8 +221,6 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 	let structuredAcceptanceReport: unknown;
 	let structuredCalled = false;
 	let structuredAcceptanceProvided = false;
-	let toolDiagnostic: ChildToolDiagnostic | undefined;
-	let acknowledgedIds: string[] | undefined;
 
 	const config: ChildRuntimeConfig = {
 		...(input.runId ? { runId: input.runId } : {}),
@@ -264,10 +269,9 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 			: {}),
 		...(toolPlan.requiredChildTools.length > 0 ? { requiredTools: toolPlan.requiredChildTools } : {}),
 		...(toolPlan.effectiveMcpTools.length > 0 ? { mcpDirectTools: toolPlan.effectiveMcpTools } : {}),
-		toolDiagnostic: (diagnostic) => { toolDiagnostic = diagnostic; },
-		runtimeAcknowledgements: (ids) => { acknowledgedIds = ids; },
 		fast: input.fast === true,
 	};
+	const capturedHooks = createCapturedChildHooks(config, input.host === "runner");
 
 	const extensionPaths = toolPlan.extensionArgs.filter((extensionPath) => !isSubagentRuntimeExtensionPath(extensionPath));
 	const ambientExtensions = input.host === "runner" && !toolPlan.disableAmbientExtensions;
@@ -288,7 +292,7 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 		...(!toolPlan.explicitToolAllowlist && toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
 		extensionPaths,
 		ambientExtensions,
-		hooks: createChildHooks(config),
+		hooks: capturedHooks.hooks,
 		...(input.host === "runner" ? { processEnv: childProcessEnv(input, toolPlan) } : {}),
 		runtime: config,
 		noSkills: !input.inheritSkills,
@@ -303,9 +307,10 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 		config,
 		session,
 		capture: {
+			completionIntentContext: capturedHooks.completionIntentContext,
 			structuredOutput: () => ({ called: structuredCalled, value: structuredValue, acceptanceReport: structuredAcceptanceReport, acceptanceReportProvided: structuredAcceptanceProvided }),
-			toolDiagnostic: () => toolDiagnostic,
-			runtimeAcknowledgedExtensions: () => (acknowledgedIds ? projectRuntimeAcknowledgedExtensions(acknowledgedIds) : undefined),
+			toolDiagnostic: capturedHooks.toolDiagnostic,
+			runtimeAcknowledgedExtensions: capturedHooks.runtimeAcknowledgedExtensions,
 		},
 		launchResolvedExtensions,
 		warnings: toolPlan.warnings,

package/src/runs/shared/child-session.ts

@@ -12,6 +12,14 @@ import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "../../shared/utils.ts";
 import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
+import { prepareReadonlySessionEvidence } from "./readonly-session-evidence.ts";
+import { toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
+
+// Private runtime authority for host continuation planning; injected factories have none.
+const readonlyModels = new WeakMap<ChildSession, { current: ModelInfo; resolve(reference: string): ModelInfo | undefined; requestBytes: number }>();
+export function getReadonlyChildModels(child: ChildSession) {
+	return readonlyModels.get(child);
+}
 
 export interface ChildSessionEvent {
 	type: string;
@@ -185,6 +193,7 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 	};
 	return {
 		async create(launch) {
+			const observeReadonly = prepareReadonlySessionEvidence(launch);
 			const pi = await loadPiCodingAgent();
 			const modelRuntime = await sharedRuntime(pi);
 			const agentDir = getAgentDir();
@@ -208,8 +217,11 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 			const open = async () => {
 				applyProcessEnv(launch.processEnv);
 				if (!resetExtensionCacheOnReload(loader) && (launch.ambientExtensions || launch.extensionPaths.length)) launch.onExtensionError?.({ extensionPath: "<loader>", event: "load", error: new Error("pi's extension cache reset is unavailable; extensions loaded into this child share module state with other sessions in this process.") });
-				await loader.reload();
+				observeReadonly?.loadingHooks(true);
+				try { await loader.reload(); } finally { observeReadonly?.loadingHooks(false); }
 				await flushQueuedProviderRegistrations(loader, modelRuntime, launch.onExtensionError);
+				// No await between receipt validation and the SDK's permissive file open.
+				observeReadonly?.beforeOpen();
 				const sessionManager = launch.storage.kind === "file"
 					? pi.SessionManager.open(launch.storage.sessionFile, undefined, launch.cwd)
 					: launch.storage.kind === "dir"
@@ -217,6 +229,7 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 						: launch.storage.kind === "memory"
 							? pi.SessionManager.inMemory(launch.cwd)
 							: pi.SessionManager.create(launch.cwd);
+				observeReadonly?.opened(sessionManager);
 				const resolvedModel = launch.model
 					? pi.resolveCliModel({ cliModel: launch.model, modelRuntime })
 					: undefined;
@@ -248,6 +261,9 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 			const opened = loading.catch(() => {}).then(open);
 			loading = opened;
 			const session = await opened;
+			let evidence: ReturnType<NonNullable<typeof observeReadonly>["observe"]>;
+			try { evidence = observeReadonly?.observe(pi, modelRuntime, session); }
+			catch (error) { session.dispose(); throw error; }
 			let pending: Promise<void> | undefined;
 			// pi's own hosts emit `session_shutdown` before disposing a session so the
 			// extensions loaded into it (ambient extensions included) release their
@@ -255,19 +271,29 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 			const shutdown = async (): Promise<void> => {
 				try {
 					const runner = session.extensionRunner;
-					if (runner.hasHandlers("session_shutdown")) await Promise.race([runner.emit({ type: "session_shutdown", reason: "quit" }), new Promise((resolve) => setTimeout(resolve, shutdownTimeoutMs).unref?.())]);
+					if (runner.hasHandlers("session_shutdown")) {
+						evidence?.beforeShutdown();
+						const settled = await Promise.race([runner.emit({ type: "session_shutdown", reason: "quit" }).then(() => true), new Promise<false>((resolve) => setTimeout(() => resolve(false), shutdownTimeoutMs).unref?.())]);
+						if (!settled) evidence?.invalidate();
+					}
 				} catch (error) {
+					evidence?.invalidate();
 					launch.onExtensionError?.({ extensionPath: "<session>", event: "session_shutdown", error });
 				} finally {
 					session.dispose();
+					evidence?.finish(child);
 				}
 			};
 			const child: ChildSession = {
 				subscribe: (listener) => session.subscribe((event) => listener(event as unknown as ChildSessionEvent)),
-				prompt: (text) => session.prompt(text),
-				steer: (text) => session.steer(text),
-				followUp: (text) => session.followUp(text),
-				abort: () => session.abort(),
+				prompt: (text) => {
+					if (!evidence) return session.prompt(text);
+					try { evidence.start(); } catch (error) { return Promise.reject(error); }
+					return session.prompt(text).then(() => evidence?.settled(), (error) => { evidence?.invalidate(); throw error; });
+				},
+				steer: (text) => { evidence?.invalidate(); return session.steer(text); },
+				followUp: (text) => { evidence?.invalidate(); return session.followUp(text); },
+				abort: () => { evidence?.invalidate(); return session.abort(); },
 				dispose: () => {
 					if (!pending) {
 						live.delete(child);
@@ -283,6 +309,16 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 				get sessionId() { return session.sessionId; },
 				get modelId() { return session.model ? `${session.model.provider}/${session.model.id}` : undefined; },
 			};
+			if (evidence && session.model) readonlyModels.set(child, {
+				current: toModelInfo(session.model),
+				requestBytes: Buffer.byteLength(session.systemPrompt) + Buffer.byteLength(JSON.stringify(session.agent.state.tools)),
+				resolve(reference) {
+					try {
+						const resolved = pi.resolveCliModel({ cliModel: reference, modelRuntime });
+						return !resolved.error && resolved.model ? toModelInfo(resolved.model) : undefined;
+					} catch { return undefined; }
+				},
+			});
 			live.add(child);
 			return child;
 		},

package/src/runs/shared/child-tool-plan.ts

@@ -16,7 +16,7 @@ import {
 import {
 	TEMP_ROOT_DIR,
 	type JsonSchemaObject,
-	type LaunchResolvedChildExtensionsV1,
+	type LaunchResolvedChildExtensions,
 } from "../../shared/types.ts";
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
 import { getAgentDir } from "../../shared/utils.ts";
@@ -214,7 +214,7 @@ export function projectLaunchResolvedChildExtensions(
 		| "extensionArgs"
 		| "disableAmbientExtensions"
 	>,
-): LaunchResolvedChildExtensionsV1 {
+): LaunchResolvedChildExtensions {
 	const runtime = boundedExtensionIdentifiers(toolPlan.runtimeExtensions);
 	const configured = boundedExtensionIdentifiers(toolPlan.configuredExtensions);
 	const effective = boundedExtensionIdentifiers(toolPlan.extensionArgs);

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

@@ -26,7 +26,7 @@ export function planCompletionEvidence(input: {
 	mutationAttemptObserved: boolean;
 	mutationEvidence?: TrackedMutationEvidence;
 	arbiterRescued?: boolean;
-	agentContractV1: boolean;
+	agentContractEnabled: boolean;
 }): CompletionEvidencePlan {
 	const guardBlocked = input.guard?.blocked === true;
 	const guardTriggered = input.guardTriggered
@@ -59,7 +59,7 @@ export function planCompletionEvidence(input: {
 		mutationExpected,
 		mutationAttempted,
 		fileMutation,
-		legacyFailureError: guardTriggered && !input.agentContractV1
+		legacyFailureError: guardTriggered && !input.agentContractEnabled
 			? MISSING_IMPLEMENTATION_MUTATION_ERROR
 			: undefined,
 	};

package/src/runs/shared/completion-guard.ts

@@ -13,6 +13,7 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 	"web_search",
 	"fetch_content",
 	"get_search_content",
+	"source_check",
 	"intercom",
 	"contact_supervisor",
 	"structured_output",

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

@@ -1,6 +1,6 @@
 import type {
 	AsyncStatus,
-	HostStepNodeV1,
+	HostStepNode,
 	HostStepState,
 	HostStepVerdict,
 	WorkflowGraphNode,
@@ -57,7 +57,7 @@ function assertTimestamp(value: unknown, field: string, source: string, required
 	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`Invalid host step '${source}': ${field} must be a non-negative safe integer.`);
 }
 
-function assertFreshness(value: unknown, source: string): asserts value is HostStepNodeV1["freshness"] {
+function assertFreshness(value: unknown, source: string): asserts value is HostStepNode["freshness"] {
 	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': freshness must be an object.`);
 	const unknownFields = Object.keys(value).filter((field) => !FRESHNESS_FIELDS.has(field));
 	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': freshness has unsupported fields: ${unknownFields.join(", ")}.`);
@@ -70,7 +70,7 @@ function assertFreshness(value: unknown, source: string): asserts value is HostS
  * Validate the persisted host-step contract. This deliberately rejects unknown
  * fields and unbounded values so status and receipt loaders fail closed.
  */
-export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNodeV1 {
+export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNode {
 	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': expected an object.`);
 	const unknownFields = Object.keys(value).filter((field) => !HOST_STEP_FIELDS.has(field));
 	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': unsupported fields: ${unknownFields.join(", ")}.`);
@@ -105,7 +105,7 @@ export function assertHostStepNode(value: unknown, source = "status"): asserts v
 	assertTimestamp(value.deadlineAt, "deadlineAt", source);
 }
 
-export function parseHostStepNode(value: unknown, source = "status"): HostStepNodeV1 {
+export function parseHostStepNode(value: unknown, source = "status"): HostStepNode {
 	assertHostStepNode(value, source);
 	return {
 		...value,
@@ -113,7 +113,7 @@ export function parseHostStepNode(value: unknown, source = "status"): HostStepNo
 	};
 }
 
-export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], source = "status"): void {
+export function assertUniqueHostStepIds(hostSteps: readonly HostStepNode[], source = "status"): void {
 	const ids = new Set<string>();
 	for (const hostStep of hostSteps) {
 		if (ids.has(hostStep.id)) throw new Error(`Invalid host step '${source}': duplicate host step id '${hostStep.id}'.`);
@@ -122,11 +122,11 @@ export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], so
 }
 
 /** Return only valid host nodes so an untrusted in-memory projection fails closed. */
-export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNodeV1[] {
+export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNode[] {
 	const nodes = graph?.nodes ?? [];
 	const nodeIdCounts = new Map<string, number>();
 	for (const node of nodes) nodeIdCounts.set(node.id, (nodeIdCounts.get(node.id) ?? 0) + 1);
-	const hostSteps: HostStepNodeV1[] = [];
+	const hostSteps: HostStepNode[] = [];
 	for (const [index, node] of nodes.entries()) {
 		if (node.kind !== "host-step") continue;
 		try {
@@ -147,7 +147,7 @@ export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | unde
 	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[] = [];
+	const hostSteps: HostStepNode[] = [];
 	for (const [index, node] of graph.nodes.entries()) {
 		if (node.kind !== "host-step") continue;
 		const hostStep = parseHostStepNode(node.hostStep, `${source}.workflowGraph.nodes[${index}].hostStep`);
@@ -161,7 +161,7 @@ export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | unde
 	}
 }
 
-export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNode {
+export function hostStepWorkflowNode(hostStep: HostStepNode): WorkflowGraphNode {
 	assertHostStepNode(hostStep, hostStep.id);
 	return {
 		id: hostStep.id,
@@ -172,7 +172,7 @@ export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNod
 	};
 }
 
-function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
+function workflowNodeStatus(hostStep: HostStepNode): WorkflowNodeStatus {
 	if (hostStep.state === "pending") return "pending";
 	if (hostStep.state === "running") return "running";
 	if (hostStep.state === "cancelled") return "stopped";
@@ -187,7 +187,7 @@ function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
  */
 export function upsertHostStep(input: {
 	status: AsyncStatus;
-	hostStep: HostStepNodeV1;
+	hostStep: HostStepNode;
 	persist: (status: AsyncStatus) => void;
 }): AsyncStatus {
 	const hostStep = parseHostStepNode(input.hostStep, input.hostStep.id);

package/src/runs/shared/llm-intent-arbiter.ts

@@ -76,9 +76,10 @@ export interface TaskMutationArbiterOptions {
 const DEFAULT_ARBITER_TIMEOUT_MS = 10_000;
 
 type RegistryModel = ReturnType<NonNullable<ExtensionContext["modelRegistry"]["find"]>>;
+type ArbiterModelContext = Pick<ExtensionContext, "model" | "modelRegistry">;
 
 function resolveArbiterModel(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): NonNullable<RegistryModel> | null {
 	const registry = ctx.modelRegistry as {
@@ -98,7 +99,7 @@ function resolveArbiterModel(
 }
 
 function resolveArbiterRuntime(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): ArbiterRuntime | null {
 	const model = resolveArbiterModel(ctx, options);
@@ -117,9 +118,9 @@ function resolveArbiterRuntime(
 }
 
 async function resolveArbiterAuth(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	model: RegistryModel,
-): Promise<ArbiterAuth> {
+): Promise<ArbiterAuth | undefined> {
 	const registry = ctx.modelRegistry as {
 		getApiKeyAndHeaders?: (m: RegistryModel) => Promise<{
 			ok: boolean;
@@ -135,14 +136,14 @@ async function resolveArbiterAuth(
 	if (!registry.getApiKeyAndHeaders) return {};
 	try {
 		const auth = await registry.getApiKeyAndHeaders(model);
-		if (auth.ok === false) return {};
+		if (auth.ok === false) return undefined;
 		return {
 			...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
 			...(auth.headers ? { headers: auth.headers } : {}),
 			...(auth.env ? { env: auth.env } : {}),
 		};
 	} catch {
-		return {};
+		return undefined;
 	}
 }
 
@@ -230,9 +231,9 @@ async function runArbitration(
 	}
 }
 
-/** Create a memoized arbiter bound to the parent session's model, or undefined when disabled/unavailable. */
+/** Create a memoized arbiter bound to the supplied model services, or undefined when disabled/unavailable. */
 export function createTaskMutationArbiter(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): TaskMutationArbiter | undefined {
 	if (process.env.PI_SUBAGENTS_LLM_INTENT_ARBITER === "0") return undefined;
@@ -244,7 +245,7 @@ export function createTaskMutationArbiter(
 		const cached = cache.get(key);
 		if (cached) return cached;
 		const auth = await resolveArbiterAuth(ctx, runtime.model);
-		const verdict = await runArbitration(runtime, auth, task);
+		const verdict = auth ? await runArbitration(runtime, auth, task) : "unavailable";
 		if (cache.size > 200) cache.clear();
 		cache.set(key, verdict);
 		return verdict;

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

@@ -1,4 +1,4 @@
-import { splitKnownThinkingSuffix, type ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
+import { splitKnownThinkingSuffix as splitThinkingSuffix, type ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
 import type { Usage } from "../../shared/types.ts";
 import { filterFallbackCandidates, findModelExclusion, parseModelKey, recordModelFailure } from "./model-exclusions.ts";
 import { checkModelScope, type ModelScopeCheckRule, type ModelScopeViolation, type ModelSource } from "./model-scope.ts";
@@ -14,9 +14,7 @@ interface ModelAttemptSummary {
 	usage?: Usage;
 }
 
-export function splitThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
-	return splitKnownThinkingSuffix(model);
-}
+export { splitThinkingSuffix };
 
 /** Aliases apply only to the resolved launch candidate (without its thinking suffix) and the exact raw response ID. */
 export function formatSubagentModelVerificationError(
@@ -38,7 +36,7 @@ export function formatSubagentModelVerificationError(
 		const expectedFullIdLeaf = expectedEntry.fullId.slice(expectedEntry.fullId.lastIndexOf("/") + 1);
 		if (expectedIdLeaf === observedBase || expectedFullIdLeaf === observedBase) return undefined;
 	}
-	return `model_verification_failed: child reported a different model than the launch candidate. Expected '${expectedModel}' but observed '${observedModel}'.`;
+	return `model_verification_failed: native Pi child reported a different model than the launch candidate. Expected '${expectedModel}' but observed '${observedModel}'. If you have independently verified this response ID identifies the requested model, declare the exact mapping in modelResponseAliases in ~/.pi/agent/extensions/subagent/config.json (see docs/configuration.md#modelresponsealiases). Use the resolved provider/model ID without its thinking suffix as the key. This leaves the outgoing request unchanged. Configuration changes affect new independent native runs; resumed native runs retain their launch-time declaration. External CLI adapters do not use this setting.`;
 }
 
 /** Sentinel model value requesting that a subagent inherit the parent session's model. */
@@ -537,6 +535,7 @@ export function buildModelCandidates(
 }
 
 const RETRYABLE_MODEL_FAILURE_PATTERNS = [
+	/^REQUEST_LIMIT_EXCEEDED$/,
 	/rate\s*limit/i,
 	/usage\s*limit/i,
 	/too many requests/i,
@@ -608,8 +607,13 @@ export function isRetryableModelFailureAttempt(input: { error: string | undefine
 	return Boolean(error && input.messages?.some((message) => messageError(message)?.trim() === error));
 }
 
+// Request-shape failures can match broad fallback signals such as "upstream",
+// but do not establish that the model is unhealthy for subsequent requests.
+const REQUEST_SHAPE_FAILURE_PATTERN = /\b(?:bad[ _]request|invalid[ _]argument|invalid_request_error)\b/i;
+
 export function recordRetryableModelFailure(model: string | undefined, error: string | undefined): void {
-	if (!model || !isRetryableModelFailure(error)) return;
+	if (!model || !error || !isRetryableModelFailure(error) || isContextOverflow(error)) return;
+	if (REQUEST_SHAPE_FAILURE_PATTERN.test(error)) return;
 	const { provider, modelId } = parseModelKey(model);
 	recordModelFailure({ modelId, reason: error, ...(provider ? { provider } : {}) });
 }

package/src/runs/shared/nested-events.ts

@@ -6,8 +6,8 @@ import {
 	TEMP_ROOT_DIR,
 	type AsyncJobState,
 	type AsyncStatus,
-	type LaunchResolvedChildExtensionsV1,
-	type RuntimeAcknowledgedChildExtensionsV1,
+	type LaunchResolvedChildExtensions,
+	type RuntimeAcknowledgedChildExtensions,
 	type NestedRouteInfo,
 	type TurnBudgetState,
 	type NestedRunSummary,
@@ -217,7 +217,7 @@ function sanitizeCost(value: unknown): NestedRunSummary["totalCost"] | undefined
 		: undefined;
 }
 
-function sanitizeLaunchResolvedExtensions(value: unknown): LaunchResolvedChildExtensionsV1 | undefined {
+function sanitizeLaunchResolvedExtensions(value: unknown): LaunchResolvedChildExtensions | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const raw = value as Record<string, unknown>;
 	if (raw.version !== 1 || raw.source !== "launch-resolved" || typeof raw.disableAmbientExtensions !== "boolean") return undefined;
@@ -241,7 +241,7 @@ function sanitizeLaunchResolvedExtensions(value: unknown): LaunchResolvedChildEx
 	};
 }
 
-function sanitizeRuntimeAcknowledgedExtensions(value: unknown): RuntimeAcknowledgedChildExtensionsV1 | undefined {
+function sanitizeRuntimeAcknowledgedExtensions(value: unknown): RuntimeAcknowledgedChildExtensions | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const raw = value as Record<string, unknown>;
 	if (raw.version !== 1 || raw.source !== "child-runtime" || !Array.isArray(raw.ids)) return undefined;
@@ -261,7 +261,7 @@ function sanitizeRuntimeAcknowledgedExtensions(value: unknown): RuntimeAcknowled
 	};
 }
 
-function runtimeAcknowledgedEntry(value: unknown): { runtimeAcknowledgedExtensions: RuntimeAcknowledgedChildExtensionsV1 } | Record<string, never> {
+function runtimeAcknowledgedEntry(value: unknown): { runtimeAcknowledgedExtensions: RuntimeAcknowledgedChildExtensions } | Record<string, never> {
 	const sanitized = sanitizeRuntimeAcknowledgedExtensions(value);
 	return sanitized ? { runtimeAcknowledgedExtensions: sanitized } : {};
 }

package/src/runs/shared/orca-progress-tabs.ts

@@ -53,6 +53,8 @@ const ORCA_CLEANUP_WATCHDOG_SCRIPT = [
 ].join("");
 
 export interface OrcaProgressTab {
+	/** Resolves when the terminal-create watchdog closes, after its final manifest/queue writes (success or failure). Not viewer completion. */
+	readonly creationSettled: Promise<void>;
 	append(text: string): void;
 	section(input: { agent: string; index: number; count: number }): void;
 	event(event: { type?: string; message?: Message; toolName?: string; args?: unknown }): void;
@@ -402,6 +404,8 @@ export function createOrcaProgressTab(input: {
 		}
 	};
 	let createSettled = false;
+	let resolveCreationSettled!: () => void;
+	const creationSettled = new Promise<void>((resolve) => { resolveCreationSettled = resolve; });
 	let cleanupPaths: string[] | undefined;
 	const scheduleDeferredCleanup = () => {
 		if (!createSettled || cleanupPaths === undefined) return;
@@ -434,6 +438,7 @@ export function createOrcaProgressTab(input: {
 			createSettled = true;
 			if (code !== 0) failObserver();
 			scheduleDeferredCleanup();
+			resolveCreationSettled();
 		});
 		watchdog.once("error", () => {
 			markCreateReady();
@@ -450,6 +455,7 @@ export function createOrcaProgressTab(input: {
 
 	let finished = false;
 	return {
+		creationSettled,
 		append(text) {
 			if (finished) return;
 			writeProgress(text);

package/src/runs/shared/parallel-handoff.ts

@@ -17,6 +17,7 @@ import type {
 	WorktreeCleanupReport,
 	WorktreeDiff,
 	WorktreeSetup,
+	WorktreeSetupProgress,
 	WorktreeCleanupIntent,
 } from "./worktree.ts";
 import { cleanupWorktrees } from "./worktree.ts";
@@ -614,18 +615,62 @@ export function parallelHandoffPath(baseDir: string, runId?: string): string {
 	return runId ? path.join(baseDir, "handoffs", `${runId}.json`) : path.join(baseDir, "handoff.json");
 }
 
-export function writePendingParallelHandoff(input: {
-	manifestPath: string;
-	runId: string;
-	mode: "single" | "parallel" | "chain";
-	source: "foreground" | "async";
-	cwd: string;
-	stepIndex: number;
-	flatStartIndex: number;
-	setup: WorktreeSetup;
-	laneBindings?: ParallelHandoffLaneBinding[];
-}): ParallelHandoffReference {
-	return writeParallelHandoffGroup({ ...input, diffs: [], results: [] });
+/** Synchronous onProgress projection shared by setup owners; snapshots are cumulative. */
+export function writeWorktreeSetupHandoff(input: Omit<Parameters<typeof writeParallelHandoffGroup>[0], "setup" | "diffs" | "results" | "cleanup" | "now"> & {
+	progress: WorktreeSetupProgress;
+}): ParallelHandoffReference | undefined {
+	const { progress, ...handoff } = input;
+	const { setup, attempts, cleanup } = progress;
+	// Preflight has no allocation identity yet. Its original error belongs to the caller.
+	if (attempts.length === 0 && setup.worktrees.length === 0) return undefined;
+	if (!setup.cwd || !setup.baseCommit) throw new Error("Cannot publish worktree allocation evidence without repository and base commit.");
+	const diagnostic = (text: string): string => text.slice(0, 512);
+	// Never copy argv, environment, Error objects or captured stdout/stderr into artifacts.
+	const commandEvidence = (command: WorktreeSetupProgress["command"]) => command && ({
+		pid: command.pid,
+		processGroupId: command.processGroupId,
+		...(command.result ? {
+			status: command.result.status,
+			signal: command.result.signal,
+			failed: Boolean(command.result.error),
+			outputIncomplete: command.result.outputIncomplete,
+			processTree: command.result.processTree?.state,
+		} : {}),
+	});
+	const errors = [
+		`Worktree setup ${JSON.stringify({ runId: input.runId, stepIndex: input.stepIndex, phase: progress.phase,
+			unknown: Boolean(progress.unknown), command: commandEvidence(progress.command) })}`,
+		...attempts.map((attempt) => {
+			const task = cleanup?.tasks.find((candidate) => candidate.index === attempt.index);
+			return `Allocation attempt ${JSON.stringify({ index: attempt.index, branch: attempt.branch,
+				path: attempt.path ?? null, validated: attempt.validated,
+				command: commandEvidence(attempt.command), hookCommand: commandEvidence(attempt.hookCommand),
+				...(task ? { worktreeRemoved: task.worktreeRemoved, branchRemoved: task.branchRemoved,
+					preserved: task.preserved, reason: task.reason && diagnostic(task.reason), errors: task.errors?.map(diagnostic) } : {}),
+			})}`;
+		}),
+		...(cleanup?.errors?.map(diagnostic) ?? []),
+		...(progress.unknown ? ["Setup settlement unknown; manual reconciliation required."] : []),
+	];
+	return writeParallelHandoffGroup({
+		...handoff, setup, diffs: [], results: [],
+		laneBindings: input.laneBindings?.filter((binding) => setup.worktrees.some((worktree) => worktree.index === binding.taskIndex)),
+		cleanup: {
+			state: cleanup?.state ?? "partial",
+			pruned: cleanup?.pruned ?? false,
+			errors,
+			// An attempted native path is not a validated recovery task, even during rollback.
+			tasks: setup.worktrees.map((worktree) => {
+				const task = cleanup?.tasks.find((candidate) => candidate.index === worktree.index);
+				return task ? { ...task, reason: task.reason && diagnostic(task.reason), errors: task.errors?.map(diagnostic) } : {
+					index: worktree.index, path: worktree.path, branch: worktree.branch,
+					provider: worktree.provider, naming: worktree.naming,
+					worktreeRemoved: false, branchRemoved: false, preserved: true,
+					reason: "setup pending durable handoff capture",
+				};
+			}),
+		},
+	});
 }
 
 export function formatParallelHandoffReference(reference: ParallelHandoffReference): string {

package/src/runs/shared/parallel-utils.ts

@@ -75,8 +75,8 @@ export interface RunnerSubagentStep {
 	launchBindingTask?: string;
 	launchContractDigest?: string;
 	extensionBindings?: import("./extension-bindings.ts").ExtensionBindings;
-	launchResolvedExtensions?: import("../../shared/types.ts").LaunchResolvedChildExtensionsV1;
-	runtimeAcknowledgedExtensions?: import("../../shared/types.ts").RuntimeAcknowledgedChildExtensionsV1;
+	launchResolvedExtensions?: import("../../shared/types.ts").LaunchResolvedChildExtensions;
+	runtimeAcknowledgedExtensions?: import("../../shared/types.ts").RuntimeAcknowledgedChildExtensions;
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
 	acceptanceInput?: import("../../shared/types.ts").AcceptanceInput;
 	acceptanceRole?: import("../../shared/types.ts").AcceptanceRole;