pi-subagents 0.63.0 → 0.65.0

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

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
 import { TEMP_ROOT_DIR } from "../../shared/types.ts";
+import { getAgentDir } from "../../shared/utils.ts";
 
 export const EXCLUSIONS_PATH_ENV = "PI_MODEL_EXCLUSIONS_PATH";
 
@@ -30,6 +31,43 @@ let loadedTTLCeilingMs: number | undefined;
 let persistTimer: ReturnType<typeof setTimeout> | null = null;
 let persistSeq = 0;
 
+const AUTH_FAILURE_PATTERNS = [
+	/auth(?:entication)?/i,
+	/unauthori[sz]ed/i,
+	/forbidden/i,
+	/api key/i,
+	/token expired/i,
+	/invalid key/i,
+];
+
+function isAuthModelExclusion(entry: ModelExclusion): boolean {
+	const reason = entry.reason;
+	return typeof reason === "string" && AUTH_FAILURE_PATTERNS.some((pattern) => pattern.test(reason));
+}
+
+function getAuthStoreMtimeMs(): number | undefined {
+	const authStorePath = path.join(getAgentDir(), "auth.json");
+	try {
+		const stats = fs.statSync(authStorePath);
+		return stats.isFile() && Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : undefined;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			console.error(`[model-exclusions] Failed to stat Pi auth store at ${authStorePath}; preserving auth-related exclusions:`, error);
+		}
+		return undefined;
+	}
+}
+
+function invalidateAuthExclusions(): void {
+	if (!exclusions.some(isAuthModelExclusion)) return;
+	const authStoreMtimeMs = getAuthStoreMtimeMs();
+	if (authStoreMtimeMs === undefined) return;
+	const retained = exclusions.filter((entry) => !isAuthModelExclusion(entry) || authStoreMtimeMs <= entry.recordedAt);
+	if (retained.length === exclusions.length) return;
+	exclusions = retained;
+	schedulePersist();
+}
+
 /**
  * Override the default TTL applied to newly recorded model exclusions.
  *
@@ -95,23 +133,23 @@ function ensureLoaded(): void {
 		const data = JSON.parse(raw);
 		if (data.version === 1) {
 			if (!Array.isArray(data.exclusions)) throw new Error("Model exclusion store version 1 must contain an exclusions array.");
-			for (let index = 0; index < data.exclusions.length; index++) {
-				const entry = data.exclusions[index];
-				if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`Model exclusion store entry ${index} must be an object.`);
-				if (entry.reason !== undefined && typeof entry.reason !== "string") throw new Error(`Model exclusion store entry ${index} has an invalid reason.`);
-				for (const field of ["recordedAt", "expiresAt"] as const) {
-					const timestamp = entry[field];
-					if (typeof timestamp !== "number" || !Number.isFinite(timestamp) || timestamp <= 0 || timestamp > MAX_DATE_TIMESTAMP_MS) {
-						throw new Error(`Model exclusion store entry ${index} has an invalid ${field}.`);
-					}
-				}
-			}
 			const now = Date.now();
-			exclusions = (data.exclusions ?? []).filter((e: ModelExclusion) => e.expiresAt > now);
+			let droppedInvalid = false;
+			exclusions = data.exclusions.flatMap((entry: unknown, index: number) => {
+				const result = readPersistedExclusion(entry, index);
+				if (!result.ok) {
+					droppedInvalid = true;
+					console.warn(`[model-exclusions] Ignoring invalid exclusion: ${result.message}`);
+					return [];
+				}
+				return [result.exclusion];
+			}).filter((e: ModelExclusion) => e.expiresAt > now);
 			const shortened = loadedTTLCeilingMs !== undefined && shortenExclusionsToTTL(exclusions, loadedTTLCeilingMs, now);
 			exclusions = deduplicate(exclusions);
-			if (shortened) schedulePersist();
+			if (droppedInvalid) flushPersist();
+			else if (shortened) schedulePersist();
 		}
+		invalidateAuthExclusions();
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
 			console.error(`[model-exclusions] Failed to load exclusions from ${getExclusionsFilePath()}:`, error);
@@ -119,6 +157,32 @@ function ensureLoaded(): void {
 	}
 }
 
+type PersistedExclusionRead =
+	| { ok: true; exclusion: ModelExclusion }
+	| { ok: false; message: string };
+
+function invalidPersistedExclusion(index: number, message: string): PersistedExclusionRead {
+	return { ok: false, message: `Model exclusion store entry ${index} ${message}.` };
+}
+
+function readPersistedExclusion(entry: unknown, index: number): PersistedExclusionRead {
+	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return invalidPersistedExclusion(index, "must be an object");
+	const candidate = entry as { modelId?: unknown; provider?: unknown; reason?: unknown; recordedAt?: unknown; expiresAt?: unknown };
+	const { modelId, provider, reason } = candidate;
+	if (modelId !== undefined && (typeof modelId !== "string" || modelId.length === 0)) return invalidPersistedExclusion(index, "has an invalid modelId");
+	if (provider !== undefined && (typeof provider !== "string" || provider.length === 0)) return invalidPersistedExclusion(index, "has an invalid provider");
+	if (reason !== undefined && typeof reason !== "string") return invalidPersistedExclusion(index, "has an invalid reason");
+	const { recordedAt, expiresAt } = candidate;
+	if (typeof recordedAt !== "number" || !Number.isFinite(recordedAt) || recordedAt <= 0 || recordedAt > MAX_DATE_TIMESTAMP_MS) return invalidPersistedExclusion(index, "has an invalid recordedAt");
+	if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= 0 || expiresAt > MAX_DATE_TIMESTAMP_MS) return invalidPersistedExclusion(index, "has an invalid expiresAt");
+	const metadata = { ...(reason === undefined ? {} : { reason }), recordedAt, expiresAt };
+	if (modelId === undefined) {
+		if (provider === undefined) return invalidPersistedExclusion(index, "must include modelId or provider");
+		return { ok: true, exclusion: { provider, ...metadata } };
+	}
+	return { ok: true, exclusion: { modelId, ...(provider === undefined ? {} : { provider }), ...metadata } };
+}
+
 function dedupKey(entry: ModelExclusion): string {
 	return `${entry.provider ?? ""}|${entry.modelId ?? ""}`;
 }
@@ -165,6 +229,7 @@ export function recordModelFailure(options: RecordModelFailureOptions): void {
  */
 export function clearExpiredExclusions(): void {
 	ensureLoaded();
+	invalidateAuthExclusions();
 	prune(exclusions, Date.now());
 	schedulePersist();
 }
@@ -190,7 +255,7 @@ export function clearExclusions(): void {
  */
 function entryMatches(entry: ModelExclusion, candidateModelId: string, candidateProvider: string | undefined, now: number): boolean {
 	if (entry.expiresAt <= now) return false;
-	if (entry.modelId) {
+	if (entry.modelId !== undefined) {
 		if (entry.modelId !== candidateModelId) return false;
 		return !entry.provider || !candidateProvider || entry.provider === candidateProvider;
 	}
@@ -202,6 +267,7 @@ function entryMatches(entry: ModelExclusion, candidateModelId: string, candidate
  */
 export function isExcluded(modelId: string, provider: string): boolean {
 	ensureLoaded();
+	invalidateAuthExclusions();
 	return exclusions.some((entry) => entryMatches(entry, modelId, provider, Date.now()));
 }
 
@@ -213,6 +279,7 @@ export function isExcluded(modelId: string, provider: string): boolean {
  */
 export function findModelExclusion(fullId: string, now = Date.now()): Readonly<ModelExclusion> | undefined {
 	ensureLoaded();
+	invalidateAuthExclusions();
 	const { provider, modelId } = parseModelKey(fullId);
 	return exclusions.find((entry) => entryMatches(entry, modelId, provider, now));
 }
@@ -252,6 +319,7 @@ export function filterFallbackCandidates(candidates: string[], opts?: {
 	onExcluded?: (candidate: string, exclusion: Readonly<ModelExclusion>) => void;
 }): string[] {
 	ensureLoaded();
+	invalidateAuthExclusions();
 	const timestamp = opts?.now ?? Date.now();
 	const seen = new Set<string>();
 	const filtered: string[] = [];

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

@@ -284,6 +284,31 @@ function enforceModelScopes(
 	for (const violation of violations) (onWarn ?? defaultScopeWarn)(violation);
 }
 
+const MODEL_EXCLUSION_DIAGNOSTIC_MAX_LENGTH = 240;
+const MODEL_EXCLUSION_DIAGNOSTIC_MAX_ENTRIES = 20;
+
+function sanitizeModelExclusionDiagnostic(value: string | undefined, fallback: string): string {
+	const normalized = typeof value === "string"
+		? value.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, " ").trim()
+		: "";
+	return redactSecretValues(normalized || fallback).slice(0, MODEL_EXCLUSION_DIAGNOSTIC_MAX_LENGTH);
+}
+
+function formatModelExclusionExpiry(expiresAt: number): string {
+	if (!Number.isFinite(expiresAt)) return "unknown";
+	const date = new Date(expiresAt);
+	return Number.isNaN(date.getTime()) ? "unknown" : date.toISOString();
+}
+
+function formatExcludedCandidateEvidence(candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>): string {
+	const { provider, modelId } = parseModelKey(candidate);
+	const displayCandidate = sanitizeModelExclusionDiagnostic(candidate, "unknown");
+	const displayModel = sanitizeModelExclusionDiagnostic(modelId, "unknown");
+	const displayProvider = sanitizeModelExclusionDiagnostic(provider ?? exclusion.provider, "unspecified");
+	const reason = sanitizeModelExclusionDiagnostic(exclusion.reason, "runtime-failure");
+	return `${displayCandidate} — model: ${displayModel}; provider: ${displayProvider}; reason: ${reason}; expires: ${formatModelExclusionExpiry(exclusion.expiresAt)}`;
+}
+
 function throwForExplicitModelExclusion(model: string): void {
 	const exclusion = findModelExclusion(model);
 	if (!exclusion) return;
@@ -419,9 +444,15 @@ export function buildModelCandidates(
 	if (!primaryModel) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
 	const origin = options?.origin ?? (options?.primaryModelFromParent ? "inherited" : "configured");
 	const scopes = configuredScopes(options?.scope);
+	type ExcludedCandidate = { candidate: string; exclusion: NonNullable<ReturnType<typeof findModelExclusion>> };
+	const excludedCandidates: ExcludedCandidate[] = [];
+	let excludedCandidateCount = 0;
 	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()}).`);
+		excludedCandidateCount++;
+		if (excludedCandidates.length < MODEL_EXCLUSION_DIAGNOSTIC_MAX_ENTRIES) excludedCandidates.push({ candidate, exclusion });
+		const displayCandidate = sanitizeModelExclusionDiagnostic(candidate, "unknown");
+		const reason = sanitizeModelExclusionDiagnostic(exclusion.reason, "runtime-failure");
+		console.warn(`[pi-subagents] Skipping model '${displayCandidate}' due to a cached exclusion (reason: ${reason}; expires: ${formatModelExclusionExpiry(exclusion.expiresAt)}).`);
 	};
 	if (origin === "explicit" && primaryModel) {
 		const normalized = resolveRequiredSubagentModelCandidate(primaryModel.trim(), availableModels, preferredProvider);
@@ -433,6 +464,7 @@ export function buildModelCandidates(
 	const candidates: string[] = [];
 	const rawCandidates = [primaryModel, ...(fallbackModels ?? [])];
 	let skippedPrimary: string | undefined;
+	let skippedFallback: string | undefined;
 	for (let index = 0; index < rawCandidates.length; index++) {
 		const raw = rawCandidates[index];
 		if (!raw) continue;
@@ -442,7 +474,10 @@ export function buildModelCandidates(
 			: resolveSubagentModelCandidate(model, availableModels, preferredProvider);
 		if (!normalized) {
 			if (index === 0) skippedPrimary = model;
-			else console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
+			else {
+				skippedFallback ??= model;
+				console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
+			}
 			continue;
 		}
 		if (seen.has(normalized)) continue;
@@ -455,7 +490,15 @@ export function buildModelCandidates(
 	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);
+		if (candidates.length === 0 && skippedFallback) resolveRequiredSubagentModelCandidate(skippedFallback, availableModels, preferredProvider);
+		if (candidates.length > 0) {
+			const shownExclusions = excludedCandidates;
+			const omittedExclusions = excludedCandidateCount - shownExclusions.length;
+			const evidence = shownExclusions.length > 0
+				? ` (excluded: ${shownExclusions.map(({ candidate, exclusion }) => formatExcludedCandidateEvidence(candidate, exclusion)).join("; ")}${omittedExclusions > 0 ? `; ... and ${omittedExclusions} more` : ""})`
+				: "";
+			throw new Error(`${ZERO_USABLE_MODEL_CANDIDATES_ERROR}${evidence}`);
+		}
 		return resolved;
 	}
 	if (skippedPrimary) {

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

@@ -16,17 +16,7 @@ import {
 	type SubagentRunMode,
 	type SubagentState,
 } from "../../shared/types.ts";
-import { isSafeNestedPathId, parseNestedPathEnv, sanitizeNestedPath, type NestedPathEntry } from "./nested-path.ts";
-import {
-	SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV,
-	SUBAGENT_PARENT_CHILD_INDEX_ENV,
-	SUBAGENT_PARENT_CONTROL_INBOX_ENV,
-	SUBAGENT_PARENT_DEPTH_ENV,
-	SUBAGENT_PARENT_EVENT_SINK_ENV,
-	SUBAGENT_PARENT_PATH_ENV,
-	SUBAGENT_PARENT_ROOT_RUN_ID_ENV,
-	SUBAGENT_PARENT_RUN_ID_ENV,
-} from "./pi-args.ts";
+import { isSafeNestedPathId, sanitizeNestedPath, type NestedPathEntry } from "./nested-path.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { sanitizeProcessTerminal } from "../background/process-terminal.ts";
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
@@ -141,13 +131,9 @@ export function createNestedRoute(rootRunId: string): NestedRoute {
 	return { rootRunId, eventSink, controlInbox, capabilityToken };
 }
 
-export function resolveNestedRouteFromEnv(env: NodeJS.ProcessEnv = process.env): NestedRoute | undefined {
-	const rootRunId = env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV];
-	const eventSink = env[SUBAGENT_PARENT_EVENT_SINK_ENV];
-	const controlInbox = env[SUBAGENT_PARENT_CONTROL_INBOX_ENV];
-	const capabilityToken = env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV];
-	if (!rootRunId || !eventSink || !controlInbox || !capabilityToken) return undefined;
-	const route = { rootRunId, eventSink, controlInbox, capabilityToken };
+/** Validate a route handed to an in-process child against its on-disk metadata. */
+export function resolveNestedRoute(route: NestedRoute): NestedRoute {
+	const { rootRunId, capabilityToken } = route;
 	validateRouteShape(route);
 	const routeFile = path.join(commonRouteRoot(route), ROUTE_FILE);
 	const metadata = JSON.parse(fs.readFileSync(routeFile, "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
@@ -157,24 +143,38 @@ export function resolveNestedRouteFromEnv(env: NodeJS.ProcessEnv = process.env):
 	return route;
 }
 
-export function resolveInheritedNestedRouteFromEnv(env: NodeJS.ProcessEnv = process.env): NestedRoute | undefined {
+export function resolveInheritedNestedRoute(route: NestedRoute): NestedRoute | undefined {
 	try {
-		return resolveNestedRouteFromEnv(env);
+		return resolveNestedRoute(route);
 	} catch (error) {
 		console.error("Ignoring invalid nested subagent event route:", error);
 		return undefined;
 	}
 }
 
-export function resolveNestedParentAddressFromEnv(env: NodeJS.ProcessEnv = process.env): { parentRunId: string; parentStepIndex?: number; depth: number; path: NestedPathEntry[] } | undefined {
-	const parentRunId = env[SUBAGENT_PARENT_RUN_ID_ENV];
-	if (!isSafeNestedId(parentRunId)) return undefined;
-	const rawIndex = env[SUBAGENT_PARENT_CHILD_INDEX_ENV];
-	const parentStepIndex = rawIndex && /^\d+$/.test(rawIndex) ? Number(rawIndex) : undefined;
-	const depth = Math.min(Math.max(1, clampNumber(Number(env[SUBAGENT_PARENT_DEPTH_ENV])) ?? 1), MAX_DEPTH);
-	const parsedPath = parseNestedPathEnv(env[SUBAGENT_PARENT_PATH_ENV]);
-	const nestedPath = parsedPath.length ? parsedPath : [{ runId: parentRunId, ...(parentStepIndex !== undefined ? { stepIndex: parentStepIndex } : {}) }];
-	return { parentRunId, ...(parentStepIndex !== undefined ? { parentStepIndex } : {}), depth, path: nestedPath };
+export interface NestedParentAddress {
+	parentRunId: string;
+	parentStepIndex?: number;
+	depth: number;
+	path: NestedPathEntry[];
+}
+
+/** The nested route an executor inherited from its own child runtime, validated against disk. */
+export function inheritedNestedRouteOf(runtime: { nestedRoute?: NestedRoute } | undefined): NestedRoute | undefined {
+	return runtime?.nestedRoute ? resolveInheritedNestedRoute(runtime.nestedRoute) : undefined;
+}
+
+/** The executor's own position in the nested run tree, from its child runtime. */
+export function inheritedNestedParentAddressOf(runtime: { nestedParent?: { parentRunId: string; parentChildIndex?: number; depth: number; path: NestedPathEntry[] } } | undefined): NestedParentAddress | undefined {
+	const parent = runtime?.nestedParent;
+	if (!parent || !isSafeNestedId(parent.parentRunId)) return undefined;
+	const depth = Math.min(Math.max(1, clampNumber(parent.depth) ?? 1), MAX_DEPTH);
+	return {
+		parentRunId: parent.parentRunId,
+		...(parent.parentChildIndex !== undefined ? { parentStepIndex: parent.parentChildIndex } : {}),
+		depth,
+		path: parent.path.length ? parent.path : [{ runId: parent.parentRunId, ...(parent.parentChildIndex !== undefined ? { stepIndex: parent.parentChildIndex } : {}) }],
+	};
 }
 
 export function resolveNestedAsyncDir(rootRunId: string, run: NestedRunSummary): string | undefined {
@@ -947,15 +947,6 @@ export function readNestedControlResults(route: NestedRoute): NestedControlResul
 		.flatMap((entry) => readControlResultsFromFile(route, path.join(route.eventSink, entry)));
 }
 
-export function nestedRouteEnv(route: NestedRoute): Record<string, string> {
-	return {
-		[SUBAGENT_PARENT_EVENT_SINK_ENV]: route.eventSink,
-		[SUBAGENT_PARENT_CONTROL_INBOX_ENV]: route.controlInbox,
-		[SUBAGENT_PARENT_ROOT_RUN_ID_ENV]: route.rootRunId,
-		[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV]: route.capabilityToken,
-	};
-}
-
 export function attachRootChildrenToSteps<T extends { children?: NestedRunSummary[]; index?: number }>(rootRunId: string, steps: T[] | undefined, children: NestedRunSummary[] | undefined): void {
 	if (!steps?.length) return;
 	for (const step of steps) {
@@ -1067,13 +1058,6 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 	};
 }
 
-export function nestedArtifactEnv(rootRunId: string, parentRunId: string): Record<string, string> {
-	return {
-		PI_SUBAGENT_NESTED_ROOT_RUN_ID: rootRunId,
-		PI_SUBAGENT_NESTED_PARENT_RUN_ID: parentRunId,
-	};
-}
-
 export function isTopLevelAsyncDir(asyncDir: string): boolean {
 	const resolved = path.resolve(asyncDir);
 	return containedPath(DIRS.async, resolved) && !containedPath(path.join(TEMP_ROOT_DIR, "nested-subagent-runs"), resolved);

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

@@ -36,17 +36,3 @@ export function sanitizeNestedPath(value: unknown): NestedPathEntry[] {
 		};
 	}).filter((part): part is NestedPathEntry => Boolean(part)).slice(0, MAX_NESTED_PATH_ENTRIES);
 }
-
-export function parseNestedPathEnv(value: string | undefined): NestedPathEntry[] {
-	if (!value) return [];
-	try {
-		return sanitizeNestedPath(JSON.parse(value) as unknown);
-	} catch {
-		return [];
-	}
-}
-
-export function encodeNestedPathEnv(value: NestedPathEntry[]): string {
-	const sanitized = sanitizeNestedPath(value);
-	return sanitized.length ? JSON.stringify(sanitized) : "";
-}

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

@@ -56,7 +56,8 @@ export interface OrcaProgressTab {
 	append(text: string): void;
 	section(input: { agent: string; index: number; count: number }): void;
 	event(event: { type?: string; message?: Message; toolName?: string; args?: unknown }): void;
-	finish(status: "completed" | "failed" | "stopped", sessionFile?: string): void;
+	/** Resolves once the mirrored log and its done marker are on disk, so a host may exit afterwards. */
+	finish(status: "completed" | "failed" | "stopped", sessionFile?: string): Promise<void>;
 }
 
 function executableFile(candidate: string): boolean {
@@ -475,7 +476,7 @@ export function createOrcaProgressTab(input: {
 			}
 		},
 		finish(status, sessionFile) {
-			if (!available || finished) return;
+			if (!available || finished) return Promise.resolve();
 			finished = true;
 			const sessionId = status === "completed" ? resolvePiSessionId(sessionFile) : undefined;
 			let verifiedSessionFile: string | undefined;
@@ -488,11 +489,15 @@ export function createOrcaProgressTab(input: {
 			const truncation = truncated ? `\n[progress mirror truncated at ${MAX_MIRROR_BYTES} bytes]\n` : "";
 			let footer = `${truncation}\n${"─".repeat(48)}\n${terminalMessage}\n`;
 			if (scheduledBytes + Buffer.byteLength(footer) > MAX_MIRROR_BYTES) footer = `\n${status}\n`;
-			logStream.end(footer, () => {
-				if (!available) return;
-				try { fs.writeFileSync(donePath, `${status}\n`, { encoding: "utf-8", mode: 0o600 }); } catch { /* best effort */ }
-				cleanupPaths = [logPath, donePath];
-				scheduleDeferredCleanup();
+			return new Promise<void>((resolve) => {
+				logStream.end(footer, () => {
+					if (available) {
+						try { fs.writeFileSync(donePath, `${status}\n`, { encoding: "utf-8", mode: 0o600 }); } catch { /* best effort */ }
+						cleanupPaths = [logPath, donePath];
+						scheduleDeferredCleanup();
+					}
+					resolve();
+				});
 			});
 		},
 	};

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

@@ -47,8 +47,6 @@ export interface RunnerSubagentStep {
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
 	mcpDirectTools?: string[];
-	mcpConfig?: import("./mcp-direct-tool-allowlist.ts").McpConfig;
-	runtimeServerNames?: string[];
 	mutationTools?: string[];
 	completionGuard?: boolean;
 	systemPrompt?: string | null;

package/src/runs/shared/permissions.ts

@@ -5,8 +5,6 @@ export type PermissionDecision = "allow" | "ask" | "deny";
 export type PermissionRules = Record<string, PermissionDecision>;
 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", "bg_wait", "structured_output"]);
 const DECISIONS = new Set<PermissionDecision>(["allow", "ask", "deny"]);
 const MAX_POLICY_BYTES = 16 * 1024;
@@ -52,17 +50,6 @@ export function permissionDecision(rules: PermissionRules | undefined, toolName:
 	return rules?.[toolName] ?? "allow";
 }
 
-export function encodePermissionRules(rules: PermissionRules | undefined): string | undefined {
-	if (!rules || Object.keys(rules).length === 0) return undefined;
-	const encoded = JSON.stringify(rules);
-	if (Buffer.byteLength(encoded, "utf-8") > MAX_POLICY_BYTES) throw new Error("Resolved permission policy is too large.");
-	return encoded;
-}
-
-export function decodePermissionRules(encoded: string | undefined): PermissionRules | undefined {
-	if (!encoded?.trim()) return undefined;
-	return validatePermissionRules(JSON.parse(encoded), PERMISSION_POLICY_ENV);
-}
 
 function redact(value: unknown, key = "", depth = 0): unknown {
 	if (SECRET_KEY.test(key)) return "[redacted]";

package/src/runs/shared/process-signal.ts

@@ -4,9 +4,12 @@ export function formatProcessSignalError(signal: string): string {
 
 export function formatMidToolExitError(input: {
 	toolName: string;
-	exitCode: number | null;
+	exitCode?: number | null;
 	processSignal?: string | null;
 }): string {
+	if (input.exitCode === undefined && !input.processSignal) {
+		return `Subagent session ended during '${input.toolName}' tool execution before the tool completed. Earlier assistant output is not a terminal result.`;
+	}
 	const terminal = [`exit ${input.exitCode ?? "unknown"}`, ...(input.processSignal ? [`signal ${input.processSignal}`] : [])].join(", ");
 	return `Subagent process exited during '${input.toolName}' tool execution (${terminal}) before the tool completed. Earlier assistant output is not a terminal result.`;
 }

package/src/runs/shared/run-fanout-budget.ts

@@ -9,7 +9,6 @@ import {
 	type RunFanoutRejection,
 } from "../../shared/types.ts";
 
-export const RUN_FANOUT_BUDGET_ENV = "PI_SUBAGENT_RUN_FANOUT_BUDGET";
 const RUN_FANOUT_ROOT = path.join(TEMP_ROOT_DIR, "run-fanout-budgets");
 
 interface ManifestV1 {
@@ -124,18 +123,6 @@ export function readRunFanoutBudgetDescriptor(asyncDir: string | undefined): Run
 	}
 }
 
-export function encodeRunFanoutBudgetDescriptor(descriptor: RunFanoutBudgetDescriptor): string {
-	return Buffer.from(JSON.stringify(validateRunFanoutBudgetDescriptor(descriptor)), "utf-8").toString("base64url");
-}
-
-export function decodeRunFanoutBudgetDescriptor(encoded: string | undefined): RunFanoutBudgetDescriptor | undefined {
-	if (!encoded) return undefined;
-	try {
-		return validateRunFanoutBudgetDescriptor(JSON.parse(Buffer.from(encoded, "base64url").toString("utf-8")));
-	} catch (error) {
-		throw new Error(`Invalid inherited run fan-out budget: ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
 
 interface AdmissionLockOwner {
 	pid: number;

package/src/runs/shared/runtime-acknowledged-extensions.ts

@@ -1,13 +1,8 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
 import type { RuntimeAcknowledgedChildExtensionsV1 } from "../../shared/types.ts";
 
 export const RUNTIME_EXTENSION_ACK_EVENT = "subagent:acknowledge-extension";
-export const RUNTIME_EXTENSION_ACK_PATH_ENV = "PI_SUBAGENT_RUNTIME_ACKNOWLEDGED_EXTENSIONS";
 export const MAX_RUNTIME_ACKNOWLEDGED_EXTENSION_IDS = 32;
 export const MAX_RUNTIME_ACKNOWLEDGED_EXTENSION_ID_LENGTH = 128;
-// Generous bound for a valid capture (32 ids x 128 chars plus envelope); larger files are child misbehavior.
-export const MAX_RUNTIME_ACKNOWLEDGED_EXTENSION_FILE_BYTES = 64 * 1024;
 
 export function isRuntimeAcknowledgedExtensionId(value: unknown): value is string {
 	return typeof value === "string"
@@ -47,25 +42,3 @@ export function sanitizeRuntimeAcknowledgedExtensions(value: unknown): RuntimeAc
 		: 0;
 	return { ...projected, omitted: projected.omitted + omitted };
 }
-
-export function readRuntimeAcknowledgedExtensions(filePath: string | undefined): RuntimeAcknowledgedChildExtensionsV1 | undefined {
-	if (!filePath) return undefined;
-	try {
-		if (fs.statSync(filePath).size > MAX_RUNTIME_ACKNOWLEDGED_EXTENSION_FILE_BYTES) return undefined;
-		const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
-		return sanitizeRuntimeAcknowledgedExtensions(parsed);
-	} catch {
-		return undefined;
-	}
-}
-
-export function writeRuntimeAcknowledgedExtensions(filePath: string, ids: Iterable<unknown>): void {
-	const projection = projectRuntimeAcknowledgedExtensions(ids);
-	try {
-		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		if (projection) fs.writeFileSync(filePath, JSON.stringify(projection), { mode: 0o600 });
-		else fs.rmSync(filePath, { force: true });
-	} catch {
-		// Runtime acknowledgement is best-effort observability only.
-	}
-}

package/src/runs/shared/structured-output.ts

@@ -7,10 +7,6 @@ import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
 import type { JsonSchemaObject } from "../../shared/types.ts";
 import type { ResolvedAcceptanceReportMode } from "./acceptance.ts";
 
-export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
-export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
-export const STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE";
-export const STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED";
 export const MISSING_STRUCTURED_OUTPUT_CALL_ERROR = "Missing structured_output call; this step has outputSchema and must finish by calling structured_output.";
 export const MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR = "Missing acceptanceReport in structured_output call; acceptance.report is \"on\".";
 
@@ -200,6 +196,23 @@ export function readStructuredOutputAcceptanceReport(runtime: StructuredOutputRu
 	}
 }
 
+/**
+ * Capture callback that persists the structured output (and acceptance report)
+ * to the runtime's files, for hosts that read the value back from disk.
+ */
+export function createStructuredOutputFileCapture(runtime: StructuredOutputRuntime): (value: unknown, acceptanceReport: unknown | undefined) => void {
+	return (value, acceptanceReport) => {
+		fs.mkdirSync(path.dirname(runtime.outputPath), { recursive: true });
+		if (runtime.acceptanceReportPath && acceptanceReport !== undefined) {
+			fs.mkdirSync(path.dirname(runtime.acceptanceReportPath), { recursive: true });
+			fs.writeFileSync(runtime.acceptanceReportPath, JSON.stringify(acceptanceReport), { mode: 0o600 });
+		} else if (runtime.acceptanceReportPath && fs.existsSync(runtime.acceptanceReportPath)) {
+			fs.unlinkSync(runtime.acceptanceReportPath);
+		}
+		fs.writeFileSync(runtime.outputPath, JSON.stringify(value), { mode: 0o600 });
+	};
+}
+
 export function clearStructuredOutputCaptures(runtime: StructuredOutputRuntime): string | undefined {
 	let cleanupError: string | undefined;
 	for (const filePath of [runtime.outputPath, runtime.acceptanceReportPath]) {

package/src/runs/shared/subagent-control.ts

@@ -45,11 +45,12 @@ export function resolveControlConfig(
 	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
 	const overrideNeedsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs);
 	const globalNeedsAttentionAfterMs = parsePositiveInt(globalConfig?.needsAttentionAfterMs);
+	const globalNeedsAttentionAfterMsIsExplicit = (globalConfig as Partial<ResolvedControlConfig> | undefined)?.needsAttentionAfterMsIsExplicit ?? globalNeedsAttentionAfterMs !== undefined;
 	const needsAttentionAfterMs = overrideNeedsAttentionAfterMs
 		?? globalNeedsAttentionAfterMs
 		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
 	const needsAttentionAfterMsIsExplicit = overrideNeedsAttentionAfterMs !== undefined
-		|| globalNeedsAttentionAfterMs !== undefined;
+		|| globalNeedsAttentionAfterMsIsExplicit;
 	const activeNoticeAfterMs = parsePositiveInt(override?.activeNoticeAfterMs)
 		?? parsePositiveInt(globalConfig?.activeNoticeAfterMs)
 		?? DEFAULT_CONTROL_CONFIG.activeNoticeAfterMs;
@@ -98,11 +99,12 @@ export function deriveActivityState(input: {
 	config: ResolvedControlConfig;
 	startedAt: number;
 	lastActivityAt?: number;
+	turnCount?: number;
 	currentTool?: string;
 	thinking?: string | false;
 	now?: number;
 }): ActivityState | undefined {
-	if (!input.config.enabled || input.currentTool) return undefined;
+	if (!input.config.enabled || input.currentTool || (input.turnCount ?? 0) === 0) return undefined;
 	const now = input.now ?? Date.now();
 	const lastActivity = input.lastActivityAt ?? input.startedAt;
 	const ageMs = Math.max(0, now - lastActivity);
@@ -136,6 +138,7 @@ export function buildControlEvent(input: {
 	tokens?: number;
 	toolCount?: number;
 	currentTool?: string;
+	toolCallId?: string;
 	currentToolDurationMs?: number;
 	currentPath?: string;
 	elapsedMs?: number;
@@ -168,6 +171,7 @@ export function buildControlEvent(input: {
 		...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
 		...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
 		...(input.currentTool ? { currentTool: input.currentTool } : {}),
+		...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
 		...(input.currentToolDurationMs !== undefined ? { currentToolDurationMs: input.currentToolDurationMs } : {}),
 		...(input.currentPath ? { currentPath: input.currentPath } : {}),
 		...(elapsedMs !== undefined ? { elapsedMs } : {}),