@selesai/code 0.13.39 → 0.14.0

package/dist/extensions/pi-subagents/src/runs/background/subagent-wait.ts

@@ -39,6 +39,7 @@
  */
 
 import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import {
 	listBackgroundWorkWakeChannels,
@@ -61,6 +62,7 @@ import {
 	type Usage,
 	type WaitCompletion,
 } from "../../shared/types.ts";
+import { nestedRunScope } from "../shared/nested-events.ts";
 import { formatDuration, shortenPath } from "../../shared/formatters.ts";
 import { formatTimeoutRecoveryLines } from "../shared/mutation-evidence.ts";
 import { toAgentToolUsage } from "../../shared/utils.ts";
@@ -103,6 +105,8 @@ export interface SubagentWaitDeps {
 	onUpdate?: (result: AgentToolResult<Details>) => void;
 	asyncDirRoot?: string;
 	resultsDir?: string;
+	/** Root from the child's validated inherited route, not a tool argument. */
+	nestedRootRunId?: string;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
 	pollIntervalMs?: number;
@@ -118,6 +122,8 @@ export interface SubagentWaitDeps {
 	failOnFailedRuns?: boolean;
 	/** Internal auto-drain mode surfaces actionable attention as an error. */
 	failOnAttention?: boolean;
+	/** Durable owned supervisor-request barrier used by headless auto-drain. */
+	hasPendingSupervisorRequest?: () => boolean;
 	/** Arm a durable exact-target wait subscription in a long-lived interactive runtime. */
 	subscribe?: (input: { targetKind: "async" | "foreground"; runId: string; requestedId: string; timeoutMs: number }) => { token: string; expiresAt: number };
 	/** Injectable provider protocol surfaces for deterministic tests. */
@@ -214,14 +220,13 @@ function matchesId(run: AsyncRunSummary, id: string): boolean {
 }
 
 function activeDetachedForegroundRuns(params: SubagentWaitParams, deps: SubagentWaitDeps): ForegroundResumeRun[] {
-	if (!params.id || !deps.state.foregroundRuns) return [];
 	const sessionId = deps.state.currentSessionId;
-	if (!sessionId) return [];
-	return [...deps.state.foregroundRuns.values()].filter((run) =>
-		(run.runId === params.id || run.runId.startsWith(params.id!))
-		&& run.sessionId === sessionId
-		&& run.children.some((child) => child.status === "detached")
+	if (!sessionId || !deps.state.foregroundRuns) return [];
+	const runs = [...deps.state.foregroundRuns.values()].filter((run) =>
+		run.sessionId === sessionId && run.children.some((child) => child.status === "detached")
 	);
+	if (params.id) return runs.filter((run) => run.runId === params.id || run.runId.startsWith(params.id!));
+	return params.all === true ? runs : [];
 }
 
 function summarizeForegroundChildren(run: ForegroundResumeRun, indices: Set<number>): string {
@@ -265,22 +270,39 @@ function backgroundWorkForSession(deps: SubagentWaitDeps, nowMs: number): Backgr
 	return deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);
 }
 
-/** Queued/running runs from this session, including runs that need attention. */
-function activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {
-	const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
-	const resultsDir = deps.resultsDir ?? DIRS.results;
-	const runs = listAsyncRuns(asyncDirRoot, {
-		states: [...ACTIVE_STATES],
+export function waitRunScopes(deps: Pick<SubagentWaitDeps, "asyncDirRoot" | "resultsDir" | "nestedRootRunId">): Array<{ asyncDirRoot: string; resultsDir: string }> {
+	return [
+		{ asyncDirRoot: deps.asyncDirRoot ?? DIRS.async, resultsDir: deps.resultsDir ?? DIRS.results },
+		...(deps.nestedRootRunId ? [nestedRunScope(deps.nestedRootRunId)] : []),
+	];
+}
+
+function collectScopedCompletions(terminal: AsyncRunSummary[], deps: SubagentWaitDeps, references: string[]): WaitCompletion[] | undefined {
+	const completions = waitRunScopes(deps).flatMap((scope) => collectWaitCompletions(
+		terminal.filter((run) => path.resolve(path.dirname(run.asyncDir)) === path.resolve(scope.asyncDirRoot)),
+		deps.state, scope.resultsDir, (reference) => references.push(reference),
+	) ?? []);
+	return completions.length ? completions : undefined;
+}
+
+/** Immediate-session runs only; named lookups can also recover already-terminal results. */
+function runsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps, activeOnly = true): AsyncRunSummary[] {
+	const runs = waitRunScopes(deps).flatMap(({ asyncDirRoot, resultsDir }) => listAsyncRuns(asyncDirRoot, {
+		states: activeOnly ? [...ACTIVE_STATES] : undefined,
 		sessionId: deps.state.currentSessionId ?? undefined,
 		resultsDir,
 		kill: deps.kill,
 		now: deps.now,
 		includeNested: false,
 		...(params.id ? { runId: params.id } : {}),
-	});
+	}));
 	return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
 }
 
+function activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {
+	return runsForSession(params, deps);
+}
+
 /** Runs (from the initial set) currently flagged needs_attention, for reporting. */
 function attentionRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps, initialIds: Set<string>): AsyncRunSummary[] {
 	return activeRunsForSession(params, deps).filter((run) => needsAttention(run) && initialIds.has(run.id));
@@ -288,9 +310,7 @@ function attentionRunsForSession(params: SubagentWaitParams, deps: SubagentWaitD
 
 /** Exact initial runs in any state, for the final summary. */
 function runsForIds(runIds: Iterable<string>, deps: SubagentWaitDeps): AsyncRunSummary[] {
-	const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
-	const resultsDir = deps.resultsDir ?? DIRS.results;
-	return [...runIds].flatMap((runId) => listAsyncRuns(asyncDirRoot, {
+	return waitRunScopes(deps).flatMap(({ asyncDirRoot, resultsDir }) => [...runIds].flatMap((runId) => listAsyncRuns(asyncDirRoot, {
 		sessionId: deps.state.currentSessionId ?? undefined,
 		resultsDir,
 		kill: deps.kill,
@@ -298,7 +318,7 @@ function runsForIds(runIds: Iterable<string>, deps: SubagentWaitDeps): AsyncRunS
 		includeNested: false,
 		runId,
 		exactRunId: true,
-	}));
+	})));
 }
 
 function summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount = 0): string {
@@ -378,6 +398,49 @@ function windowElapsedResult(
 	};
 }
 
+function supervisorYieldResult(
+	activeRunIds: string[],
+	activeProviderItems: readonly RegisteredBackgroundWorkItem[] = [],
+): AgentToolResult<Details> {
+	return {
+		content: [{ type: "text", text: "Wait yielded for a pending supervisor request. Background work remains active and will continue after the supervisor reply." }],
+		details: {
+			mode: "management",
+			results: [],
+			wait: {
+				reason: "supervisor_request",
+				timedOut: false,
+				activeRunIds,
+				activeProviderItems: activeProviderItems.map(({ provider, id }) => ({ provider, id })),
+			},
+		},
+	};
+}
+
+interface InitialWaitScope {
+	asyncRunIds: Set<string>;
+	foregroundRuns: Array<{ runId: string; sessionId?: string; detachedIndices: Set<number> }>;
+	providerIds: Set<string>;
+}
+
+function supervisorYieldForScope(scope: InitialWaitScope, params: SubagentWaitParams, deps: SubagentWaitDeps, nowMs: number): AgentToolResult<Details> {
+	try {
+		const activeAsyncIds = new Set(activeRunsForSession(params.id ? { id: params.id } : {}, deps).map((run) => run.id));
+		const activeRunIds = new Set([...scope.asyncRunIds].filter((id) => activeAsyncIds.has(id)));
+		for (const initial of scope.foregroundRuns) {
+			const current = deps.state.foregroundRuns?.get(initial.runId);
+			if (!current || current.sessionId !== initial.sessionId) continue;
+			if (current.children.some((child) => initial.detachedIndices.has(child.index) && child.status === "detached")) activeRunIds.add(initial.runId);
+		}
+		const activeProviderItems = scope.providerIds.size > 0
+			? backgroundWorkForSession(deps, nowMs).items.filter((item) => scope.providerIds.has(backgroundWorkIdentity(item)))
+			: [];
+		return supervisorYieldResult([...activeRunIds], activeProviderItems);
+	} catch (error) {
+		return result(error instanceof Error ? error.message : String(error), true);
+	}
+}
+
 /** Build the live status shown while async work keeps bg_wait blocked. */
 function asyncWaitUpdate(runs: AsyncRunSummary[], providerCount: number, elapsedMs: number): AgentToolResult<Details> {
 	const activity = runs.flatMap((run) => {
@@ -500,6 +563,7 @@ async function waitForDetachedForegroundRun(
 	now: () => number,
 	pollIntervalMs: number,
 	timeoutMs: number,
+	supervisorYield: () => AgentToolResult<Details>,
 ): Promise<AgentToolResult<Details>> {
 	const initialDetachedIndices = new Set(run.children.filter((child) => child.status === "detached").map((child) => child.index));
 	while (true) {
@@ -510,6 +574,7 @@ async function waitForDetachedForegroundRun(
 		if (!current || current.sessionId !== run.sessionId) {
 			return result(`Remembered foreground run "${run.runId}" disappeared before a terminal child result was recorded. Completion cannot be confirmed; do not launch a replacement without checking the originating child session.`, true);
 		}
+		if (deps.hasPendingSupervisorRequest?.()) return supervisorYield();
 		const pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === "detached");
 		const attention = foregroundChildrenNeedingAttention(current, initialDetachedIndices);
 		if (attention.length > 0) return formatForegroundAttention(current, attention, now() - startedAt);
@@ -534,6 +599,38 @@ async function waitForDetachedForegroundRun(
 	}
 }
 
+async function waitForSessionDetachedForegroundRuns(
+	runs: ForegroundResumeRun[],
+	signal: AbortSignal | undefined,
+	deps: SubagentWaitDeps,
+	startedAt: number,
+	now: () => number,
+	pollIntervalMs: number,
+	timeoutMs: number,
+	supervisorYield: () => AgentToolResult<Details>,
+): Promise<AgentToolResult<Details>> {
+	const texts: string[] = [];
+	for (const run of runs) {
+		const one = await waitForDetachedForegroundRun(run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
+		if (one.isError) return one;
+		if (one.details.wait?.reason === "supervisor_request") return one;
+		if (one.details.wait?.reason === "window_elapsed") {
+			const activeRunIds = runs.filter((initial) => {
+				const current = deps.state.foregroundRuns?.get(initial.runId);
+				if (!current || current.sessionId !== initial.sessionId) return false;
+				return initial.children.some((child) => child.status === "detached"
+						&& current.children.some((candidate) => candidate.index === child.index && candidate.status === "detached"));
+			}).map((activeRun) => activeRun.runId);
+			return windowElapsedResult(
+				one.content.map((part) => part.type === "text" ? part.text : "").join("\n"),
+				activeRunIds,
+			);
+		}
+		texts.push(one.content.map((part) => part.type === "text" ? part.text : "").join("\n").trim());
+	}
+	return result(texts.filter(Boolean).join("\n") || `Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run(s); done.`);
+}
+
 /**
  * Block until the targeted async or remembered detached foreground run finishes,
  * the timeout elapses, or the turn is aborted. Resolves with a short
@@ -557,6 +654,7 @@ export async function waitForSubagents(
 		? params.timeoutMs
 		: deps.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const startedAt = now();
+	const sessionId = deps.state.currentSessionId;
 	const waitForAll = params.id ? true : params.all === true;
 	if (params.nonBlocking && !params.id) {
 		return result("Non-blocking wait subscriptions require id so the registration can bind one exact run identity.", true);
@@ -569,13 +667,17 @@ export async function waitForSubagents(
 	let foreground: ForegroundResumeRun[];
 	let providerSnapshot: BackgroundWorkSnapshot;
 	try {
-		active = activeRunsForSession(params, deps);
-		foreground = activeDetachedForegroundRuns(params, deps);
+		active = runsForSession(params, deps, !params.id);
+		foreground = activeDetachedForegroundRuns(params, deps).map((run) => ({
+			...run,
+			children: run.children.map((child) => ({ ...child })),
+		}));
 		providerSnapshot = params.id ? { providers: [], items: [] } : backgroundWorkForSession(deps, startedAt);
 	} catch (error) {
 		return result(error instanceof Error ? error.message : String(error), true);
 	}
 
+	let selectedForeground: ForegroundResumeRun | undefined;
 	if (params.id) {
 		const candidates = [
 			...active.map((run) => ({ kind: "async" as const, id: run.id, run })),
@@ -584,9 +686,21 @@ export async function waitForSubagents(
 		const exact = candidates.filter((candidate) => candidate.id === params.id);
 		const matches = exact.length > 0 ? exact : candidates;
 		if (matches.length > 1) {
-			return result(`Ambiguous subagent run id prefix "${params.id}" matched ${matches.length} active runs: ${matches.map((candidate) => candidate.id).join(", ")}. Pass a longer id.`, true);
+			return result(`Ambiguous subagent run id prefix "${params.id}" matched ${matches.length} runs: ${matches.map((candidate) => candidate.id).join(", ")}. Pass a longer id.`, true);
 		}
 		const selected = matches[0];
+		if (selected?.kind === "async" && !ACTIVE_STATES.includes(selected.run.state)) {
+			try {
+				const references: string[] = [];
+				const completions = collectScopedCompletions([selected.run], deps, references);
+				return result(
+					`Run "${selected.id}" is terminal. Outcome: ${summarizeTerminalRuns([selected.run])}.${formatCompletionRecovery(completions)}${references.length ? `\n${references.join("\n")}` : ""}`,
+					deps.failOnFailedRuns === true && (selected.run.state === "failed" || selected.run.state === "partial"), completions,
+				);
+			} catch (error) {
+				return result(error instanceof Error ? error.message : String(error), true);
+			}
+		}
 		if (selected && params.nonBlocking) {
 			if (!deps.subscribe) {
 				return result("Non-blocking wait subscriptions require a long-lived interactive subagent runtime; this runtime can only use blocking bg_wait calls.", true);
@@ -598,27 +712,47 @@ export async function waitForSubagents(
 				return result(error instanceof Error ? error.message : String(error), true);
 			}
 		}
-		if (selected?.kind === "foreground") {
-			return waitForDetachedForegroundRun(selected.run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);
-		}
+		selectedForeground = selected?.kind === "foreground" ? selected.run : undefined;
 		active = selected?.kind === "async" ? [selected.run] : [];
 	}
 
 	let providerActive = providerSnapshot.items;
+	const scopedForeground = selectedForeground ? [selectedForeground] : params.id ? [] : foreground;
+	const initialAsyncIds = new Set(active.map((run) => run.id));
+	const initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+	const initialScope: InitialWaitScope = {
+		asyncRunIds: initialAsyncIds,
+		foregroundRuns: scopedForeground.map((run) => ({
+			runId: run.runId,
+			sessionId: run.sessionId,
+			detachedIndices: new Set(run.children.filter((child) => child.status === "detached").map((child) => child.index)),
+		})),
+		providerIds: initialProviderIds,
+	};
+	const supervisorYield = () => supervisorYieldForScope(initialScope, params, deps, now());
+	if (selectedForeground) {
+		return waitForDetachedForegroundRun(selectedForeground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
+	}
 	if (active.length === 0 && providerActive.length === 0) {
+		if (waitForAll && !params.id && foreground.length > 0) {
+			return waitForSessionDetachedForegroundRuns(foreground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
+		}
 		return result(params.id
 			? `No active run matched "${params.id}". Nothing to wait for.`
 			: "No active async runs or registered provider work in this session. Nothing to wait for.");
 	}
 	const waitParams = params.id ? { ...params, id: active[0]!.id } : params;
-	const initialAsyncIds = new Set(active.map((run) => run.id));
-	const initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
 	const initialProviderNames = new Set(providerActive.map((item) => item.provider));
 	const initialCount = initialAsyncIds.size + initialProviderIds.size;
 	const stopOnAttention = params.stopOnAttention ?? deps.stopOnAttention !== false;
 	let attention = active.filter((run) => needsAttention(run));
+	let supervisorBarrier = false;
 
 	const isDone = (): boolean => {
+		if (deps.hasPendingSupervisorRequest?.()) {
+			supervisorBarrier = true;
+			return true;
+		}
 		if (attention.some((run) => initialAsyncIds.has(run.id) && (stopOnAttention || hasSupervisorTool(run)))) return true;
 		const activeAsyncIds = new Set(active.map((run) => run.id));
 		const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
@@ -650,6 +784,7 @@ export async function waitForSubagents(
 		}
 		try {
 			await waitForWake(pollIntervalMs, signal, deps);
+			if (deps.state.currentSessionId !== sessionId) return result("Wait stopped because the active session changed.", true);
 			active = activeRunsForSession(waitParams, deps);
 			attention = attentionRunsForSession(waitParams, deps, initialAsyncIds);
 			providerSnapshot = params.id ? providerSnapshot : backgroundWorkForSession(deps, now());
@@ -663,12 +798,16 @@ export async function waitForSubagents(
 			return result(error instanceof Error ? error.message : String(error), true);
 		}
 	}
+	if (supervisorBarrier) {
+		return supervisorYield();
+	}
 
 	let terminalSummary: string;
 	let finishedAsyncCount: number;
 	let failedAsyncCount: number;
 	let completions: WaitCompletion[] | undefined;
 	let resumeGuidance = "";
+	const references: string[] = [];
 	const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
 	const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
 	try {
@@ -678,7 +817,7 @@ export async function waitForSubagents(
 		failedAsyncCount = terminal.filter((run) => run.state === "failed" || run.state === "partial").length;
 		terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
 		resumeGuidance = formatResumeFirstFailedRunsNote(terminal);
-		completions = collectWaitCompletions(terminal, deps.state, deps.resultsDir ?? DIRS.results);
+		completions = collectScopedCompletions(terminal, deps, references);
 	} catch (error) {
 		return result(error instanceof Error ? error.message : String(error), true);
 	}
@@ -694,9 +833,18 @@ export async function waitForSubagents(
 		+ providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;
 	const elapsed = formatDuration(now() - startedAt);
 	const outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : "";
-	const recoveryNote = formatCompletionRecovery(completions);
+	const recoveryNote = formatCompletionRecovery(completions) + (references.length ? `\n${references.join("\n")}\n` : "");
 
 	if (waitForAll) {
+		const foregroundResult = !params.id && foreground.length > 0 && relevantAttention.length === 0
+			? await waitForSessionDetachedForegroundRuns(foreground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield)
+			: undefined;
+		if (foregroundResult?.isError) return foregroundResult;
+		if (foregroundResult?.details.wait?.reason === "supervisor_request") return foregroundResult;
+		if (foregroundResult?.details.wait?.reason === "window_elapsed") return foregroundResult;
+		const foregroundNote = foregroundResult
+			? `\n${foregroundResult.content.map((part) => part.type === "text" ? part.text : "").join("\n")}`
+			: "";
 		const scope = params.id
 			? `run "${params.id}"`
 			: initialProviderIds.size === 0
@@ -704,7 +852,7 @@ export async function waitForSubagents(
 				: `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;
 		const status = relevantAttention.length > 0 ? "attention required" : "done";
 		return result(
-			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
+			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote}${foregroundNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
 			(deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0),
 			completions,
 		);
@@ -725,4 +873,4 @@ export async function waitForSubagents(
 		(deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0),
 		completions,
 	);
-}
+}

package/dist/extensions/pi-subagents/src/runs/background/wait-completions.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import type { ArtifactPaths, SubagentState, Usage, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
 import type { AsyncRunSummary } from "./async-status.ts";
 import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
-import { fallbackResultPayloadPathForSessionRun, resultFilePath, resultPayloadPathForSessionRun } from "./result-files.ts";
+import { fallbackResultPayloadPathForSessionRun, resultFilePath, resultPayloadMatchesSessionRun, resultPayloadPathForSessionRun } from "./result-files.ts";
 import { parseWorkflowChildSummary } from "../../workflows/workflow-child-summary.ts";
 import { projectTimeoutRecovery } from "../shared/mutation-evidence.ts";
 
@@ -44,6 +44,27 @@ function errorMessage(error: unknown): string {
 
 const STRUCTURED_OUTPUT_INLINE_LIMIT_BYTES = 4 * 1024;
 
+function waitResultPayloadCandidate(resultsDir: string, run: AsyncRunSummary): string {
+	const publicPath = resultFilePath(resultsDir, run.id);
+	if (!run.sessionId) return publicPath;
+	try {
+		const indexedPath = resultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id);
+		return indexedPath ?? publicPath;
+	} catch (error) {
+		if (!isAccessDenied(error)) throw error;
+		const pendingPath = fallbackResultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id);
+		return pendingPath ?? publicPath;
+	}
+}
+
+function readWaitResultPayload(candidatePath: string, run: AsyncRunSummary): Record<string, unknown> | undefined {
+	// A terminal run without session ownership cannot safely claim a payload.
+	if (!run.sessionId) return undefined;
+	const payload: unknown = JSON.parse(fs.readFileSync(candidatePath, "utf-8"));
+	if (!resultPayloadMatchesSessionRun(payload, run.sessionId, run.id)) return undefined;
+	return payload as Record<string, unknown>;
+}
+
 export function projectStructuredOutput(value: unknown): unknown {
 	if (value === undefined) return undefined;
 	const serialized = JSON.stringify(value);
@@ -85,6 +106,7 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 				...(sessionFile ? { sessionFile } : {}),
 				...(typeof child.success === "boolean" ? { success: child.success } : {}),
 				...(outputState ? { outputState } : {}),
+				...(child.outputPartial === true ? { outputPartial: true } : {}),
 				...(structuredOutput !== undefined ? { structuredOutput } : {}),
 				...(structuredOutputPath ? { structuredOutputPath } : {}),
 				...(error ? { error } : {}),
@@ -118,8 +140,9 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 /**
  * Record a consumed terminal payload for later surfacing by bg_wait, pruning
  * stale entries with the same TTL that dedupes completion notifications. The result
- * file is deleted after delivery, so this record is the only in-process source once
- * the watcher has consumed it.
+ * file is deleted after durable replay succeeds, so this record is the in-process
+ * source once the watcher has consumed it. Payload ownership must be explicit and
+ * agree with persistence ownership. Returns whether that replay is durable.
  */
 export function recordWaitCompletion(
 	state: SubagentState,
@@ -128,7 +151,10 @@ export function recordWaitCompletion(
 	now: number,
 	ttlMs: number,
 	persistence?: { resultsDir: string; sessionId: string },
-): void {
+): boolean {
+	const sessionId = asNonEmptyString(data.sessionId);
+	if (!sessionId || !resultPayloadMatchesSessionRun(data, sessionId, runId)) return false;
+	if (persistence && persistence.sessionId !== sessionId) return false;
 	const store = state.completedResults ??= new Map();
 	for (const [key, entry] of store) {
 		if (now - entry.seenAt > ttlMs) store.delete(key);
@@ -148,7 +174,8 @@ export function recordWaitCompletion(
 			console.error(`Failed to persist completion replay for '${runId}':`, error);
 		}
 	}
-	store.set(runId, { seenAt: now, completion });
+	store.set(runId, { sessionId, seenAt: now, completion });
+	return completion.archivePath !== undefined;
 }
 
 /**
@@ -157,37 +184,59 @@ export function recordWaitCompletion(
  * so a direct read never observes a torn write; the read is deliberately read-only —
  * the watcher owns notification and cleanup.
  */
-export function collectWaitCompletions(terminal: AsyncRunSummary[], state: SubagentState, resultsDir: string): WaitCompletion[] | undefined {
+export function collectWaitCompletions(terminal: AsyncRunSummary[], state: SubagentState, resultsDir: string, onReference?: (text: string) => void): WaitCompletion[] | undefined {
 	if (terminal.length === 0) return undefined;
 	const completions: WaitCompletion[] = [];
+	const add = (completion: WaitCompletion, resultPath?: string): void => {
+		completions.push(completion);
+		// Tool details are not model context. Publish the evidence address in content
+		// without copying potentially unbounded reviewer output into every wait.
+		const reference = completion.archivePath ?? resultPath;
+		if (reference) onReference?.(`Result [${completion.runId}]: ${reference}`);
+	};
 	for (const run of terminal) {
 		const recorded = state.completedResults?.get(run.id);
-		if (recorded) {
-			completions.push(recorded.completion);
+		if (recorded && recorded.sessionId === run.sessionId) {
+			if (recorded.completion.archivePath) {
+				add(recorded.completion);
+				continue;
+			}
+			try {
+				const candidatePath = waitResultPayloadCandidate(resultsDir, run);
+				if (!readWaitResultPayload(candidatePath, run)) {
+					const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
+					add(replay?.completion ?? recorded.completion);
+					continue;
+				}
+				add(recorded.completion, candidatePath);
+				continue;
+			} catch (error) {
+				if (errorCode(error) !== "ENOENT") throw error;
+			}
+			const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
+			add(replay?.completion ?? recorded.completion);
 			continue;
 		}
-		const publicResultPath = resultFilePath(resultsDir, run.id);
-		let resultPath = publicResultPath;
+		let candidatePath: string;
 		try {
-			resultPath = run.sessionId
-				? resultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id) ?? publicResultPath
-				: publicResultPath;
+			candidatePath = waitResultPayloadCandidate(resultsDir, run);
 		} catch (error) {
-			if (!isAccessDenied(error) || !run.sessionId) throw error;
-			try {
-				resultPath = fallbackResultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id) ?? publicResultPath;
-			} catch (fallbackError) {
-				throw new Error(`Failed to read subagent result '${publicResultPath}': ${errorMessage(fallbackError)}`, {
-					cause: fallbackError instanceof Error ? fallbackError : undefined,
-				});
-			}
+			const publicResultPath = resultFilePath(resultsDir, run.id);
+			throw new Error(`Failed to read subagent result '${publicResultPath}': ${errorMessage(error)}`, {
+				cause: error instanceof Error ? error : undefined,
+			});
 		}
 		try {
-			const raw = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as Record<string, unknown>;
-			completions.push(toWaitCompletion(raw, run.id));
+			const payload = readWaitResultPayload(candidatePath, run);
+			if (!payload) {
+				const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
+				if (replay) add(replay.completion);
+				continue;
+			}
+			add(toWaitCompletion(payload, run.id), candidatePath);
 		} catch (error) {
 			if (errorCode(error) !== "ENOENT") {
-				throw new Error(`Failed to read subagent result '${resultPath}': ${errorMessage(error)}`, {
+				throw new Error(`Failed to read subagent result '${candidatePath}': ${errorMessage(error)}`, {
 					cause: error instanceof Error ? error : undefined,
 				});
 			}
@@ -195,13 +244,13 @@ export function collectWaitCompletions(terminal: AsyncRunSummary[], state: Subag
 			// read. Prefer its in-memory record, then the durable replay written before
 			// result cleanup so watcher reloads do not lose completion details.
 			const late = state.completedResults?.get(run.id);
-			if (late) {
-				completions.push(late.completion);
+			if (late && late.sessionId === run.sessionId) {
+				add(late.completion);
 				continue;
 			}
 			try {
 				const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
-				if (replay) completions.push(replay.completion);
+				if (replay) add(replay.completion);
 			} catch (replayError) {
 				throw new Error(`Failed to read completion replay for '${run.id}': ${errorMessage(replayError)}`, {
 					cause: replayError instanceof Error ? replayError : undefined,
@@ -210,4 +259,4 @@ export function collectWaitCompletions(terminal: AsyncRunSummary[], state: Subag
 		}
 	}
 	return completions.length > 0 ? completions : undefined;
-}
+}

package/dist/extensions/pi-subagents/src/runs/background/wait-subscriptions.ts

@@ -44,6 +44,7 @@ export interface ArmWaitSubscriptionInput {
 }
 
 export interface WaitSubscriptionManager {
+	start(): void;
 	arm(input: ArmWaitSubscriptionInput): WaitSubscriptionRecord;
 	restore(): void;
 	reconcile(): void;
@@ -109,6 +110,7 @@ export function createWaitSubscriptionManager(
 	state.waitSubscriptions = subscriptions;
 	const unresolvedRestoredForegroundTokens = new Set<string>();
 	let disposed = false;
+	let interval: ReturnType<typeof setInterval> | undefined;
 	let lastForeignSweepAt = 0;
 
 	/**
@@ -283,10 +285,13 @@ export function createWaitSubscriptionManager(
 		SUBAGENT_RESULT_INTERCOM_EVENT,
 	];
 	const unsubscribes = wakeChannels.map((channel) => pi.events.on(channel, reconcile));
-	const interval = setInterval(reconcile, options.pollIntervalMs ?? RECONCILE_INTERVAL_MS);
-	interval.unref?.();
 
 	return {
+		start() {
+			if (disposed || interval) return;
+			interval = setInterval(reconcile, options.pollIntervalMs ?? RECONCILE_INTERVAL_MS);
+			interval.unref?.();
+		},
 		arm(input) {
 			const sessionId = state.currentSessionId;
 			if (!sessionId) throw new Error("A wait subscription requires an active session identity.");
@@ -338,11 +343,12 @@ export function createWaitSubscriptionManager(
 		dispose() {
 			if (disposed) return;
 			disposed = true;
-			clearInterval(interval);
+			if (interval) clearInterval(interval);
+			interval = undefined;
 			for (const unsubscribe of unsubscribes) {
 				try { unsubscribe(); } catch { /* best effort */ }
 			}
 			subscriptions.clear();
 		},
 	};
-}
+}