pi-subagents 0.65.1 → 0.67.0

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

@@ -29,7 +29,7 @@ const ORCA_CREATE_WATCHDOG_SCRIPT = [
 	"function exists(file){try{return fs.existsSync(file)}catch{return false}}",
 	"function keepQueued(){try{const now=new Date();fs.utimesSync(done,now,now)}catch{}}",
 	"function predecessorReady(){if(previous==='-')return true;if(exists(previous.replace(/\\.pending$/,'.ready')))return true;try{return Date.now()-fs.statSync(previous).mtimeMs>=waitTimeout}catch{return true}}",
-	"function updateManifest(state,stdout=''){if(manifest==='-')return;try{const payload=JSON.parse(fs.readFileSync(manifest,'utf8'));payload.state=state;payload.updatedAt=new Date().toISOString();const raw=stdout.trim().split(/\\r?\\n/).filter(Boolean).at(-1);if(raw){try{payload.orca=JSON.parse(raw)}catch{payload.orcaRaw=raw.slice(0,4096)}}fs.writeFileSync(manifest,JSON.stringify(payload,null,2)+'\\n')}catch{}}",
+	"function updateManifest(state,stdout=''){if(manifest==='-')return;try{const payload=JSON.parse(fs.readFileSync(manifest,'utf8'));payload.state=state;payload.updatedAt=new Date().toISOString();const raw=stdout.trim();if(raw){try{payload.orca=JSON.parse(raw)}catch{payload.orcaRaw=raw.slice(0,4096)}}fs.writeFileSync(manifest,JSON.stringify(payload,null,2)+'\\n')}catch{}}",
 	"function start(){",
 	" try{",
 	"  const child=spawn(command,args,{stdio:['ignore','pipe','ignore'],windowsHide:true});",
@@ -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;

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

@@ -49,6 +49,7 @@ export interface PiSpawnDeps {
 	platform?: NodeJS.Platform;
 	execPath?: string;
 	argv1?: string;
+	bunVersion?: string;
 	existsSync?: (filePath: string) => boolean;
 	realpathSync?: (filePath: string) => string;
 	readFileSync?: (filePath: string, encoding: "utf-8") => string;
@@ -58,6 +59,15 @@ export interface PiSpawnDeps {
 	env?: NodeJS.ProcessEnv;
 }
 
+/** Compiled Pi's entrypoint is virtual; execPath is the real (possibly renamed) image. */
+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;
+	const env = deps.env ?? process.env;
+	return env[PI_SUBAGENT_PI_BINARY_ENV]?.trim() || (deps.execPath ?? process.execPath);
+}
+
 interface PiSpawnCommand {
 	command: string;
 	args: string[];

package/src/runs/shared/readonly-drain-observation.ts

@@ -0,0 +1,42 @@
+const knownStates = new Set(["queued", "running", "complete", "failed", "partial", "paused", "stopped", "rejected"]);
+
+/**
+ * Private, installation-owned evidence. Never changes drain/query behavior or retains statuses.
+ * Observes the ordinary indexed drain, not historical ownership or outside work appearing later.
+ */
+export class ReadonlyDrainObservation {
+	private state: "pending" | "empty" | "denied" = "pending";
+	private started = false;
+	private first = false;
+	private readonly file: string;
+	private readonly guard: () => boolean;
+	constructor(file: string, guard: () => boolean) { this.file = file; this.guard = guard; }
+	deny(): void { this.state = "denied"; }
+	check(): boolean {
+		try { if (!this.guard()) this.deny(); } catch { this.deny(); }
+		return this.state !== "denied";
+	}
+	begin(file: string | null, native: boolean): void {
+		if (this.started || file !== this.file || !native) this.deny();
+		this.started = true;
+		this.check();
+	}
+	/** Called at the existing initial read, before reconciliation or filtering. */
+	readonly status: RawDrainStatusObserver = (status) => {
+		if (!status || typeof status.sessionId !== "string" || !status.sessionId
+			|| !knownStates.has(status.state as string)) this.deny();
+		else if (status.sessionId === this.file && (status.state === "queued" || status.state === "running")) this.deny();
+	};
+	predicate(hasWork: boolean): void {
+		if (this.first) return;
+		this.first = true;
+		if (hasWork) this.deny();
+	}
+	complete(): void {
+		if (this.started && this.first && this.check()) this.state = "empty";
+	}
+	settled(): boolean { return this.check() && this.state === "empty"; }
+}
+
+/** Internal synchronous sink; null means an existing query encountered uncertainty. */
+export type RawDrainStatusObserver = (status: { sessionId?: unknown; state?: unknown } | null) => void;

package/src/runs/shared/readonly-model-continuation.ts

@@ -0,0 +1,69 @@
+import type { ChildSession } from "./child-session.ts";
+import { getReadonlySessionEvidence, type SettledReadonlyEvidence } from "./readonly-session-evidence.ts";
+
+/** Owned by the logical host run, shared with abort recovery; never reset per attempt. */
+export type LogicalRecoveryState = "unused" | "abort-recovery" | "readonly-continuation";
+
+export interface ReadonlyContinuationCandidate {
+	/** Actual resolved identity, not an alias or a parsed display reference. */
+	readonly resolved: { readonly provider: string; readonly model: string; readonly api: string } | undefined;
+	readonly tried: boolean;
+	/** Host assessment of retained input support AND context capacity, including prompt overhead. */
+	readonly compatibility: "compatible" | "incompatible" | "unknown";
+}
+
+export interface ReadonlyContinuationInput {
+	/** Retain the source child privately: its live accessor detects revoked receipts. */
+	readonly source: ChildSession | undefined;
+	readonly recoveryState: LogicalRecoveryState;
+	/** Ordered, already authorized and exclusion-filtered. This planner never resolves models. */
+	readonly candidates: readonly ReadonlyContinuationCandidate[];
+	readonly currentIndex: number;
+	/** False includes success, stop/interrupt/detach/handoff, deadline, or workflow-permit veto. */
+	readonly lifecycleAllowsContinuation: boolean;
+	/** False includes completion/structured/acceptance failures, pending input or other effects. */
+	readonly effectsAllowContinuation: boolean;
+	/** Configured tool budgets are unsupported; unknown authoritative usage allowance denies. */
+	readonly budget: "unconfigured" | "available" | "exhausted" | "unknown" | "tool-budget-configured";
+	readonly knownContextOverflow: boolean;
+}
+
+export const READONLY_CONTINUATION_PROMPT = "The previous provider request failed with HTTP 429 after read-only progress. Continue from the retained transcript and completed tool results. Do not restart or repeat completed work. Use only the existing read-only tools and finish the requested response.";
+
+export type ReadonlyContinuationPlan =
+	| { readonly kind: "deny"; readonly reason: "recovery-consumed" | "veto" | "no-evidence" | "unresolved-identity" | "incompatible" | "no-sibling" }
+	| { readonly kind: "continue"; readonly candidateIndex: number; readonly expected: SettledReadonlyEvidence;
+		readonly prompt: typeof READONLY_CONTINUATION_PROMPT; readonly recoveryState: "readonly-continuation" };
+
+/**
+ * Pure decision: no disk reads, dispatch, receipt minting, or state mutation.
+ * The host MUST recheck live source proof and lifecycle/budget at handoff, then store the
+ * returned consumed state BEFORE creation (even if creation subsequently fails),
+ * and pass expected to requestReadonlySessionEvidence on the exact-file sibling launch.
+ * That factory guard owns checkpoint/configured-provider revalidation before open/prompt/dispatch.
+ * The host must also verify the actual sibling model matches the selected resolved identity;
+ * a plan is not a dispatch authorization and any create/guard failure terminates recovery.
+ */
+export function planReadonlyModelContinuation(input: ReadonlyContinuationInput): ReadonlyContinuationPlan {
+	if (input.recoveryState !== "unused") return { kind: "deny", reason: "recovery-consumed" };
+	if (!input.lifecycleAllowsContinuation || !input.effectsAllowContinuation || input.knownContextOverflow
+		|| (input.budget !== "unconfigured" && input.budget !== "available")) return { kind: "deny", reason: "veto" };
+	const expected = input.source && getReadonlySessionEvidence(input.source);
+	if (!expected || input.source?.detached || input.source?.shutDown) return { kind: "deny", reason: "no-evidence" };
+	const current = Number.isInteger(input.currentIndex) && input.currentIndex >= 0 ? input.candidates[input.currentIndex]?.resolved : undefined;
+	if (!current || current.provider !== expected.provider || current.model !== expected.model || current.api !== expected.api) {
+		return { kind: "deny", reason: "unresolved-identity" };
+	}
+	for (let index = input.currentIndex + 1; index < input.candidates.length; index++) {
+		const candidate = input.candidates[index];
+		if (!candidate) return { kind: "deny", reason: "unresolved-identity" };
+		if (candidate.tried) continue;
+		const resolved = candidate.resolved;
+		if (!resolved?.provider || !resolved.model || !resolved.api) return { kind: "deny", reason: "unresolved-identity" };
+		if (resolved.provider !== expected.provider || resolved.model === expected.model) continue;
+		if (input.candidates.some((other) => other.tried && other.resolved?.provider === resolved.provider && other.resolved.model === resolved.model)) continue;
+		if (resolved.api !== expected.api || candidate.compatibility !== "compatible") return { kind: "deny", reason: "incompatible" };
+		return { kind: "continue", candidateIndex: index, expected, prompt: READONLY_CONTINUATION_PROMPT, recoveryState: "readonly-continuation" };
+	}
+	return { kind: "deny", reason: "no-sibling" };
+}

package/src/runs/shared/readonly-session-evidence.ts

@@ -0,0 +1,307 @@
+/** Internal, opt-in factory evidence. No runner enables continuation through this module. */
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import type { AgentSession, SessionEntry, SessionHeader } from "@earendil-works/pi-coding-agent";
+import type { ChildSession, ChildSessionLaunch, PiCodingAgentModule } from "./child-session.ts";
+import { captureReadonlyChildDrain, isReadonlyChildHookProfile, isReadonlyChildSessionReporting, observeReadonlyChildHookDrain } from "./child-hooks.ts";
+
+type Runtime = Awaited<ReturnType<PiCodingAgentModule["ModelRuntime"]["create"]>>;
+type Model = NonNullable<AgentSession["model"]>;
+
+export interface SettledReadonlyEvidence {
+	readonly sessionFile: string;
+	readonly sessionId: string;
+	readonly leafId: string;
+	readonly provider: string;
+	readonly model: string;
+	readonly api: string;
+	readonly status: 429;
+	/** Complete active context, not the host's attempt-only event projection. */
+	readonly contextJson: string;
+	readonly completedToolResults: number;
+	readonly fileDigest: string;
+}
+
+const requested = new WeakMap<ChildSessionLaunch, SettledReadonlyEvidence | null>();
+const receipts = new WeakMap<ChildSession, SettledReadonlyEvidence>();
+// Opaque configured-provider continuity, never an implementation-origin attestation.
+const providers = new WeakMap<SettledReadonlyEvidence, object>();
+
+/** Internal integration seam: opt in before factory creation. Ordinary launches do no evidence I/O. */
+export function requestReadonlySessionEvidence(launch: ChildSessionLaunch, expected?: SettledReadonlyEvidence): void {
+	requested.set(launch, expected ?? null);
+}
+
+/** Only the default factory can produce a receipt; duck-typed fake child properties are ignored. */
+export function getReadonlySessionEvidence(child: ChildSession): SettledReadonlyEvidence | undefined {
+	return receipts.get(child);
+}
+
+function digest(bytes: string): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function absent(file: string): boolean {
+	try { lstatSync(file); return false; }
+	catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT"; }
+}
+
+function sameStored(disk: unknown, live: unknown): boolean {
+	// The SDK keeps optional undefined fields in memory which JSONL intentionally omits.
+	return isDeepStrictEqual(disk, JSON.parse(JSON.stringify(live)));
+}
+
+/** Must run before opening a retained file. Never repairs, truncates, or creates it. */
+export function validateReadonlySessionCheckpoint(evidence: SettledReadonlyEvidence): boolean {
+	if (!providers.has(evidence)) return false;
+	try { return digest(readFileSync(evidence.sessionFile, "utf8")) === evidence.fileDigest; }
+	catch { return false; }
+}
+
+function readHistory(file: string): { header: SessionHeader; entries: SessionEntry[]; bytes: string } {
+	const bytes = readFileSync(file, "utf8");
+	if (!bytes.endsWith("\n")) throw new Error("Incomplete session file");
+	const rows = bytes.slice(0, -1).split("\n").map((line) => JSON.parse(line));
+	const [header, ...entries] = rows;
+	if (header?.type !== "session" || header.version !== 3 || typeof header.id !== "string" || !header.id || typeof header.cwd !== "string" || !entries.length) throw new Error("Unsupported session header");
+	const ids = new Set<string>();
+	for (const entry of entries) {
+		if (!entry || typeof entry.id !== "string" || !entry.id || ids.has(entry.id) || typeof entry.type !== "string" || typeof entry.timestamp !== "string" || (entry.parentId !== null && !ids.has(entry.parentId))) throw new Error("Broken session chain");
+		ids.add(entry.id);
+	}
+	return { header, entries, bytes };
+}
+
+function activeMessages(branch: SessionEntry[]): AgentSession["messages"] {
+	const messages = branch.flatMap((entry) => {
+		if (entry.type === "message") return [entry.message];
+		// Compaction/branch summaries and custom context need their own proof; do not reconstruct them.
+		if (!["model_change", "thinking_level_change", "session_info", "label"].includes(entry.type)) throw new Error("Unsupported active context");
+		return [];
+	});
+	// Snapshot the persisted representation, not mutable SDK message references.
+	return JSON.parse(JSON.stringify(messages));
+}
+
+function completedResults(messages: AgentSession["messages"]): number {
+	const pending = new Map<string, string>();
+	const seen = new Set<string>();
+	let completed = 0;
+	for (const message of messages) {
+		if (message.role === "toolResult") {
+			if (typeof message.toolCallId !== "string" || !pending.has(message.toolCallId) || pending.get(message.toolCallId) !== message.toolName || !Array.isArray(message.content)) throw new Error("Unmatched tool result");
+			pending.delete(message.toolCallId);
+			if (!message.isError && message.content.length) completed++;
+		} else {
+			if (pending.size) throw new Error("Unresolved tool call");
+			if (message.role === "assistant") {
+				if (!Array.isArray(message.content)) throw new Error("Invalid assistant content");
+				for (const block of message.content) {
+					if (block.type !== "toolCall") continue;
+					if (!block.id || typeof block.id !== "string" || seen.has(block.id) || !["read", "ls"].includes(block.name)) throw new Error("Uncertified tool call");
+					seen.add(block.id);
+					pending.set(block.id, block.name);
+				}
+			} else if (message.role !== "user") throw new Error("Unsupported context message");
+		}
+	}
+	if (pending.size) throw new Error("Unresolved tool call");
+	return completed;
+}
+
+function eligibleLaunch(launch: ChildSessionLaunch): boolean {
+	const r = launch.runtime;
+	return launch.ambientExtensions === false && !launch.extensionPaths.length
+		&& isReadonlyChildSessionReporting(launch)
+		&& (!launch.hooks.length || (launch.storage.kind === "file" && isReadonlyChildHookProfile(launch.hooks, r)))
+		&& launch.tools !== undefined && launch.tools.every((tool) => tool === "read" || tool === "ls")
+		&& !r.toolBudget && !r.permissions && !r.childWatchdog && !r.watchdogStatus && !r.structuredOutput
+		&& !r.waitTool.enabled && !r.fanoutChild && !r.fast && !r.nestedRoute && !r.nestedParent && !r.runFanoutBudget
+		&& !r.supervisorChannelDir && !r.mcpDirectTools?.length;
+}
+
+export interface ReadonlyEvidenceObserver {
+	start(): void;
+	settled(): void;
+	invalidate(): void;
+	beforeShutdown(): void;
+	finish(child: ChildSession): void;
+}
+
+/** Called only on the explicit opt-in path, before SessionManager.open can permissively repair input. */
+export function prepareReadonlySessionEvidence(launch: ChildSessionLaunch): { loadingHooks(enabled: boolean): void; beforeOpen(): void; opened(manager: AgentSession["sessionManager"]): void; observe(pi: PiCodingAgentModule, runtime: Runtime, session: AgentSession): ReadonlyEvidenceObserver | undefined } | undefined {
+	if (!requested.has(launch)) return undefined;
+	const expected = requested.get(launch);
+	requested.delete(launch);
+	const deny = (): undefined => {
+		if (expected) throw new Error("Unsupported read-only continuation session");
+		return undefined;
+	};
+	const checkExpected = (): void => {
+		if (expected && (launch.storage.kind !== "file" || resolve(launch.storage.sessionFile) !== expected.sessionFile || !validateReadonlySessionCheckpoint(expected))) throw new Error("Read-only continuation checkpoint changed");
+	};
+	checkExpected();
+	if (!eligibleLaunch(launch) || launch.storage.kind !== "file") return deny();
+	const file = resolve(launch.storage.sessionFile);
+	// Only an initially absent *assigned exact file* may use SDK initialization.
+	// Empty files, dangling symlinks, inaccessible and corrupt inputs are not fresh.
+	let fresh = !expected && absent(file);
+	let initialHeader: SessionHeader | undefined;
+	try { if (!fresh) initialHeader = readHistory(file).header; }
+	catch { return deny(); }
+	const beforeOpen = (): void => {
+		checkExpected();
+		if (fresh) fresh = absent(file);
+	};
+	const opened = (manager: AgentSession["sessionManager"]): void => {
+		if (fresh && manager.getSessionFile() === file && manager.getEntries().length === 0 && manager.getLeafId() === null) {
+			// Capture the real SDK-generated identity immediately after open, before hooks.
+			initialHeader = JSON.parse(JSON.stringify(manager.getHeader()));
+		}
+	};
+	const observe = (pi: PiCodingAgentModule, runtime: Runtime, session: AgentSession): ReadonlyEvidenceObserver | undefined => {
+		const drainSettled = captureReadonlyChildDrain(launch.hooks);
+		// A deliberately tested capability floor, not an attestation of installed code origin.
+		if (!initialHeader || pi.VERSION !== "0.85.1" || !session.model || !session.agent.streamFunction) return deny();
+		const header = initialHeader;
+		const model = { ...session.model };
+		const provider = runtime.getProvider(model.provider);
+		if (expected && provider !== providers.get(expected)) return deny();
+		// Coverage is namespace/API plus the observed POST topology below, not builtin provider origin.
+		const supported = (m: Model): boolean => m.provider === "baseten" && m.api === "openai-completions"
+			&& runtime.getProvider(m.provider) === provider
+			&& !runtime.getRegisteredNativeProvider(m.provider) && !runtime.getRegisteredProviderConfig(m.provider);
+		const allowed = launch.tools!.filter((name) => !launch.excludeTools?.includes(name)).sort();
+		const toolsMatch = (): boolean => {
+			const tools = session.getAllTools();
+			return isDeepStrictEqual(session.getActiveToolNames().sort(), allowed)
+				&& isDeepStrictEqual(tools.map((tool) => tool.name).sort(), allowed)
+				&& tools.every((tool) => tool.sourceInfo?.source === "builtin");
+		};
+		const idle = (): boolean => session.isIdle && !session.isRetrying && !session.agent.hasQueuedMessages()
+			&& session.agent.state.pendingToolCalls.size === 0 && !session.hasPendingBashMessages;
+		const continuity = (): boolean => eligibleLaunch(launch) && toolsMatch() && session.model !== undefined
+			&& session.model.id === model.id && session.model.provider === model.provider && session.model.api === model.api && supported(session.model);
+		const history = () => {
+			const disk = readHistory(file);
+			const manager = session.sessionManager;
+			const leaf = manager.getLeafId();
+			if (session.sessionFile !== file || session.sessionId !== header.id || !leaf || leaf !== disk.entries.at(-1)?.id
+				|| !isDeepStrictEqual(disk.header, header) || !sameStored(disk.header, manager.getHeader())
+				|| !sameStored(disk.entries, manager.getEntries())) throw new Error("Session checkpoint mismatch");
+			// The disk chain and live entries already agree; use the SDK's raw branch walk.
+			const messages = activeMessages(manager.getBranch());
+			if (!sameStored(messages, session.messages)) throw new Error("Incomplete active context");
+			return { ...disk, messages, leaf, completed: completedResults(messages) };
+		};
+		const startingHistory = () => {
+			// SDK defers persistence until its first assistant response. This exception
+			// is for the empty source baseline only; settlement always reads strict disk history.
+			if (fresh && absent(file)) {
+				const manager = session.sessionManager;
+				if (session.sessionFile !== file || session.sessionId !== header.id || !sameStored(header, manager.getHeader())
+					|| session.messages.length
+					|| manager.getEntries().some((entry) => !["model_change", "thinking_level_change", "session_info", "label"].includes(entry.type))) throw new Error("Fresh session initialization changed");
+				return { messages: [] as AgentSession["messages"], completed: 0 };
+			}
+			return history();
+		};
+		if (!provider || !eligibleLaunch(launch) || !supported(model) || !toolsMatch() || !idle()) return deny();
+		try {
+			const restored = startingHistory();
+			if (expected && (model.provider !== expected.provider || JSON.stringify(restored.messages) !== expected.contextJson)) throw new Error("Restored continuation context changed");
+		} catch (error) {
+			if (expected) throw error;
+			return undefined;
+		}
+		let invalid = false;
+		let phase: "new" | "running" | "settled" = "new";
+		let owner: ChildSession | undefined;
+		let baseline = 0;
+		let before: AgentSession["messages"] = [];
+		let inFlight = 0;
+		type Invocation = { status?: number; pending: number; ambiguous: boolean; result?: Awaited<ReturnType<Awaited<ReturnType<typeof session.agent.streamFunction>>["result"]>> };
+		let latest: Invocation | undefined;
+		const original = session.agent.streamFunction;
+		const wrapped: typeof original = async (m, context, options) => {
+			const invocation: Invocation = { pending: 0, ambiguous: false };
+			latest = invocation;
+			if (inFlight++ || phase !== "running" || !eligibleLaunch(launch) || !supported(m) || m.id !== model.id || !toolsMatch()) invalid = true;
+			if (expected && (!continuity() || session.agent.streamFunction !== wrapped)) invalid = true;
+			// The repository's older agent-core types omit this documented 0.85.1 request option.
+			const transport = (options as (typeof options & { fetch?: typeof fetch }))?.fetch ?? globalThis.fetch;
+			const observedFetch: typeof fetch = async (...args) => {
+				invocation.status = undefined; // Starting even a rejected retry invalidates any earlier 429.
+				if (invocation.pending++ || invocation.result) invocation.ambiguous = true;
+				try {
+					try {
+						const [input, init] = args;
+						const url = new URL(input instanceof Request ? input.url : String(input));
+						// Only the tested completions POST topology. Radius /messages and auxiliary requests deny.
+						if (init?.method !== "POST" || !url.pathname.endsWith("/chat/completions") || typeof init.body !== "string") invocation.ambiguous = true;
+					} catch { invocation.ambiguous = true; }
+					const response = await transport(...args);
+					invocation.status = response.status;
+					return response;
+				} catch (error) {
+					invocation.status = undefined;
+					throw error;
+				} finally { invocation.pending--; }
+			};
+			try {
+				// Guarded continuations must veto known changes before entering configured SDK dispatch.
+				if (expected && invalid) throw new Error("Read-only continuation changed before dispatch");
+				const stream = await original.call(session.agent, m, context, { ...options, fetch: observedFetch });
+				// Observe result without consuming or replacing the event stream.
+				void stream.result().then((result) => {
+					invocation.result = result;
+					inFlight--;
+				}, () => { invalid = true; inFlight--; });
+				return stream;
+			} catch (error) { invalid = true; inFlight--; throw error; }
+		};
+		session.agent.streamFunction = wrapped;
+		return {
+			start() {
+				if (owner) receipts.delete(owner);
+				if (phase !== "new" || !idle()) invalid = true;
+				if (expected && (!continuity() || session.agent.streamFunction !== wrapped)) invalid = true;
+				phase = "running";
+				latest = undefined;
+				try {
+					const h = startingHistory(); baseline = h.completed; before = h.messages;
+					if (expected && JSON.stringify(h.messages) !== expected.contextJson) invalid = true;
+				} catch { invalid = true; }
+				if (expected && invalid) throw new Error("Read-only continuation changed before prompt");
+			},
+			settled() { phase = "settled"; },
+			invalidate() { invalid = true; if (owner) receipts.delete(owner); },
+			beforeShutdown() {
+				// Only the identity-certified prompt runtime may finalize owned acknowledgements.
+				if (!launch.hooks.length || !continuity()) invalid = true;
+			},
+			finish(child) {
+				owner = child;
+				if (!drainSettled()) return;
+				if (invalid || child.detached || child.shutDown || phase !== "settled" || inFlight || !eligibleLaunch(launch) || !idle() || !supported(model) || !toolsMatch() || session.agent.streamFunction !== wrapped
+					|| session.model?.id !== model.id || session.model.provider !== model.provider || session.model.api !== model.api) return;
+				const invocation = latest;
+				const terminal = invocation?.result;
+				if (!invocation || invocation.ambiguous || invocation.pending || invocation.status !== 429 || terminal?.stopReason !== "error"
+					|| terminal.content.length || terminal.provider !== model.provider || terminal.model !== model.id || terminal.api !== model.api) return;
+				try {
+					const h = history();
+					if (h.completed <= baseline || !isDeepStrictEqual(h.messages.slice(0, before.length), before) || !sameStored(h.messages.at(-1), terminal)) return;
+					const receipt: SettledReadonlyEvidence = Object.freeze({ sessionFile: file, sessionId: session.sessionId, leafId: h.leaf,
+						provider: model.provider, model: model.id, api: model.api, status: 429, contextJson: JSON.stringify(h.messages),
+						completedToolResults: h.completed, fileDigest: digest(h.bytes) });
+					providers.set(receipt, provider);
+					receipts.set(child, receipt);
+				} catch { /* Strict checkpoint failures only deny evidence; never repair storage. */ }
+			},
+		};
+	};
+	return { beforeOpen, opened, observe, loadingHooks: (enabled) => observeReadonlyChildHookDrain(launch.hooks, enabled, file) };
+}