pi-subagents 0.65.1 → 0.66.0

package/src/runs/background/notify.ts

@@ -6,6 +6,7 @@
  * observation channel, not a delivery acknowledgement.
  */
 
+import { debuglog } from "node:util";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.ts";
 import {
@@ -34,6 +35,7 @@ export interface SubagentNotifyChildOutput {
 export type SubagentNotifyWatchdogBlocker = Pick<ChildWatchdogWarningSummary, "summary" | "addressed" | "stalemate"> & { agent: string };
 
 export interface SubagentNotifyDetails {
+	workflowReceiptPath?: string;
 	agent: string;
 	status: "completed" | "failed" | "paused" | "stopped";
 	source?: "async" | "foreground";
@@ -189,11 +191,17 @@ function structuredOutputText(value: unknown): string | undefined {
 	}
 }
 
+function isDegenerateOutput(text: string): boolean {
+	return !text.trim() || text.trim() === "</think>";
+}
+
 function childInlinePreview(child: CompletionChild): { preview?: string; truncated?: boolean; unavailableReason?: string } {
 	const output = typeof child.output === "string" ? child.output : "";
 	const outputReference = childSavedOutputPath(child);
 	const referenceOnly = Boolean(outputReference && output.trim().startsWith("Output saved to:"));
-	const raw = child.outputState === "absent" || referenceOnly ? structuredOutputText(child.structuredOutput) : output || structuredOutputText(child.structuredOutput);
+	const raw = child.outputState === "absent" || referenceOnly
+		? structuredOutputText(child.structuredOutput)
+		: isDegenerateOutput(output) ? structuredOutputText(child.structuredOutput) ?? output : output;
 	if (!raw?.trim()) {
 		return { unavailableReason: referenceOnly ? "saved output is file-only" : "no safe inline output" };
 	}
@@ -283,6 +291,7 @@ export function formatSingleCompletion(details: SubagentNotifyDetails): string {
 		: undefined;
 	return [
 		`${taskKind} ${details.status}: **${details.agent}**${details.taskInfo ?? ""}`,
+		details.workflowReceiptPath ? `Workflow receipt: ${details.workflowReceiptPath}` : undefined,
 		"",
 		scheduleLine,
 		scheduleLine ? "" : undefined,
@@ -303,7 +312,11 @@ export function parseSubagentNotifyContent(content: string): SubagentNotifyDetai
 	const lines = content.split("\n");
 	const match = (lines[0] ?? "").match(/^(Background task|Detached foreground task) (completed|failed|paused|stopped): \*\*(.+?)\*\*(?:\s+(\([^)]*\)))?$/);
 	if (!match) return undefined;
-	let body = lines.slice(2);
+	// Only the header slot before the blank separator can carry a receipt.
+	// Identical lines anywhere in model output remain preview text.
+	const receiptHeader = lines[1]?.startsWith("Workflow receipt: ") && lines[2] === "";
+	const workflowReceiptPath = receiptHeader ? lines[1]!.slice("Workflow receipt: ".length) : undefined;
+	let body = lines.slice(receiptHeader ? 3 : 2);
 	// Restore the schedule origin so a re-rendered notice keeps its attribution and
 	// does not fold the line into the result preview.
 	const scheduleMatch = (body[0] ?? "").match(/^Scheduled run from \*\*(.+?)\*\* \(schedule (.+?)\)\.$/);
@@ -359,6 +372,7 @@ export function parseSubagentNotifyContent(content: string): SubagentNotifyDetai
 		...(match[1] === "Detached foreground task" ? { source: "foreground" as const } : {}),
 		...(match[4] ? { taskInfo: match[4] } : {}),
 		...(parsedScheduleOrigin ? { scheduleOrigin: parsedScheduleOrigin } : {}),
+		...(workflowReceiptPath ? { workflowReceiptPath } : {}),
 		resultPreview,
 		...(handoffPath ? { handoffPath } : {}),
 		...(workflowRunId ? { workflowRunId } : {}),
@@ -377,6 +391,7 @@ export function formatGroupedCompletion(details: SubagentNotifyDetails[]): strin
 		if (!detail) continue;
 		const sessionLine = formatSessionLine(detail);
 		blocks.push(`${index + 1}. ${detail.agent}${detail.taskInfo ?? ""}${detail.scheduleOrigin ? ` — scheduled run from ${detail.scheduleOrigin.name ?? detail.scheduleOrigin.id} (schedule ${detail.scheduleOrigin.id})` : ""}`);
+		if (detail.workflowReceiptPath) blocks.push(`Workflow receipt: ${detail.workflowReceiptPath}`);
 		blocks.push(formatResultPreview(detail));
 		blocks.push(...formatWatchdogBlockerLines(detail));
 		if (detail.handoffPath) blocks.push(`Parallel handoff: ${detail.handoffPath}`);
@@ -387,7 +402,31 @@ export function formatGroupedCompletion(details: SubagentNotifyDetails[]): strin
 	return blocks.join("\n").trimEnd();
 }
 
+const notificationDebug = debuglog("pi-subagents-notify");
+type TraceIdentity = Pick<CompletionNotification, "id" | "runId" | "source">;
+type NotificationReason = "disposed" | "missing_session" | "foreground_session_mismatch" | "not_owned"
+	| "intercom_delivered" | "deduped_ttl" | "deduped_pending" | "batch_deferred"
+	| "emit_foreground_session_mismatch" | "emit_not_owned" | "send_accepted" | "send_failed" | "dispose_pending";
+
+// Slice before sanitizing: diagnostic work and each identity are bounded even for
+// malformed result metadata. Never include task/output, paths, or error bodies.
+function traceIdentity(result: TraceIdentity): TraceIdentity {
+	const identity = (value: unknown) => typeof value === "string"
+		? value.slice(0, 128).replace(/[^a-zA-Z0-9_.:-]/g, "_") : undefined;
+	return { id: identity(result.id), runId: identity(result.runId), source: result.source === "foreground" ? "foreground" : "async" };
+}
+
+function traceNotification(reason: NotificationReason, result?: TraceIdentity): void {
+	if (!notificationDebug.enabled) return;
+	try {
+		notificationDebug("%s", JSON.stringify({ reason, ...(result ? traceIdentity(result) : {}) }));
+	} catch {
+		// Diagnostics must never change delivery acknowledgement.
+	}
+}
+
 interface PendingCompletion {
+	trace?: TraceIdentity;
 	key: string;
 	details: SubagentNotifyDetails;
 	sessionId: string;
@@ -448,6 +487,10 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		? result.parallelHandoff as { path?: unknown }
 		: undefined;
 	const handoffPath = typeof parallelHandoff?.path === "string" ? parallelHandoff.path : undefined;
+	const receipt = result.workflowReceipt;
+	const receiptPath = receipt && typeof receipt === "object" && !Array.isArray(receipt)
+		? (receipt as Record<string, unknown>).path : undefined;
+	const workflowReceiptPath = typeof receiptPath === "string" && receiptPath ? receiptPath : undefined;
 	const rawRunId = typeof result.runId === "string" ? result.runId : typeof result.id === "string" ? result.id : undefined;
 	const workflowRunId = (result.mode === "workflow" || agent === "workflow") && rawRunId ? rawRunId : undefined;
 	const directChild = !workflowRunId && result.results?.length === 1 ? result.results[0]! : undefined;
@@ -456,10 +499,17 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		: undefined;
 	const directSummary = summary.trim();
 	const directAgent = typeof directChild?.agent === "string" ? directChild.agent : agent;
+	const directSummaryBody = directAgent && summary.trimStart().startsWith(`${directAgent}:\n`)
+		? summary.trimStart().slice(directAgent.length + 2)
+		: directSummary;
+	const directDegenerateSummary = directChild
+		&& isDegenerateOutput(typeof directChild.output === "string" ? directChild.output : "")
+		&& isDegenerateOutput(directSummaryBody)
+		&& structuredOutputText(directChild.structuredOutput) !== undefined;
 	const directNoOutputSummary = directChild && (!directSummary
 		|| directSummary === "(no output)"
 		|| (directAgent && directSummary === `${directAgent}:\n(no output)`));
-	const resultPreview = directStructuredPreview && directNoOutputSummary
+	const resultPreview = directStructuredPreview && (directNoOutputSummary || directDegenerateSummary)
 		? `Structured output:\n${directStructuredPreview}`
 		: summary;
 	const childRuns = result.results?.flatMap((child) => {
@@ -517,6 +567,7 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		agent,
 		status,
 		...(scheduleOrigin ? { scheduleOrigin } : {}),
+		...(workflowReceiptPath ? { workflowReceiptPath } : {}),
 		...(result.source ? { source: result.source } : {}),
 		...(taskInfo ? { taskInfo } : {}),
 		resultPreview,
@@ -548,8 +599,9 @@ export default function registerSubagentNotify(
 			&& typeof completionOwnerId === "string"
 			&& completionOwnerId === state.completionOwnerId);
 
-	const settle = (items: PendingCompletion[], accepted: boolean) => {
+	const settle = (items: PendingCompletion[], accepted: boolean, reason?: NotificationReason) => {
 		for (const item of items) {
+			if (reason) traceNotification(reason, item.trace);
 			pending.delete(item.key);
 			if (accepted) markSeenWithTtl(seen, item.key, now(), ttlMs);
 			item.resolve(accepted);
@@ -562,10 +614,12 @@ export default function registerSubagentNotify(
 			const owned = item.details.source === "foreground"
 				? item.sessionId === state.currentSessionId
 				: ownsResult(item.sessionId, item.completionOwnerId);
+			if (!owned) traceNotification(item.details.source === "foreground" ? "emit_foreground_session_mismatch" : "emit_not_owned", item.trace);
 			(owned ? accepted : rejected).push(item);
 		}
 		settle(rejected, false);
-		settle(accepted, sendCompletion(pi, accepted));
+		const sent = sendCompletion(pi, accepted);
+		settle(accepted, sent, sent ? "send_accepted" : "send_failed");
 	};
 	const getBatcher = (result: CompletionNotification) => {
 		const key = completionBatchKey(result);
@@ -583,17 +637,35 @@ export default function registerSubagentNotify(
 	};
 
 	const deliver = (result: CompletionNotification): Promise<boolean> => {
-		if (disposed || typeof result.sessionId !== "string") return Promise.resolve(false);
+		if (disposed || typeof result.sessionId !== "string") {
+			traceNotification(disposed ? "disposed" : "missing_session", result);
+			return Promise.resolve(false);
+		}
 		if (result.source === "foreground") {
-			if (result.sessionId !== state.currentSessionId) return Promise.resolve(false);
-		} else if (!ownsResult(result.sessionId, result.completionOwnerId)) return Promise.resolve(false);
-		if (result.intercomDelivered === true) return Promise.resolve(true);
+			if (result.sessionId !== state.currentSessionId) {
+				traceNotification("foreground_session_mismatch", result);
+				return Promise.resolve(false);
+			}
+		} else if (!ownsResult(result.sessionId, result.completionOwnerId)) {
+			traceNotification("not_owned", result);
+			return Promise.resolve(false);
+		}
+		if (result.intercomDelivered === true) {
+			traceNotification("intercom_delivered", result);
+			return Promise.resolve(true);
+		}
 		const key = buildCompletionKey(result, "notify");
 		const seenAt = seen.get(key);
-		if (seenAt !== undefined && now() - seenAt <= ttlMs) return Promise.resolve(true);
+		if (seenAt !== undefined && now() - seenAt <= ttlMs) {
+			traceNotification("deduped_ttl", result);
+			return Promise.resolve(true);
+		}
 		if (seenAt !== undefined) seen.delete(key);
 		const inFlight = pending.get(key);
-		if (inFlight) return inFlight;
+		if (inFlight) {
+			traceNotification("deduped_pending", result);
+			return inFlight;
+		}
 		const details = buildCompletionDetails(result);
 		let resolve!: (accepted: boolean) => void;
 		const completion = new Promise<boolean>((settleCompletion) => { resolve = settleCompletion; });
@@ -606,6 +678,7 @@ export default function registerSubagentNotify(
 			triggerTurn: result.triggerTurn !== false,
 			resolve,
 		};
+		if (notificationDebug.enabled) item.trace = traceIdentity(result);
 		if (details.source === "foreground") {
 			emit([item]);
 			return completion;
@@ -616,6 +689,7 @@ export default function registerSubagentNotify(
 			emit([item]);
 			return completion;
 		}
+		if (batchConfig.enabled) traceNotification("batch_deferred", item.trace);
 		batcher.push(item);
 		return completion;
 	};
@@ -633,7 +707,7 @@ export default function registerSubagentNotify(
 		dispose() {
 			if (disposed) return;
 			disposed = true;
-			for (const batcher of batchers.values()) settle(batcher.dispose(), false);
+			for (const batcher of batchers.values()) settle(batcher.dispose(), false, "dispose_pending");
 			batchers.clear();
 			for (const unsubscribe of [unsubscribeAsync, unsubscribeForeground]) {
 				try {

package/src/runs/background/owned-process-tree.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import type { ProcessTreeTerminalV1 } from "../../shared/types.ts";
+import type { ProcessTreeTerminal } from "../../shared/types.ts";
 
 const DEFAULT_TERM_GRACE_MS = 3000;
 const DEFAULT_KILL_VERIFY_MS = 1000;
@@ -52,25 +52,25 @@ async function waitUntilGroupTerminal(
 	}
 }
 
-function observed(processGroupId: number): ProcessTreeTerminalV1 {
+function observed(processGroupId: number): ProcessTreeTerminal {
 	return { state: "observed", mechanism: "posix-process-group", processGroupId, verifiedAt: Date.now() };
 }
 
 /** Owns one writer process group and arbitrates its cleanup exactly once. */
 export interface OwnedProcessTreeController {
-	terminate(): Promise<ProcessTreeTerminalV1>;
-	finishAfterWriterClose(): Promise<ProcessTreeTerminalV1>;
+	terminate(): Promise<ProcessTreeTerminal>;
+	finishAfterWriterClose(): Promise<ProcessTreeTerminal>;
 }
 
 export function createOwnedProcessTreeController(
 	pid: number,
 	options: { termGraceMs?: number; killVerifyMs?: number } = {},
 ): OwnedProcessTreeController {
-	let termination: Promise<ProcessTreeTerminalV1> | undefined;
+	let termination: Promise<ProcessTreeTerminal> | undefined;
 	const posixGroupOwned = process.platform !== "win32";
 	const target = posixGroupOwned ? -pid : pid;
 
-	const terminate = (): Promise<ProcessTreeTerminalV1> => {
+	const terminate = (): Promise<ProcessTreeTerminal> => {
 		if (termination) return termination;
 		termination = (async () => {
 			if (!posixGroupOwned) {

package/src/runs/background/process-terminal.ts

@@ -4,10 +4,10 @@ import { writeAtomicJson, writePrivateAtomicJson } from "../../shared/atomic-jso
 import {
 	SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
 	type AsyncStatus,
-	type CanonicalSessionTerminalV1,
-	type ProcessInstanceExitV1,
+	type CanonicalSessionTerminal,
+	type ProcessInstanceExit,
 	type ProcessTerminalReason,
-	type ProcessTerminalV1,
+	type ProcessTerminal,
 } from "../../shared/types.ts";
 import { canonicalSessionId, inspectSessionLease } from "../shared/session-lease.ts";
 import { releaseActiveRunIndex } from "./active-run-index.ts";
@@ -16,7 +16,7 @@ export interface ProcessTerminalCandidate {
 	version: 1;
 	runId: string;
 	runnerProcessInstanceId: string;
-	writers: Record<string, ProcessInstanceExitV1[]>;
+	writers: Record<string, ProcessInstanceExit[]>;
 	expectedWriters?: Record<string, number>;
 	sessionFile?: string;
 	revivalLeaseToken?: string;
@@ -34,7 +34,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
-function validProcessInstance(value: unknown, kind?: "runner" | "pi-writer"): value is ProcessInstanceExitV1 {
+function validProcessInstance(value: unknown, kind?: "runner" | "pi-writer"): value is ProcessInstanceExit {
 	if (!isRecord(value)) return false;
 	if (typeof value.processInstanceId !== "string" || value.processInstanceId.length === 0) return false;
 	if (kind ? value.kind !== kind : (value.kind !== "runner" && value.kind !== "pi-writer")) return false;
@@ -56,7 +56,7 @@ function validProcessInstance(value: unknown, kind?: "runner" | "pi-writer"): va
 		&& (value.processTree.diagnostic === undefined || typeof value.processTree.diagnostic === "string");
 }
 
-function validInstance(value: unknown): value is ProcessInstanceExitV1 {
+function validInstance(value: unknown): value is ProcessInstanceExit {
 	return validProcessInstance(value, "pi-writer");
 }
 
@@ -78,7 +78,7 @@ export function readProcessTerminalCandidate(asyncDir: string): ProcessTerminalC
 		if (!isRecord(raw) || raw.version !== 1 || typeof raw.runId !== "string" || typeof raw.runnerProcessInstanceId !== "string" || !isRecord(raw.writers)) {
 			throw new Error(`Invalid process-terminal candidate in '${asyncDir}'.`);
 		}
-		const writers: Record<string, ProcessInstanceExitV1[]> = {};
+		const writers: Record<string, ProcessInstanceExit[]> = {};
 		for (const [index, entries] of Object.entries(raw.writers)) {
 			if (!Array.isArray(entries) || !entries.every(validInstance)) throw new Error(`Invalid writer process records for child '${index}'.`);
 			writers[index] = entries;
@@ -137,7 +137,7 @@ export function markProcessTerminalCandidateLeaseRelease(asyncDir: string, token
 	writeProcessTerminalCandidate(asyncDir, { ...candidate, revivalLeaseReleaseAcknowledged: acknowledged });
 }
 
-function unknownProof(runId: string, runnerProcessInstanceId: string, reason: ProcessTerminalReason, diagnostic?: string): ProcessTerminalV1 {
+function unknownProof(runId: string, runnerProcessInstanceId: string, reason: ProcessTerminalReason, diagnostic?: string): ProcessTerminal {
 	return { version: 1, state: "unknown", runId, runnerProcessInstanceId, reason, ...(diagnostic ? { diagnostic } : {}) };
 }
 
@@ -147,7 +147,7 @@ function resumeDisposition(state: string | undefined, sessionFile: string | unde
 	return sessionFile && fs.existsSync(sessionFile) ? "resumable" : "unavailable";
 }
 
-function sessionProjection(candidate: ProcessTerminalCandidate, lease: ReturnType<typeof inspectSessionLease>): CanonicalSessionTerminalV1 | undefined {
+function sessionProjection(candidate: ProcessTerminalCandidate, lease: ReturnType<typeof inspectSessionLease>): CanonicalSessionTerminal | undefined {
 	if (!candidate.sessionFile || lease.state !== "free") return undefined;
 	if (candidate.revivalLeaseToken && candidate.revivalLeaseReleaseAcknowledged !== true) return undefined;
 	return {
@@ -158,7 +158,7 @@ function sessionProjection(candidate: ProcessTerminalCandidate, lease: ReturnTyp
 	};
 }
 
-function validateProof(raw: unknown, asyncDir: string, fallback?: { runId?: string; runnerProcessInstanceId?: string }): raw is ProcessTerminalV1 {
+function validateProof(raw: unknown, asyncDir: string, fallback?: { runId?: string; runnerProcessInstanceId?: string }): raw is ProcessTerminal {
 	if (!isRecord(raw) || raw.version !== 1 || !["pending", "observed", "unknown", "not-started"].includes(String(raw.state)) || typeof raw.runId !== "string" || !raw.runId || typeof raw.runnerProcessInstanceId !== "string" || !raw.runnerProcessInstanceId) {
 		throw new Error(`Invalid process-terminal proof in '${asyncDir}'.`);
 	}
@@ -177,21 +177,21 @@ function validateProof(raw: unknown, asyncDir: string, fallback?: { runId?: stri
 	return true;
 }
 
-export function sanitizeProcessTerminal(value: unknown, fallback: { runId?: string; runnerProcessInstanceId?: string }, label = "status"): ProcessTerminalV1 | undefined {
+export function sanitizeProcessTerminal(value: unknown, fallback: { runId?: string; runnerProcessInstanceId?: string }, label = "status"): ProcessTerminal | undefined {
 	if (value === undefined) return undefined;
 	try {
 		validateProof(value, label, fallback);
-		return value as ProcessTerminalV1;
+		return value as ProcessTerminal;
 	} catch (error) {
 		return unknownProof(fallback.runId ?? label, fallback.runnerProcessInstanceId ?? "unknown", "proof-write-failed", errorMessage(error));
 	}
 }
 
-export function readProcessTerminal(asyncDir: string, fallback?: { runId?: string; runnerProcessInstanceId?: string }): ProcessTerminalV1 | undefined {
+export function readProcessTerminal(asyncDir: string, fallback?: { runId?: string; runnerProcessInstanceId?: string }): ProcessTerminal | undefined {
 	try {
 		const raw = JSON.parse(fs.readFileSync(processTerminalPath(asyncDir), "utf-8")) as unknown;
 		validateProof(raw, asyncDir, fallback);
-		return raw as ProcessTerminalV1;
+		return raw as ProcessTerminal;
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
 		return unknownProof(fallback?.runId ?? path.basename(asyncDir), fallback?.runnerProcessInstanceId ?? "unknown", "proof-write-failed", errorMessage(error));
@@ -199,12 +199,12 @@ export function readProcessTerminal(asyncDir: string, fallback?: { runId?: strin
 }
 
 function stepProcessTerminalProof(
-	proof: ProcessTerminalV1,
+	proof: ProcessTerminal,
 	childIndex: number,
-	state: ProcessTerminalV1["state"],
-	records: ProcessInstanceExitV1[],
-	resumeDispositionValue: ProcessTerminalV1["resumeDisposition"],
-): ProcessTerminalV1 {
+	state: ProcessTerminal["state"],
+	records: ProcessInstanceExit[],
+	resumeDispositionValue: ProcessTerminal["resumeDisposition"],
+): ProcessTerminal {
 	const base = {
 		version: 1 as const,
 		runId: proof.runId,
@@ -221,7 +221,7 @@ function stepProcessTerminalProof(
 	return { ...base, state };
 }
 
-function overlayStatus(asyncDir: string, proof: ProcessTerminalV1, candidate?: ProcessTerminalCandidate): void {
+function overlayStatus(asyncDir: string, proof: ProcessTerminal, candidate?: ProcessTerminalCandidate): void {
 	const statusPath = path.join(asyncDir, "status.json");
 	try {
 		const status = JSON.parse(fs.readFileSync(statusPath, "utf-8")) as AsyncStatus;
@@ -244,13 +244,13 @@ export function finalizeProcessTerminal(
 	asyncDir: string,
 	runId: string,
 	runnerClose: RunnerCloseObservation,
-): ProcessTerminalV1 {
+): ProcessTerminal {
 	const existing = readProcessTerminal(asyncDir, { runId, runnerProcessInstanceId: runnerClose.processInstanceId });
 	if (existing && fs.existsSync(processTerminalPath(asyncDir))) {
 		if (existing.state === "observed" && existing.runId === runId && existing.runnerProcessInstanceId === runnerClose.processInstanceId) return existing;
 		if (existing.state === "unknown") return existing;
 	}
-	let proof: ProcessTerminalV1;
+	let proof: ProcessTerminal;
 	let candidateForOverlay: ProcessTerminalCandidate | undefined;
 	try {
 		const candidate = readProcessTerminalCandidate(asyncDir);
@@ -279,7 +279,7 @@ export function finalizeProcessTerminal(
 			} else if (allWriters.some((writer) => writer.kind === "pi-writer" && writer.processTree.state !== "observed")) {
 				proof = unknownProof(runId, runnerClose.processInstanceId, "process-tree-unverified");
 			} else {
-				const runner: ProcessInstanceExitV1 = { kind: "runner", ...runnerClose };
+				const runner: ProcessInstanceExit = { kind: "runner", ...runnerClose };
 				const canonicalSession = session && sessionProjection(candidate, session);
 				proof = {
 					version: 1,

package/src/runs/background/run-child-session.ts

@@ -8,7 +8,7 @@
 import type { Message } from "@earendil-works/pi-ai";
 import type { ChildTranscriptWriter } from "../../shared/child-transcript.ts";
 import { extractTextFromContent, extractToolArgsPreview, getFinalOutput, hasEmptyTerminalAssistantResponse } from "../../shared/utils.ts";
-import type { EffectsProjection, RuntimeAcknowledgedChildExtensionsV1, SubagentOutputState, ToolBudgetState, Usage } from "../../shared/types.ts";
+import type { EffectsProjection, RuntimeAcknowledgedChildExtensions, SubagentOutputState, ToolBudgetState, Usage } from "../../shared/types.ts";
 import {
 	acceptChildWatchdogEvent,
 	applyChildWatchdogMessage,
@@ -22,9 +22,10 @@ import { projectChildLifecycle, type ChildLifecycleAction, type ChildLifecycleSt
 import { formatSubagentModelVerificationError } from "../shared/model-fallback.ts";
 import { isMutatingTool, resolveCurrentPath } from "../shared/long-running-guard.ts";
 import { effectiveToolTimeoutMs, formatToolTimeoutMessage, toolTimeoutCallKey } from "../shared/tool-timeout.ts";
-import type { InProcessChildLaunch } from "../shared/child-launch.ts";
+import { createReportedChildSessionInput, type InProcessChildLaunch } from "../shared/child-launch.ts";
 import { projectChildSessionEventForJson, type ChildSession, type ChildSessionEvent, type ChildSessionFactory } from "../shared/child-session.ts";
 import { formatSteerMessage } from "../shared/subagent-prompt-runtime.ts";
+import { getReadonlySessionEvidence, requestReadonlySessionEvidence, type SettledReadonlyEvidence } from "../shared/readonly-session-evidence.ts";
 import type { SteerDeliveryStatus, SteerRequest } from "./control-channel.ts";
 
 export interface ChildEventContext {
@@ -95,6 +96,16 @@ export interface RunChildSessionInput {
 	modelVerificationRegistry?: Array<{ provider: string; id: string; fullId: string }>;
 	modelResponseAliases?: Record<string, string[]>;
 	mutationTools?: readonly string[];
+	/** Internal guarded continuation handoff; never part of persisted results. */
+	readonlyContinuation?: { source: ChildSession; expected: SettledReadonlyEvidence; modelId: string };
+	collectReadonlyEvidence?: boolean;
+	canContinue?: () => boolean;
+}
+
+const settledChildren = new WeakMap<RunChildSessionResult, ChildSession>();
+export function getSettledReadonlyChild(result: RunChildSessionResult): ChildSession | undefined {
+	const child = settledChildren.get(result);
+	return child && getReadonlySessionEvidence(child) ? child : undefined;
 }
 
 export interface RunChildSessionResult {
@@ -123,7 +134,7 @@ export interface RunChildSessionResult {
 	toolBudget?: ToolBudgetState;
 	toolBudgetBlocked?: boolean;
 	structuredOutput?: unknown;
-	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensions;
 	abortRecoveryDiagnostic?: string;
 	effects?: EffectsProjection;
 }
@@ -474,6 +485,10 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
 					}
 				}
 				if (event.message.errorMessage) assistantError = event.message.errorMessage;
+				else if (hasToolCall && event.message.stopReason === "toolUse") {
+					// A recovered request can finish via a terminating tool, without a text stop.
+					assistantError = undefined;
+				}
 				const eventUsage = event.message.usage;
 				if (eventUsage) {
 					usage.turns++;
@@ -533,29 +548,33 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
 				: interrupted || (forcedDrainAfterFinalSuccess && !forcedDrainAfterEmptyTerminal)
 					? 0
 					: finalError || promptError !== undefined ? 1 : 0;
-			void closed.then(() => resolve(omitUndefined({
-				exitCode,
-				messages,
-				usage,
-				toolCount,
-				durationMs: Date.now() - startedAt,
-				model,
-				error: stopped ? stopMessage() : timedOut ? (error ?? timeoutMessage()) : interrupted || (forcedDrainAfterFinalSuccess && !forcedDrainAfterEmptyTerminal) ? undefined : finalError,
-				finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage() : error ?? timeoutMessage()) : finalOutput,
-				outputState: finalOutput.trim() ? "present" : "absent",
-				interrupted: interrupted || undefined,
-				timedOut: timedOut || undefined,
-				stopped: stopped || undefined,
-				observedMutationAttempt,
-				structuredOutputToolInvoked,
-				structuredOutputMessageStartIndex,
-				watchdog: childWatchdogState,
-				sessionFile: session?.sessionFile,
-				currentTool,
-				currentToolArgs,
-				currentPath,
-				afterCompactionSettlement: afterCompactionSettlement || undefined,
-			})));
+			void closed.then(() => {
+				const result: RunChildSessionResult = omitUndefined({
+					exitCode,
+					messages,
+					usage,
+					toolCount,
+					durationMs: Date.now() - startedAt,
+					model,
+					error: stopped ? stopMessage() : timedOut ? (error ?? timeoutMessage()) : interrupted || (forcedDrainAfterFinalSuccess && !forcedDrainAfterEmptyTerminal) ? undefined : finalError,
+					finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage() : error ?? timeoutMessage()) : finalOutput,
+					outputState: finalOutput.trim() ? "present" : "absent",
+					interrupted: interrupted || undefined,
+					timedOut: timedOut || undefined,
+					stopped: stopped || undefined,
+					observedMutationAttempt,
+					structuredOutputToolInvoked,
+					structuredOutputMessageStartIndex,
+					watchdog: childWatchdogState,
+					sessionFile: session?.sessionFile,
+					currentTool,
+					currentToolArgs,
+					currentPath,
+					afterCompactionSettlement: afterCompactionSettlement || undefined,
+				});
+				if (session && !forced && !forcedTermination && !interrupted && !timedOut && !stopped && getReadonlySessionEvidence(session)) settledChildren.set(result, session);
+				resolve(result);
+			});
 		};
 
 		input.registerInterrupt?.(() => {
@@ -575,17 +594,25 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
 
 		void (async () => {
 			try {
-				const created = await input.factory.create({
-					...input.launch.session,
-					onExtensionError: (extensionError) => {
-						input.transcriptWriter?.writeStderrLine(`Extension error (${extensionError.extensionPath}, ${extensionError.event}): ${extensionError.error instanceof Error ? extensionError.error.message : String(extensionError.error)}`);
-					},
-				});
+				const continuation = input.readonlyContinuation;
+				const checkContinuation = () => {
+					if (!continuation) return;
+					if (interrupted || timedOut || stopped || input.canContinue?.() !== true
+						|| (input.runDeadlineAt !== undefined && Date.now() >= input.runDeadlineAt)
+						|| getReadonlySessionEvidence(continuation.source) !== continuation.expected
+						|| continuation.source.detached || continuation.source.shutDown) throw new Error("Read-only continuation handoff vetoed");
+				};
+				checkContinuation();
+				const createInput = createReportedChildSessionInput(input.launch, input.transcriptWriter);
+				if (input.collectReadonlyEvidence || continuation) requestReadonlySessionEvidence(createInput, continuation?.expected);
+				const created = await input.factory.create(createInput);
 				if (settled) {
 					void created.dispose();
 					return;
 				}
 				session = created;
+				checkContinuation();
+				if (continuation && (created.modelId !== continuation.modelId || input.launch.capture.completionIntentContext?.()?.model?.api !== continuation.expected.api)) throw new Error("Read-only continuation model changed");
 				unsubscribe = created.subscribe(processEvent);
 				input.registerWatchdogStatus?.((event) => processEvent(event as unknown as ChildSessionEvent));
 				input.registerSteer?.(async (request) => {
@@ -602,6 +629,7 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
 						: { state: "delivered", deliveryStatus: "delivered", message: "Pi accepted the steering input." };
 				});
 				if (interrupted || timedOut || stopped) abortChild();
+				checkContinuation();
 				await created.prompt(input.prompt);
 				promptSettled = true;
 				settle(undefined);