pi-subagents 0.67.0 → 0.69.0

package/src/runs/shared/{model-fallback.ts → model-resolution.ts}

@@ -1,17 +1,11 @@
 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";
-import { redactSecretValues } from "./permissions.ts";
 
 export type { AvailableModelInfo };
 
-interface ModelAttemptSummary {
-	model: string;
-	success: boolean;
-	exitCode?: number | null;
-	error?: string;
-	usage?: Usage;
+export interface ModelSelectionEvidence {
+	model?: string;
+	requestedModel?: string;
 }
 
 export { splitThinkingSuffix };
@@ -290,57 +284,6 @@ 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)}`;
-}
-
-const MODEL_UNAVAILABLE_EXCLUSION_PATTERNS = [
-	/model.*not found/i,
-	/unknown model/i,
-	/model.*unavailable/i,
-	/model.*disabled/i,
-];
-
-function isCurrentRegistryModel(candidate: string, availableModels: AvailableModelInfo[] | undefined): boolean {
-	if (!availableModels || availableModels.length === 0) return false;
-	const { baseModel } = splitThinkingSuffix(candidate);
-	return availableModels.some((entry) => entry.fullId === baseModel);
-}
-
-function ignoreStaleModelUnavailableExclusion(candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>, availableModels: AvailableModelInfo[] | undefined): boolean {
-	const reason = exclusion.reason ?? "";
-	return MODEL_UNAVAILABLE_EXCLUSION_PATTERNS.some((pattern) => pattern.test(reason)) && isCurrentRegistryModel(candidate, availableModels);
-}
-
-function throwForExplicitModelExclusion(model: string): void {
-	const exclusion = findModelExclusion(model);
-	if (!exclusion) return;
-	const reason = redactSecretValues((exclusion.reason ?? "runtime-failure").replace(/[\u0000-\u001f\u007f]+/g, " ")).slice(0, 240);
-	const expiry = Number.isFinite(exclusion.expiresAt) ? `; expires: ${new Date(exclusion.expiresAt).toISOString()}` : "";
-	throw new Error(`Requested subagent model '${model}' is excluded and cannot be replaced by a fallback (reason: ${reason}${expiry}).`);
-}
-
 /**
  * Resolve the `--model` override passed to a spawned subagent.
  *
@@ -377,7 +320,6 @@ export function resolveSubagentModelOverride(
 		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;
@@ -421,19 +363,15 @@ export function resolveEffectiveSubagentModel(
 
 export type ModelOrigin = ModelSource | "configured";
 
-export interface BuildModelCandidatesOptions {
-	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
+export interface ResolveModelSelectionOptions {
 	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. */
+	/** How the model was selected. */
 	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;
@@ -458,176 +396,30 @@ export function inheritsParentModel(
 	return Boolean(parentModel && (!trimmed || trimmed === INHERIT_MODEL));
 }
 
-export function buildModelCandidates(
-	primaryModel: string | undefined,
-	fallbackModels: string[] | undefined,
+export function resolveModelSelection(
+	model: string | undefined,
 	availableModels: AvailableModelInfo[] | undefined,
 	preferredProvider?: string,
-	options?: BuildModelCandidatesOptions,
-): string[] {
-	if (!primaryModel) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
+	options?: ResolveModelSelectionOptions,
+): ModelSelectionEvidence {
+	if (!model) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
 	const origin = options?.origin ?? (options?.primaryModelFromParent ? "inherited" : "configured");
+	const requestedModel = origin === "inherited" ? undefined : model;
 	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>>) => {
-		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);
-		throwForExplicitModelExclusion(normalized);
+	if (origin === "explicit" && model) {
+		const normalized = resolveRequiredSubagentModelCandidate(model.trim(), availableModels, preferredProvider);
 		enforceModelScopes(normalized, scopes, "explicit", options?.onWarn);
-		primaryModel = normalized;
-	}
-	const seen = new Set<string>();
-	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;
-		const model = raw.trim();
-		const normalized = index === 0 && (origin === "inherited" || origin === "explicit" || options?.primaryModelFromParent)
-			? model
-			: resolveSubagentModelCandidate(model, availableModels, preferredProvider);
-		if (!normalized) {
-			if (index === 0) skippedPrimary = model;
-			else {
-				skippedFallback ??= model;
-				console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
-			}
-			continue;
-		}
-		if (seen.has(normalized)) continue;
-		if (index > 0 || scopes.some((scope) => scope.enforce === true && scope.strict === true)) {
-			enforceModelScopes(normalized, scopes, "inherited", options?.onWarn);
-		}
-		seen.add(normalized);
-		candidates.push(normalized);
-	}
-	const resolved = filterFallbackCandidates(candidates, {
-		onExcluded: warnCachedExclusion,
-		ignoreExclusion: (candidate, exclusion) => ignoreStaleModelUnavailableExclusion(candidate, exclusion, availableModels),
-	});
-	if (resolved.length === 0) {
-		if (skippedPrimary) resolveRequiredSubagentModelCandidate(skippedPrimary, availableModels, preferredProvider);
-		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;
+		model = normalized;
 	}
-	if (skippedPrimary) {
-		console.warn(`[pi-subagents] Skipping primary model '${skippedPrimary}' because it is unavailable in this environment.`);
+	const resolved = model && (origin === "inherited" || origin === "explicit" || options?.primaryModelFromParent)
+		? model.trim()
+		: model ? resolveRequiredSubagentModelCandidate(model.trim(), availableModels, preferredProvider) : undefined;
+	if (resolved && scopes.some((scope) => scope.enforce === true && scope.strict === true)) {
+		enforceModelScopes(resolved, scopes, "inherited", options?.onWarn);
 	}
-	return resolved;
-}
-
-const RETRYABLE_MODEL_FAILURE_PATTERNS = [
-	/^REQUEST_LIMIT_EXCEEDED$/,
-	/rate\s*limit/i,
-	/usage\s*limit/i,
-	/too many requests/i,
-	/\b429\b/,
-	/quota/i,
-	/billing/i,
-	/credit/i,
-	// OpenRouter can return only a status-prefixed body, without auth-related prose.
-	/^\s*401\s*:/,
-	/auth(?:entication)?/i,
-	/unauthori[sz]ed/i,
-	/forbidden/i,
-	/api key/i,
-	/token expired/i,
-	/invalid key/i,
-	/provider.*unavailable/i,
-	/model.*unavailable/i,
-	/model.*disabled/i,
-	/model.*not found/i,
-	/unknown model/i,
-	/overloaded/i,
-	/service unavailable/i,
-	/temporar(?:ily)? unavailable/i,
-	/connection\s+(?:error|reset|closed|aborted)/i,
-	/connection refused/i,
-	/fetch failed/i,
-	/network error/i,
-	/socket hang up/i,
-	/stream ended without finish_reason/i,
-	/upstream/i,
-	/timed? out/i,
-	/timeout/i,
-	/\b500\b/,
-	/\b502\b/,
-	/\b503\b/,
-	/\b504\b/,
-	/internal server error/i,
-	/cold.?start/i,
-	/empty response/i,
-	/no output/i,
-	/model.*(?:load|fail|error)/i,
-];
-
-/**
- * Failures reported as `<tool> failed (exit N): ...` or `<tool> failed with
- * exit code N` come from a tool call inside the child's task, not from the
- * provider/model, however network-flavored their details read. Retrying a
- * different model cannot fix them and would rerun the whole task. Tool names
- * include namespaced forms like `mcp.server/write`.
- */
-const TOOL_FAILURE_PREFIX = /^[\w.:@/-]+ failed (?:(?:\(exit \d+\):)|(?:with exit code \d+))(?:\s|$)/i;
-
-export function isRetryableModelFailure(error: string | undefined): boolean {
-	if (!error) return false;
-	if (TOOL_FAILURE_PREFIX.test(error.trim())) return false;
-	return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
-}
-
-function messageError(message: unknown): string | undefined {
-	if (!message || typeof message !== "object") return undefined;
-	const value = (message as { errorMessage?: unknown }).errorMessage;
-	return typeof value === "string" ? value : undefined;
-}
-
-export function isRetryableModelFailureAttempt(input: { error: string | undefined; messages?: readonly unknown[]; toolCount?: number }): boolean {
-	if (!isRetryableModelFailure(input.error)) return false;
-	if ((input.toolCount ?? 0) > 0) return false;
-	if (input.error === "Subagent produced no output (possible model cold-start or empty response)." || /^Subagent produced no output after terminal assistant stopReason "[^"]+"\.$/.test(input.error ?? "")) return true;
-	if ((input.toolCount ?? 0) === 0 && (input.messages?.length ?? 0) === 0) return true;
-	const error = input.error?.trim();
-	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 || !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 } : {}) });
+	return { ...(resolved ? { model: resolved } : {}), ...(requestedModel ? { requestedModel } : {}) };
 }
-
-/**
- * Context-overflow signals. These are deliberately NOT part of
- * {@link RETRYABLE_MODEL_FAILURE_PATTERNS}: an overflow means the input was too
- * large for the model's context window, so retrying the same input on another
- * model (or the same model again) cannot succeed. Callers should treat overflow
- * as a terminal, non-retryable failure and surface a clear "input too large"
- * error instead of burning fallback attempts on a guaranteed failure.
- */
+/** Context-overflow signals used to surface a clear input-too-large error. */
 const CONTEXT_OVERFLOW_PATTERNS = [
 	/context(?: length| window| limit)? (?:exceed|overflow|too long)/i,
 	/maximum context length/i,
@@ -644,13 +436,6 @@ const CONTEXT_OVERFLOW_PATTERNS = [
 
 export function isContextOverflow(error: string | undefined): boolean {
 	if (!error) return false;
-	if (TOOL_FAILURE_PREFIX.test(error.trim())) return false;
+	if (/^[\w.:@/-]+ failed (?:(?:\(exit \d+\):)|(?:with exit code \d+))(?:\s|$)/i.test(error.trim())) return false;
 	return CONTEXT_OVERFLOW_PATTERNS.some((pattern) => pattern.test(error));
 }
-
-export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
-	const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
-	return nextModel
-		? `[fallback] ${attempt.model} failed: ${failure}. Retrying with ${nextModel}.`
-		: `[fallback] ${attempt.model} failed: ${failure}.`;
-}

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

@@ -17,7 +17,7 @@ import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
 
 export interface ModelScopeRule {
 	enforce?: boolean;
-	/** Reject inherited and fallback models outside the allowlist instead of warning. */
+	/** Reject inherited models outside the allowlist instead of warning. */
 	strict?: boolean;
 	/** Glob-style allow patterns (only `*` is special), matched against `provider/id`. */
 	allow?: string[];

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

@@ -232,10 +232,12 @@ function sanitizeLaunchResolvedExtensions(value: unknown): LaunchResolvedChildEx
 		disableAmbientExtensions: raw.disableAmbientExtensions,
 		runtime: stringList(raw.runtime),
 		configured: stringList(raw.configured),
+		required: Array.isArray(raw.required) ? raw.required.filter((item): item is string => typeof item === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(item)).slice(0, 32) : [],
 		effective: stringList(raw.effective),
 		omitted: {
 			runtime: omittedCount("runtime"),
 			configured: omittedCount("configured"),
+			required: omittedCount("required"),
 			effective: omittedCount("effective"),
 		},
 	};
@@ -1063,8 +1065,15 @@ export function isTopLevelAsyncDir(asyncDir: string): boolean {
 	return containedPath(DIRS.async, resolved) && !containedPath(path.join(TEMP_ROOT_DIR, "nested-subagent-runs"), resolved);
 }
 
-export function nestedResultsPath(rootRunId: string, id: string): string {
+export function nestedRunScope(rootRunId: string) {
 	assertSafeId("rootRunId", rootRunId);
+	return {
+		asyncDirRoot: path.join(TEMP_ROOT_DIR, "nested-subagent-runs", rootRunId),
+		resultsDir: path.join(DIRS.results, "nested", rootRunId),
+	};
+}
+
+export function nestedResultsPath(rootRunId: string, id: string): string {
 	assertSafeId("id", id);
-	return path.join(DIRS.results, "nested", rootRunId, `${id}.json`);
+	return path.join(nestedRunScope(rootRunId).resultsDir, `${id}.json`);
 }

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

@@ -10,6 +10,10 @@ export interface RunnerSubagentStep {
 	sessionName?: string;
 	task: string;
 	runner?: ResolvedRunnerConfig;
+	/** Herdr saved machine this external-cli step runs on; `cwd` is then the directory on that machine. */
+	machine?: import("../../shared/types.ts").HerdrMachineReference;
+	remoteReads?: string[] | false;
+	machineEnv?: Record<string, string>;
 	externalJobFollowUp?: {
 		sourceRunId: string;
 		sourceStepIndex: number;
@@ -37,7 +41,7 @@ export interface RunnerSubagentStep {
 	fast?: boolean;
 	thinking?: string;
 	thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
-	modelCandidates?: string[];
+	requestedModel?: string;
 	/** The primary model is inherited from the parent session and should not be verified against the child-reported active registry model. */
 	skipPrimaryModelVerification?: boolean;
 	modelVerificationRegistry?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
@@ -47,6 +51,8 @@ export interface RunnerSubagentStep {
 	allowNestedSubagents?: boolean;
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
+	/** Private immutable host policy snapshot serialized to the native runner. */
+	requiredExtensions?: import("../../shared/required-child-extensions.ts").RequiredChildExtensionSnapshot;
 	mcpDirectTools?: string[];
 	mutationTools?: string[];
 	completionGuard?: boolean;
@@ -237,7 +243,6 @@ export interface ParallelTaskResult {
 	error?: string;
 	timedOut?: boolean;
 	model?: string;
-	attemptedModels?: string[];
 	outputTargetPath?: string;
 	outputTargetExists?: boolean;
 }

package/src/runs/shared/pi-spawn.ts

@@ -63,7 +63,7 @@ export interface PiSpawnDeps {
 export function resolveBunPiExecutable(deps: PiSpawnDeps = {}): string | undefined {
 	const bunVersion = deps.bunVersion ?? process.versions.bun;
 	const entry = deps.argv1 ?? process.argv[1];
-	if (!bunVersion || !entry?.startsWith("/$bunfs/")) return undefined;
+	if (!bunVersion || !entry || !/^(?:\/\$bunfs\/|B:[\\/]~BUN[\\/])/.test(entry)) return undefined;
 	const env = deps.env ?? process.env;
 	return env[PI_SUBAGENT_PI_BINARY_ENV]?.trim() || (deps.execPath ?? process.execPath);
 }

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -17,6 +17,7 @@ import { registerChildWatchdog } from "../../watchdog/register-child.ts";
 import type { ChildWatchdogConfig } from "../../watchdog/child-status.ts";
 import { requestWatchdogPermission, type WatchdogPermissionRequest, type WatchdogPermissionResult } from "../../watchdog/permission-arbiter.ts";
 import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.ts";
+import { inheritedNestedRouteOf } from "./nested-events.ts";
 import { registerWaitTool } from "../background/wait-tool.ts";
 import { drainOutstandingWork } from "../background/auto-drain.ts";
 import {
@@ -466,7 +467,8 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 		watcherRestartTimer: null,
 		resultFileCoalescer: { schedule: () => false, clear: () => {} },
 	} as unknown as SubagentState;
-	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs);
+	const nestedRootRunId = inheritedNestedRouteOf(config)?.rootRunId;
+	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs, { nestedRootRunId });
 	const supervisorMetadata = childSupervisorMetadata(config);
 	let nativeSupervisorClientRegistered = false;
 	const registerNativeSupervisorClientOnce = (): void => {
@@ -495,7 +497,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 		}
 		config.holdFinalDrain?.(true);
 		try {
-			await drainOutstandingWork({ state: waitState, events: pi.events }, drainObservation);
+			await drainOutstandingWork({ state: waitState, events: pi.events, nestedRootRunId, hasPendingSupervisorRequest: config.hasPendingSupervisorRequest }, drainObservation);
 		} finally {
 			config.holdFinalDrain?.(false);
 		}

package/src/runs/shared/worktree-setup-command.ts

@@ -2,6 +2,26 @@ import { spawn } from "node:child_process";
 import { createOwnedProcessTreeController } from "../background/owned-process-tree.ts";
 import type { ProcessTreeTerminal } from "../../shared/types.ts";
 
+function terminateCommandTree(pid: number, controller: ReturnType<typeof createOwnedProcessTreeController>): Promise<ProcessTreeTerminal> {
+	if (process.platform !== "win32") return controller.terminate();
+	return new Promise((resolve) => {
+		let settled = false;
+		const fallback = () => {
+			if (settled) return;
+			settled = true;
+			void controller.terminate().then(resolve);
+		};
+		const cleanup = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+		cleanup.once("error", fallback);
+		cleanup.once("close", (status) => {
+			if (settled) return;
+			if (status !== 0) return fallback();
+			settled = true;
+			resolve({ state: "observed", mechanism: "windows-taskkill", pid, verifiedAt: Date.now() });
+		});
+	});
+}
+
 export interface SetupCommandOptions {
 	cwd?: string;
 	env?: NodeJS.ProcessEnv;
@@ -19,6 +39,7 @@ export interface SetupCommandOptions {
 
 export interface SetupCommandResult {
 	stdout: string;
+	stdoutBuffer: Buffer;
 	stderr: string;
 	status: number | null;
 	signal: NodeJS.Signals | null;
@@ -46,7 +67,7 @@ export async function runSetupCommand(
 	options: SetupCommandOptions,
 ): Promise<SetupCommandResult> {
 	const result: SetupCommandResult = {
-		stdout: "", stderr: "", status: null, signal: null, outputIncomplete: false,
+		stdout: "", stdoutBuffer: Buffer.alloc(0), stderr: "", status: null, signal: null, outputIncomplete: false,
 	};
 	const maxBuffer = options.maxBuffer ?? 1024 * 1024;
 	if (!Number.isSafeInteger(maxBuffer) || maxBuffer <= 0) throw new Error("Invalid setup command maxBuffer");
@@ -84,7 +105,8 @@ export async function runSetupCommand(
 	let directSettled = false;
 	const releaseUnknownIO = () => {
 		if (!directSettled || result.processTree?.state !== "unknown") return;
-		result.error ??= commandError("Worktree setup process tree settlement is unverified", "PROCESS_TREE_UNVERIFIED");
+		const detail = result.processTree.diagnostic ? `: ${result.processTree.diagnostic}` : "";
+		result.error = commandError(`Worktree setup process tree settlement is unverified${detail}`, "PROCESS_TREE_UNVERIFIED");
 		result.outputIncomplete = true;
 		// Only local I/O is released; unknown descendant ownership remains retained.
 		child.stdin.destroy();
@@ -101,7 +123,7 @@ export async function runSetupCommand(
 			releaseUnknownIO();
 			return;
 		}
-		termination = tree.terminate().then((proof) => {
+		termination = terminateCommandTree(result.pid!, tree).then((proof) => {
 			result.processTree = proof;
 			releaseUnknownIO();
 			return proof;
@@ -177,7 +199,8 @@ export async function runSetupCommand(
 		if (termination) result.processTree = await termination;
 		const cancelled = cancellation();
 		if (cancelled) fail(cancelled);
-		result.stdout = Buffer.concat(stdout).toString("utf8");
+		result.stdoutBuffer = Buffer.concat(stdout);
+		result.stdout = result.stdoutBuffer.toString("utf8");
 		result.stderr = Buffer.concat(stderr).toString("utf8");
 		return result;
 	} finally {

package/src/runs/shared/worktree.ts

@@ -180,7 +180,7 @@ export interface WorktreeSetupProgress {
 	setup: WorktreeSetup;
 	attempts: Array<{ index: number; branch: string; path?: string; validated: boolean; command?: WorktreeSetupProgress["command"]; hookCommand?: WorktreeSetupProgress["command"] }>;
 	phase: string;
-	command?: { command: string; args: string[]; pid?: number; processGroupId?: number; result?: Omit<SetupCommandResult, "stdout" | "stderr"> };
+	command?: { command: string; args: string[]; pid?: number; processGroupId?: number; result?: Omit<SetupCommandResult, "stdout" | "stdoutBuffer" | "stderr"> };
 	unknown?: string;
 	cleanup?: WorktreeCleanupReport;
 }
@@ -245,7 +245,7 @@ class SetupTransaction {
 			...options, signal: this.options.signal, deadlineAt: this.options.deadlineAt,
 			onSpawn: (process) => { Object.assign(this.progress.command!, process); this.publish(); },
 		});
-		const { stdout: _stdout, stderr: _stderr, ...metadata } = result;
+		const { stdout: _stdout, stdoutBuffer: _stdoutBuffer, stderr: _stderr, ...metadata } = result;
 		this.progress.command.result = metadata;
 		if (result.processTree?.state === "unknown") this.unknown(result.error ?? "Command tree settlement unverified");
 		this.publish();
@@ -743,13 +743,35 @@ export function resolveExpectedWorktreeAgentCwd(cwd: string, runId: string, inde
 function linkNodeModulesIfPresent(toplevel: string, worktreePath: string): boolean {
 	const nodeModulesPath = path.join(toplevel, "node_modules");
 	const nodeModulesLinkPath = path.join(worktreePath, "node_modules");
-	if (!fs.existsSync(nodeModulesPath) || fs.existsSync(nodeModulesLinkPath)) return false;
+	const hasDirectoryEntry = (candidate: string): boolean => {
+		try { fs.lstatSync(candidate); return true; }
+		catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+			throw error;
+		}
+	};
 	try {
-		fs.symlinkSync(nodeModulesPath, nodeModulesLinkPath);
+		if (hasDirectoryEntry(nodeModulesLinkPath)) return false;
+		let sourceRealPath: string;
+		try {
+			if (!fs.statSync(nodeModulesPath).isDirectory()) throw new Error("source node_modules is not a directory");
+			sourceRealPath = fs.realpathSync.native(nodeModulesPath);
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+			throw error;
+		}
+		fs.symlinkSync(nodeModulesPath, nodeModulesLinkPath, process.platform === "win32" ? "junction" : "dir");
+		if (!fs.lstatSync(nodeModulesLinkPath).isSymbolicLink()
+			|| fs.realpathSync.native(nodeModulesLinkPath) !== sourceRealPath) {
+			throw new Error("created link does not resolve to the source node_modules");
+		}
 		return true;
-	} catch {
-		// Symlink creation is optional (e.g., unsupported filesystems on CI runners).
-		return false;
+	} catch (error) {
+		const code = error instanceof Error && "code" in error && typeof error.code === "string" ? `${error.code}: ` : "";
+		throw new Error(
+			`failed to link node_modules from ${nodeModulesPath} to ${nodeModulesLinkPath}: ${code}${error instanceof Error ? error.message : String(error)}`,
+			{ cause: error },
+		);
 	}
 }
 
@@ -1295,7 +1317,7 @@ async function compensateSetup(tx: SetupTransaction): Promise<WorktreeCleanupRep
 			deadlineAt: tx.options.deadlineAt, acceptedExitCodes,
 			onSpawn: (process) => { Object.assign(tx.progress.command!, process); tx.publish(); },
 		});
-		const { stdout: _stdout, stderr: _stderr, ...metadata } = result;
+		const { stdout: _stdout, stdoutBuffer: _stdoutBuffer, stderr: _stderr, ...metadata } = result;
 		tx.progress.command.result = metadata;
 		if (result.processTree?.state === "unknown") tx.unknown(result.error ?? "Rollback command settlement unverified");
 		tx.publish();

package/src/shared/child-cache-retention.ts

@@ -0,0 +1,43 @@
+import type { StreamFn } from "@earendil-works/pi-agent-core";
+
+/**
+ * Anthropic prices a cache write by the TTL it is asked for: 1.25x base input
+ * for the 5m window, 2x for the 1h one. Child sessions are short-lived and
+ * rarely idle, so a 1h window they never claim is a flat surcharge on every
+ * write. Setting this to `short` keeps that surcharge off children while the
+ * parent keeps `long`, the same split Claude Code makes between its main
+ * conversation and its subagents.
+ *
+ * Unset means children inherit the parent's retention, which is the behaviour
+ * before this setting existed.
+ */
+export function childCacheRetention(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	return env.PI_SUBAGENT_CACHE_RETENTION || undefined;
+}
+
+/**
+ * Launch-environment form for spawned children. Empty when unset, so the child
+ * inherits the parent's `PI_CACHE_RETENTION` rather than having it cleared.
+ */
+export function childCacheRetentionEnv(env?: NodeJS.ProcessEnv): { PI_CACHE_RETENTION?: string } {
+	const retention = childCacheRetention(env);
+	return retention ? { PI_CACHE_RETENTION: retention } : {};
+}
+
+/**
+ * Pi resolves retention per request as `options.env?.[name] || process.env[name]`,
+ * so a per-call env beats the process-wide one. Wrapping the session's own
+ * stream function keeps this scoped to one child, with no shared-state race
+ * against a parent turn streaming concurrently.
+ */
+export function pinChildCacheRetention(agent: { streamFunction: StreamFn } | undefined, env?: NodeJS.ProcessEnv): void {
+	if (!agent?.streamFunction) return;
+	const retention = childCacheRetention(env);
+	if (!retention) return;
+	const base = agent.streamFunction;
+	agent.streamFunction = (model, context, options) =>
+		base(model, context, {
+			...options,
+			env: { ...(options?.env ?? {}), PI_CACHE_RETENTION: retention },
+		});
+}