pi-subagents 0.35.1 → 0.37.0

package/src/runs/background/notify.ts

@@ -1,28 +1,20 @@
 /**
- * Subagent completion notifications.
+ * Completion notification delivery.
  *
- * Successful (completed) async results are held briefly and emitted as a
- * single grouped message when sibling jobs finish within a short window (see
- * `completion-batcher.ts`). Failed and paused results bypass grouping and fire
- * immediately, flushing any held successes first, so failure and attention
- * signals are never delayed.
+ * Async result files call this notifier directly and are deleted only after
+ * `sendMessage()` accepts the notification. The event bus remains an
+ * observation channel, not a delivery acknowledgement.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "./completion-dedupe.ts";
+import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.ts";
 import {
 	type CompletionBatchConfig,
 	type CompletionBatcher,
 	createCompletionBatcher,
 	resolveCompletionBatchConfig,
 } from "./completion-batcher.ts";
-import { SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_FOREGROUND_COMPLETE_EVENT, type SubagentState } from "../../shared/types.ts";
-
-interface ChainStepResult {
-	agent: string;
-	output: string;
-	success: boolean;
-}
+import { SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_FOREGROUND_COMPLETE_EVENT, type ParallelHandoffReference, type SubagentState } from "../../shared/types.ts";
 
 export interface SubagentNotifyDetails {
 	agent: string;
@@ -33,27 +25,30 @@ export interface SubagentNotifyDetails {
 	durationMs?: number;
 	sessionLabel?: string;
 	sessionValue?: string;
+	handoffPath?: string;
 }
 
-interface SubagentResult {
-	id: string | null;
+export interface CompletionNotification {
+	[key: string]: unknown;
+	id?: string | null;
 	source?: "async" | "foreground";
-	agent: string | null;
-	success: boolean;
-	summary: string;
+	agent?: string | null;
+	success?: boolean;
+	summary?: string;
 	exitCode?: number;
 	state?: string;
-	timestamp: number;
+	timestamp?: number;
 	durationMs?: number;
 	cwd?: string;
 	sessionFile?: string;
 	shareUrl?: string;
 	gistUrl?: string;
 	shareError?: string;
-	results?: ChainStepResult[];
 	taskIndex?: number;
 	totalTasks?: number;
 	sessionId?: string | null;
+	triggerTurn?: boolean;
+	parallelHandoff?: ParallelHandoffReference;
 }
 
 interface NotifyTimerApi {
@@ -67,6 +62,11 @@ export interface RegisterSubagentNotifyOptions {
 	now?: () => number;
 }
 
+export interface CompletionNotifier {
+	deliver(result: CompletionNotification): Promise<boolean>;
+	dispose(): void;
+}
+
 function formatSessionLine(details: SubagentNotifyDetails): string | undefined {
 	if (!details.sessionValue) return undefined;
 	return details.sessionLabel ? `${details.sessionLabel}: ${details.sessionValue}` : details.sessionValue;
@@ -79,6 +79,8 @@ export function formatSingleCompletion(details: SubagentNotifyDetails): string {
 		`${taskKind} ${details.status}: **${details.agent}**${details.taskInfo ?? ""}`,
 		"",
 		details.resultPreview.trim() ? details.resultPreview : "(no output)",
+		details.handoffPath ? "" : undefined,
+		details.handoffPath ? `Parallel handoff: ${details.handoffPath}` : undefined,
 		sessionLine ? "" : undefined,
 		sessionLine,
 	]
@@ -99,7 +101,12 @@ export function parseSubagentNotifyContent(content: string): SubagentNotifyDetai
 		}
 	}
 	const sessionLine = sessionIndex >= 0 ? body[sessionIndex] : undefined;
-	const resultPreview = (sessionIndex >= 0 ? body.slice(0, sessionIndex) : body).join("\n").trim() || "(no output)";
+	const handoffIndex = body.findIndex((line) => line.startsWith("Parallel handoff: "));
+	const metadataIndexes = [sessionIndex, handoffIndex].filter((index) => index >= 0);
+	const firstMetadataIndex = metadataIndexes.length ? Math.min(...metadataIndexes) : body.length;
+	const resultEnd = firstMetadataIndex > 0 && body[firstMetadataIndex - 1]?.trim() === "" ? firstMetadataIndex - 1 : firstMetadataIndex;
+	const resultPreview = body.slice(0, resultEnd).join("\n").trim() || "(no output)";
+	const handoffPath = handoffIndex >= 0 ? body[handoffIndex]!.slice("Parallel handoff: ".length).trim() : undefined;
 	let sessionLabel: string | undefined;
 	let sessionValue: string | undefined;
 	if (sessionLine) {
@@ -113,6 +120,7 @@ export function parseSubagentNotifyContent(content: string): SubagentNotifyDetai
 		...(match[1] === "Detached foreground task" ? { source: "foreground" as const } : {}),
 		...(match[4] ? { taskInfo: match[4] } : {}),
 		resultPreview,
+		...(handoffPath ? { handoffPath } : {}),
 		...(sessionLabel && sessionValue ? { sessionLabel, sessionValue } : {}),
 	};
 }
@@ -126,35 +134,47 @@ export function formatGroupedCompletion(details: SubagentNotifyDetails[]): strin
 		const sessionLine = formatSessionLine(detail);
 		blocks.push(`${index + 1}. ${detail.agent}${detail.taskInfo ?? ""}`);
 		blocks.push(detail.resultPreview.trim() ? detail.resultPreview : "(no output)");
+		if (detail.handoffPath) blocks.push(`Parallel handoff: ${detail.handoffPath}`);
 		if (sessionLine) blocks.push(sessionLine);
 		blocks.push("");
 	}
 	return blocks.join("\n").trimEnd();
 }
 
-function sendCompletion(pi: Pick<ExtensionAPI, "sendMessage">, details: SubagentNotifyDetails[]): void {
-	if (details.length === 0) return;
-	const content = details.length === 1
-		? formatSingleCompletion(details[0]!)
-		: formatGroupedCompletion(details);
-	pi.sendMessage(
-		{
-			customType: "subagent-notify",
-			content,
-			display: true,
-		},
-		{ triggerTurn: true },
-	);
+interface PendingCompletion {
+	key: string;
+	details: SubagentNotifyDetails;
+	triggerTurn: boolean;
+	resolve(accepted: boolean): void;
+}
+
+function sendCompletion(pi: Pick<ExtensionAPI, "sendMessage">, items: PendingCompletion[]): boolean {
+	if (items.length === 0) return true;
+	const details = items.map((item) => item.details);
+	const content = details.length === 1 ? formatSingleCompletion(details[0]!) : formatGroupedCompletion(details);
+	try {
+		pi.sendMessage(
+			{
+				customType: "subagent-notify",
+				content,
+				display: true,
+			},
+			{ triggerTurn: items.some((item) => item.triggerTurn) },
+		);
+		return true;
+	} catch {
+		return false;
+	}
 }
 
-function completionBatchKey(result: SubagentResult): string {
+function completionBatchKey(result: CompletionNotification): string {
 	const sessionId = typeof result.sessionId === "string" ? result.sessionId.trim() : "";
 	if (sessionId) return `session:${sessionId}`;
 	const cwd = typeof result.cwd === "string" ? result.cwd.trim() : "";
 	return cwd ? `cwd:${cwd}` : "unknown";
 }
 
-export function buildCompletionDetails(result: SubagentResult): SubagentNotifyDetails {
+export function buildCompletionDetails(result: CompletionNotification): SubagentNotifyDetails {
 	const agent = result.agent ?? "unknown";
 	const summary = typeof result.summary === "string" ? result.summary : "";
 	const paused = !result.success && (
@@ -163,12 +183,15 @@ export function buildCompletionDetails(result: SubagentResult): SubagentNotifyDe
 		|| summary.startsWith("Paused after interrupt.")
 	);
 	const status = paused ? "paused" : result.success ? "completed" : "failed";
-
 	const taskInfo =
 		result.taskIndex !== undefined && result.totalTasks !== undefined
 			? ` (${result.taskIndex + 1}/${result.totalTasks})`
 			: undefined;
 
+	const parallelHandoff = result.parallelHandoff && typeof result.parallelHandoff === "object"
+		? result.parallelHandoff as { path?: unknown }
+		: undefined;
+	const handoffPath = typeof parallelHandoff?.path === "string" ? parallelHandoff.path : undefined;
 	const session =
 		result.shareUrl
 			? { label: "Session", value: result.shareUrl }
@@ -177,7 +200,6 @@ export function buildCompletionDetails(result: SubagentResult): SubagentNotifyDe
 				: result.sessionFile
 					? { label: "Session file", value: result.sessionFile }
 					: undefined;
-
 	return {
 		agent,
 		status,
@@ -185,6 +207,7 @@ export function buildCompletionDetails(result: SubagentResult): SubagentNotifyDe
 		...(taskInfo ? { taskInfo } : {}),
 		resultPreview: summary,
 		...(typeof result.durationMs === "number" ? { durationMs: result.durationMs } : {}),
+		...(handoffPath ? { handoffPath } : {}),
 		...(session ? { sessionLabel: session.label, sessionValue: session.value } : {}),
 	};
 }
@@ -193,102 +216,91 @@ export default function registerSubagentNotify(
 	pi: ExtensionAPI,
 	state: Pick<SubagentState, "currentSessionId">,
 	options: RegisterSubagentNotifyOptions = {},
-): () => void {
-	const unsubscribeStoreKey = "__pi_subagents_notify_unsubscribe__";
-	const batcherStoreKey = "__pi_subagents_notify_batcher__";
-	const globalStore = globalThis as Record<string, unknown>;
-	const previousUnsubscribe = globalStore[unsubscribeStoreKey];
-	if (typeof previousUnsubscribe === "function") {
-		try {
-			previousUnsubscribe();
-		} catch {
-			// Best effort cleanup for stale handlers from an older reload.
-		}
-	}
-	const previousBatcher = globalStore[batcherStoreKey];
-	if (previousBatcher && typeof (previousBatcher as { dispose?: () => void }).dispose === "function") {
-		try {
-			(previousBatcher as { dispose: () => void }).dispose();
-		} catch {
-			// Best effort cleanup for a stale batcher from an older reload.
-		}
-	}
-
-	const seen = getGlobalSeenMap("__pi_subagents_notify_seen__");
+): CompletionNotifier {
+	const seen = new Map<string, number>();
+	const pending = new Map<string, Promise<boolean>>();
 	const ttlMs = 10 * 60 * 1000;
-	const nowFn = options.now ?? Date.now;
+	const now = options.now ?? Date.now;
 	const batchConfig = resolveCompletionBatchConfig(options.batchConfig);
-	const batchers = new Map<string, CompletionBatcher<SubagentNotifyDetails>>();
+	const batchers = new Map<string, CompletionBatcher<PendingCompletion>>();
 	let disposed = false;
 
-	const handleComplete = (data: unknown) => {
-		if (disposed) return;
-		const result = data as SubagentResult;
-		if (typeof result.sessionId !== "string" || result.sessionId !== state.currentSessionId) return;
-		const now = nowFn();
-		const key = buildCompletionKey(result, "notify");
-		if (markSeenWithTtl(seen, key, now, ttlMs)) return;
-
-		const details = buildCompletionDetails(result);
-		if (result.source === "foreground") {
-			sendCompletion(pi, [details]);
-			return;
+	const settle = (items: PendingCompletion[], accepted: boolean) => {
+		for (const item of items) {
+			pending.delete(item.key);
+			if (accepted) markSeenWithTtl(seen, item.key, now(), ttlMs);
+			item.resolve(accepted);
 		}
-		const batchKey = completionBatchKey(result);
-		let batcher = batchers.get(batchKey);
+	};
+	const emit = (items: PendingCompletion[]) => settle(items, sendCompletion(pi, items));
+	const getBatcher = (result: CompletionNotification) => {
+		const key = completionBatchKey(result);
+		let batcher = batchers.get(key);
 		if (!batcher) {
-			batcher = createCompletionBatcher<SubagentNotifyDetails>({
+			batcher = createCompletionBatcher<PendingCompletion>({
 				config: batchConfig,
-				emit: (items) => sendCompletion(pi, items),
+				emit,
 				...(options.timers ? { timers: options.timers } : {}),
-				now: nowFn,
+				now,
 			});
-			batchers.set(batchKey, batcher);
+			batchers.set(key, batcher);
 		}
+		return batcher;
+	};
+
+	const deliver = (result: CompletionNotification): Promise<boolean> => {
+		if (disposed || typeof result.sessionId !== "string" || result.sessionId !== state.currentSessionId) return Promise.resolve(false);
+		const key = buildCompletionKey(result, "notify");
+		const seenAt = seen.get(key);
+		if (seenAt !== undefined && now() - seenAt <= ttlMs) return Promise.resolve(true);
+		if (seenAt !== undefined) seen.delete(key);
+		const inFlight = pending.get(key);
+		if (inFlight) return inFlight;
+		const details = buildCompletionDetails(result);
+		let resolve!: (accepted: boolean) => void;
+		const completion = new Promise<boolean>((settleCompletion) => { resolve = settleCompletion; });
+		pending.set(key, completion);
+		const item: PendingCompletion = {
+			key,
+			details,
+			triggerTurn: result.triggerTurn !== false,
+			resolve,
+		};
+		if (details.source === "foreground") {
+			emit([item]);
+			return completion;
+		}
+		const batcher = getBatcher(result);
 		if (details.status !== "completed") {
-			// Failures and paused runs bypass grouping. Flush any held
-			// successes for the same owner first so they are not stranded
-			// behind this signal, then emit the non-completion result immediately.
 			batcher.flush();
-			sendCompletion(pi, [details]);
-			return;
+			emit([item]);
+			return completion;
 		}
-		batcher.push(details);
+		batcher.push(item);
+		return completion;
 	};
 
-	const unsubscribers = [
-		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete),
-		pi.events.on(SUBAGENT_FOREGROUND_COMPLETE_EVENT, handleComplete),
-	].filter((unsubscribe): unsubscribe is () => void => typeof unsubscribe === "function");
-	const batcherRegistration = { dispose };
+	const unsubscribeAsync = pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, (data) => {
+		void deliver(data as CompletionNotification);
+	});
+	const unsubscribeForeground = pi.events.on(SUBAGENT_FOREGROUND_COMPLETE_EVENT, (data) => {
+		void deliver(data as CompletionNotification);
+	});
 
-	function dispose(): void {
-		if (disposed) return;
-		disposed = true;
-		for (const batcher of batchers.values()) {
-			try {
-				batcher.dispose();
-			} catch {
-				// Best effort cleanup must continue through every owned batcher.
-			}
-		}
-		batchers.clear();
-		for (const unsubscribe of unsubscribers) {
-			try {
-				unsubscribe();
-			} catch {
-				// Best effort cleanup must continue through every owned handler.
+	return {
+		deliver,
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			for (const batcher of batchers.values()) settle(batcher.dispose(), false);
+			batchers.clear();
+			for (const unsubscribe of [unsubscribeAsync, unsubscribeForeground]) {
+				try {
+					unsubscribe?.();
+				} catch {
+					// The runtime is already shutting down; pending records stay on disk.
+				}
 			}
-		}
-		if (globalStore[unsubscribeStoreKey] === dispose) {
-			delete globalStore[unsubscribeStoreKey];
-		}
-		if (globalStore[batcherStoreKey] === batcherRegistration) {
-			delete globalStore[batcherStoreKey];
-		}
-	}
-
-	globalStore[unsubscribeStoreKey] = dispose;
-	globalStore[batcherStoreKey] = batcherRegistration;
-	return dispose;
+		},
+	};
 }

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

@@ -0,0 +1,280 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson, writePrivateAtomicJson } from "../../shared/atomic-json.ts";
+import {
+	SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+	type AsyncStatus,
+	type CanonicalSessionTerminalV1,
+	type ProcessInstanceExitV1,
+	type ProcessTerminalReason,
+	type ProcessTerminalV1,
+} from "../../shared/types.ts";
+import { canonicalSessionId, inspectSessionLease } from "../shared/session-lease.ts";
+
+export interface ProcessTerminalCandidate {
+	version: 1;
+	runId: string;
+	runnerProcessInstanceId: string;
+	writers: Record<string, ProcessInstanceExitV1[]>;
+	expectedWriters?: Record<string, number>;
+	sessionFile?: string;
+	revivalLeaseToken?: string;
+	revivalLeaseReleaseAcknowledged?: boolean;
+}
+
+export interface RunnerCloseObservation {
+	processInstanceId: string;
+	closeObservedAt: number;
+	exitCode: number | null;
+	signal: string | null;
+}
+
+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 {
+	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;
+	if (typeof value.closeObservedAt !== "number" || !Number.isFinite(value.closeObservedAt)) return false;
+	if (typeof value.exitCode !== "number" && value.exitCode !== null) return false;
+	if (typeof value.signal !== "string" && value.signal !== null) return false;
+	return value.kind === "runner"
+		? value.attempt === undefined
+		: typeof value.attempt === "number" && Number.isInteger(value.attempt) && value.attempt >= 0;
+}
+
+function validInstance(value: unknown): value is ProcessInstanceExitV1 {
+	return validProcessInstance(value, "pi-writer");
+}
+
+export function processTerminalCandidatePath(asyncDir: string): string {
+	return path.join(asyncDir, "process-terminal-candidate.json");
+}
+
+export function processTerminalPath(asyncDir: string): string {
+	return path.join(asyncDir, "process-terminal.json");
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function readProcessTerminalCandidate(asyncDir: string): ProcessTerminalCandidate | undefined {
+	try {
+		const raw = JSON.parse(fs.readFileSync(processTerminalCandidatePath(asyncDir), "utf-8")) as unknown;
+		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[]> = {};
+		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;
+		}
+		let expectedWriters: Record<string, number> | undefined;
+		if (raw.expectedWriters !== undefined) {
+			if (!isRecord(raw.expectedWriters)) throw new Error("Invalid expected writer process records.");
+			expectedWriters = {};
+			for (const [index, count] of Object.entries(raw.expectedWriters)) {
+				if (typeof count !== "number" || !Number.isInteger(count) || count < 0) throw new Error(`Invalid expected writer count for child '${index}'.`);
+				expectedWriters[index] = count;
+			}
+		}
+		if (raw.sessionFile !== undefined && typeof raw.sessionFile !== "string") throw new Error("Invalid process-terminal candidate sessionFile.");
+		if (raw.revivalLeaseToken !== undefined && typeof raw.revivalLeaseToken !== "string") throw new Error("Invalid process-terminal candidate lease token.");
+		if (raw.revivalLeaseReleaseAcknowledged !== undefined && typeof raw.revivalLeaseReleaseAcknowledged !== "boolean") throw new Error("Invalid process-terminal lease release acknowledgement.");
+		return {
+			version: 1,
+			runId: raw.runId,
+			runnerProcessInstanceId: raw.runnerProcessInstanceId,
+			writers,
+			...(expectedWriters ? { expectedWriters } : {}),
+			...(raw.sessionFile ? { sessionFile: raw.sessionFile } : {}),
+			...(raw.revivalLeaseToken ? { revivalLeaseToken: raw.revivalLeaseToken } : {}),
+			...(raw.revivalLeaseReleaseAcknowledged !== undefined ? { revivalLeaseReleaseAcknowledged: raw.revivalLeaseReleaseAcknowledged } : {}),
+		};
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+export function writeProcessTerminalCandidate(asyncDir: string, candidate: ProcessTerminalCandidate): void {
+	writePrivateAtomicJson(processTerminalCandidatePath(asyncDir), candidate);
+}
+
+export function markProcessTerminalCandidateLeaseRelease(asyncDir: string, token: string, acknowledged: boolean): void {
+	const candidate = readProcessTerminalCandidate(asyncDir);
+	if (!candidate || candidate.revivalLeaseToken !== token) return;
+	writeProcessTerminalCandidate(asyncDir, { ...candidate, revivalLeaseReleaseAcknowledged: acknowledged });
+}
+
+function unknownProof(runId: string, runnerProcessInstanceId: string, reason: ProcessTerminalReason, diagnostic?: string): ProcessTerminalV1 {
+	return { version: 1, state: "unknown", runId, runnerProcessInstanceId, reason, ...(diagnostic ? { diagnostic } : {}) };
+}
+
+function resumeDisposition(state: string | undefined, sessionFile: string | undefined): "resumable" | "non-resumable" | "unavailable" {
+	if (state === "stopped") return "non-resumable";
+	if (state !== "complete" && state !== "completed" && state !== "failed" && state !== "paused") return "unavailable";
+	return sessionFile && fs.existsSync(sessionFile) ? "resumable" : "unavailable";
+}
+
+function sessionProjection(candidate: ProcessTerminalCandidate, lease: ReturnType<typeof inspectSessionLease>): CanonicalSessionTerminalV1 | undefined {
+	if (!candidate.sessionFile || lease.state !== "free") return undefined;
+	if (candidate.revivalLeaseToken && candidate.revivalLeaseReleaseAcknowledged !== true) return undefined;
+	return {
+		canonicalSessionId: canonicalSessionId(candidate.sessionFile),
+		leaseDisposition: candidate.revivalLeaseToken ? "released" : "not-held",
+		freeAtObservation: true,
+		...(candidate.revivalLeaseToken ? { canonicalSessionLeaseReleased: true } : {}),
+	};
+}
+
+function validateProof(raw: unknown, asyncDir: string, fallback?: { runId?: string; runnerProcessInstanceId?: string }): raw is ProcessTerminalV1 {
+	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}'.`);
+	}
+	if (fallback?.runId && raw.runId !== fallback.runId) throw new Error(`Process-terminal proof in '${asyncDir}' belongs to run '${raw.runId}', expected '${fallback.runId}'.`);
+	if (fallback?.runnerProcessInstanceId && raw.runnerProcessInstanceId !== fallback.runnerProcessInstanceId) throw new Error(`Process-terminal proof in '${asyncDir}' belongs to runner '${raw.runnerProcessInstanceId}', expected '${fallback.runnerProcessInstanceId}'.`);
+	if (raw.instances !== undefined && (!Array.isArray(raw.instances) || !raw.instances.every((entry) => validProcessInstance(entry)))) {
+		throw new Error(`Invalid process-terminal instances in '${asyncDir}'.`);
+	}
+	if (raw.state === "observed") {
+		if (typeof raw.observedAt !== "number" || !Number.isFinite(raw.observedAt)) throw new Error(`Observed process-terminal proof in '${asyncDir}' is missing observedAt.`);
+		if (!Array.isArray(raw.instances)) throw new Error(`Observed process-terminal proof in '${asyncDir}' is missing instances.`);
+		const runner = raw.instances.find((entry) => isRecord(entry) && entry.kind === "runner");
+		if (!validProcessInstance(runner, "runner") || runner.processInstanceId !== raw.runnerProcessInstanceId) throw new Error(`Observed process-terminal proof in '${asyncDir}' has no matching runner instance.`);
+	}
+	if (raw.resumeDisposition !== undefined && !["resumable", "non-resumable", "unavailable"].includes(String(raw.resumeDisposition))) throw new Error(`Invalid process-terminal resume disposition in '${asyncDir}'.`);
+	return true;
+}
+
+export function sanitizeProcessTerminal(value: unknown, fallback: { runId?: string; runnerProcessInstanceId?: string }, label = "status"): ProcessTerminalV1 | undefined {
+	if (value === undefined) return undefined;
+	try {
+		validateProof(value, label, fallback);
+		return value;
+	} 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 {
+	try {
+		const raw = JSON.parse(fs.readFileSync(processTerminalPath(asyncDir), "utf-8")) as unknown;
+		validateProof(raw, asyncDir, fallback);
+		return raw;
+	} 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));
+	}
+}
+
+function stepProcessTerminalProof(
+	proof: ProcessTerminalV1,
+	childIndex: number,
+	state: ProcessTerminalV1["state"],
+	records: ProcessInstanceExitV1[],
+	resumeDispositionValue: ProcessTerminalV1["resumeDisposition"],
+): ProcessTerminalV1 {
+	const base = {
+		version: 1 as const,
+		runId: proof.runId,
+		childIndex,
+		runnerProcessInstanceId: proof.runnerProcessInstanceId,
+		...(resumeDispositionValue ? { resumeDisposition: resumeDispositionValue } : {}),
+	};
+	if (state === "observed") {
+		return { ...base, state, observedAt: proof.state === "observed" ? proof.observedAt : Date.now(), instances: records };
+	}
+	if (state === "unknown") {
+		return { ...base, state, reason: proof.state === "unknown" ? proof.reason : "writer-close-unverified" };
+	}
+	return { ...base, state };
+}
+
+function overlayStatus(asyncDir: string, proof: ProcessTerminalV1, candidate?: ProcessTerminalCandidate): void {
+	const statusPath = path.join(asyncDir, "status.json");
+	try {
+		const status = JSON.parse(fs.readFileSync(statusPath, "utf-8")) as AsyncStatus;
+		status.processTerminal = proof;
+		if (status.steps) {
+			for (const [index, step] of status.steps.entries()) {
+				const records = candidate?.writers[String(index)] ?? [];
+				const expected = candidate?.expectedWriters?.[String(index)] ?? (records.length > 0 ? records.length : 0);
+				const stepState = expected === 0 ? "not-started" : proof.state === "observed" && records.length === expected ? "observed" : proof.state === "pending" ? "pending" : "unknown";
+				step.processTerminal = stepProcessTerminalProof(proof, index, stepState, records, resumeDisposition(step.status, step.sessionFile ?? candidate?.sessionFile));
+			}
+		}
+		writeAtomicJson(statusPath, status);
+	} catch {
+		// The proof sidecar remains authoritative when terminal status is unavailable.
+	}
+}
+
+export function finalizeProcessTerminal(
+	asyncDir: string,
+	runId: string,
+	runnerClose: RunnerCloseObservation,
+): ProcessTerminalV1 {
+	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 candidateForOverlay: ProcessTerminalCandidate | undefined;
+	try {
+		const candidate = readProcessTerminalCandidate(asyncDir);
+		candidateForOverlay = candidate;
+		if (!candidate) proof = unknownProof(runId, runnerClose.processInstanceId, "runner-candidate-missing");
+		else if (candidate.runId !== runId || candidate.runnerProcessInstanceId !== runnerClose.processInstanceId) proof = unknownProof(runId, runnerClose.processInstanceId, "runner-instance-mismatch");
+		else {
+			const allWriters = Object.values(candidate.writers).flat();
+			const status = (() => {
+				try { return JSON.parse(fs.readFileSync(path.join(asyncDir, "status.json"), "utf-8")) as AsyncStatus; } catch { return undefined; }
+			})();
+			const session = candidate.sessionFile ? inspectSessionLease(candidate.sessionFile) : undefined;
+			const writerEntries = Object.entries(candidate.writers);
+			const expectedWriters = candidate.expectedWriters ?? Object.fromEntries(writerEntries.map(([index, records]) => [index, records.length]));
+			const expectedEntries = Object.entries(expectedWriters);
+			const expectedIndexes = new Set(expectedEntries.map(([index]) => index));
+			const writerIndexes = new Set(writerEntries.map(([index]) => index));
+			const inconsistentWriters = writerEntries.some(([index, records]) => !expectedIndexes.has(index) || records.length !== expectedWriters[index])
+				|| expectedEntries.some(([index, expected]) => !writerIndexes.has(index) && expected !== 0);
+			if (session && session.state !== "free") {
+				proof = unknownProof(runId, runnerClose.processInstanceId, session.state === "owned" ? "canonical-session-lease-active" : "canonical-session-unavailable");
+			} else if (candidate.revivalLeaseToken && candidate.revivalLeaseReleaseAcknowledged !== true) {
+				proof = unknownProof(runId, runnerClose.processInstanceId, "canonical-session-release-unverified");
+			} else if (inconsistentWriters || (allWriters.length === 0 && expectedEntries.length === 0)) {
+				proof = unknownProof(runId, runnerClose.processInstanceId, "writer-close-unverified");
+			} else {
+				const runner: ProcessInstanceExitV1 = { kind: "runner", ...runnerClose };
+				const canonicalSession = session && sessionProjection(candidate, session);
+				proof = {
+					version: 1,
+					state: "observed",
+					runId,
+					runnerProcessInstanceId: runnerClose.processInstanceId,
+					observedAt: runnerClose.closeObservedAt,
+					instances: [runner, ...allWriters],
+					resumeDisposition: resumeDisposition(status?.state, candidate.sessionFile ?? status?.sessionFile),
+					...(canonicalSession ? { canonicalSession } : {}),
+				};
+			}
+		}
+	} catch (error) {
+		proof = unknownProof(runId, runnerClose.processInstanceId, "proof-write-failed", errorMessage(error));
+	}
+	let durable = false;
+	try {
+		writeAtomicJson(processTerminalPath(asyncDir), proof);
+		durable = true;
+		overlayStatus(asyncDir, proof, candidateForOverlay);
+		fs.appendFileSync(path.join(asyncDir, "events.jsonl"), `${JSON.stringify({ type: "subagent.run.process_terminal", lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, ts: Date.now(), runId, processTerminal: proof })}\n`, "utf-8");
+	} catch {
+		// Do not emit a process-terminal event when the proof sidecar was not durable.
+	}
+	return durable ? proof : unknownProof(runId, runnerClose.processInstanceId, "proof-write-failed", "Failed to persist process-terminal proof.");
+}