pi-subagents 0.65.1 → 0.66.0

package/src/runs/background/subagent-wait.ts

@@ -337,6 +337,9 @@ function completionUsage(completions: WaitCompletion[] | undefined): Usage | und
 
 function result(text: string, isError = false, completions?: WaitCompletion[]): AgentToolResult<Details> {
 	const usage = completionUsage(completions);
+	for (const completion of completions ?? []) {
+		if (completion.workflowReceiptPath) text += `\nWorkflow receipt [${completion.runId}]: ${completion.workflowReceiptPath}`;
+	}
 	return {
 		content: [{ type: "text", text }],
 		...(isError ? { isError: true } : {}),

package/src/runs/background/wait-completions.ts

@@ -96,6 +96,9 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 		})
 		: undefined;
 	const agent = asNonEmptyString(data.agent);
+	const receipt = data.workflowReceipt;
+	const workflowReceiptPath = receipt && typeof receipt === "object" && !Array.isArray(receipt)
+		? asNonEmptyString((receipt as Record<string, unknown>).path) : undefined;
 	const mode = asNonEmptyString(data.mode);
 	const state = asNonEmptyString(data.state);
 	const workflowChildren = parseWorkflowChildSummary(data.workflowChildren);
@@ -104,6 +107,7 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 		runId,
 		...(agent ? { agent } : {}),
 		...(mode ? { mode } : {}),
+		...(workflowReceiptPath ? { workflowReceiptPath } : {}),
 		...(state ? { state } : {}),
 		...(typeof data.success === "boolean" ? { success: data.success } : {}),
 		...(results && results.length > 0 ? { results } : {}),

package/src/runs/foreground/async-steering-action.ts

@@ -26,6 +26,7 @@ export async function steerAsyncRun(input: {
 	message: string;
 	mode?: SteerDeliveryMode;
 	index?: number;
+	findPendingAsks?: (target: { runId: string; agent: string; childIndex: number }) => string[];
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	location: { asyncDir: string | null };
 	signal?: AbortSignal;
@@ -44,6 +45,24 @@ export async function steerAsyncRun(input: {
 		};
 	}
 	const asyncDir = input.location.asyncDir;
+	const snapshot = input.findPendingAsks ? readStatus(asyncDir) : null;
+	if (snapshot?.mode === "single"
+		&& (!input.state.currentSessionId || snapshot.sessionId === input.state.currentSessionId)
+		&& (snapshot.state === "running" || snapshot.state === "queued")
+		&& snapshot.steps?.length === 1 && (input.index === undefined || input.index === 0)
+		&& (snapshot.steps[0]?.status === "running" || snapshot.steps[0]?.status === "pending")) {
+		const asks = input.findPendingAsks?.({ runId: snapshot.runId, agent: snapshot.steps[0].agent, childIndex: 0 }) ?? [];
+		if (asks.length > 0) {
+			const replies = asks.map(replyTo => `subagent_supervisor(${JSON.stringify({ action: "reply", replyTo, message: "<explicit answer>" })})`).join("\n");
+			return {
+				content: [{ type: "text", text: `Steering not delivered or queued: async run ${snapshot.runId} is blocked on ${asks.length === 1 ? "a pending supervisor ask" : "ambiguous pending supervisor asks"}. No reply or recovery was attempted. Reply explicitly${asks.length > 1 ? " to the intended request ID" : ""}:\n${replies}` }],
+				isError: true,
+				details: { mode: "management", results: [] },
+			};
+		}
+	}
+	// The read-only snapshot precedes even stale-run reconciliation. An ask arriving
+	// later does not make a runner acknowledgement proof of consumption or unblocking.
 	const status = reconcileAsyncRun(asyncDir, { kill: input.kill }).status;
 	if (input.state.currentSessionId && status?.sessionId !== input.state.currentSessionId) {
 		return {

package/src/runs/foreground/execution.ts

@@ -58,6 +58,9 @@ import { effectiveToolTimeoutMs, formatToolTimeoutMessage, resolveToolTimeoutMs,
 import { evaluateCompletionMutationGuard, expectsImplementationMutation, hasMutationToolCapability, validateImplementationToolContract } from "../shared/completion-guard.ts";
 import { planCompletionEvidence } from "../shared/completion-evidence.ts";
 import { planAbortRecovery } from "../shared/abort-recovery.ts";
+import { planReadonlyModelContinuation, type LogicalRecoveryState } from "../shared/readonly-model-continuation.ts";
+import { getReadonlySessionEvidence, requestReadonlySessionEvidence, type SettledReadonlyEvidence } from "../shared/readonly-session-evidence.ts";
+import { getReadonlyChildModels } from "../shared/child-session.ts";
 import { arbitrateCompletionGuardRescue } from "../shared/llm-intent-arbiter.ts";
 import { preflightLaunchCwd } from "../shared/launch-cwd.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
@@ -94,7 +97,7 @@ import {
 } from "../shared/long-running-guard.ts";
 import { acceptanceFailureMessage, buildSkippedAcceptanceLedger, evaluateAcceptance, formatAcceptancePrompt, resolveEffectiveAcceptance, stripAcceptanceReport, validateAcceptanceInput } from "../shared/acceptance.ts";
 import { PROMPT_REDACTED } from "../../shared/utils.ts";
-import { attachContractProjections, isAgentContractV1 } from "../shared/agent-contract.ts";
+import { attachContractProjections, isAgentContract } from "../shared/agent-contract.ts";
 import { initialToolBudgetState, toolBudgetState } from "../shared/tool-budget.ts";
 import { resolveWatchdogConfig } from "../../watchdog/settings.ts";
 import { agentDefinitionDigest, launchBindingDigest } from "../../shared/launch-contract.ts";
@@ -109,7 +112,7 @@ import {
 	type ChildWatchdogStateSnapshot,
 	type ChildWatchdogStatusEvent,
 } from "../../watchdog/child-status.ts";
-import { buildInProcessChildLaunch } from "../shared/child-launch.ts";
+import { buildInProcessChildLaunch, createReportedChildSessionInput } from "../shared/child-launch.ts";
 import { childSessionFactory, projectChildSessionEventForJson, type ChildSession, type ChildSessionEvent } from "../shared/child-session.ts";
 
 const artifactOutputByResult = new WeakMap<SingleResult, string>();
@@ -340,6 +343,7 @@ function structuredDelegationProgressChanged(
 
 const AFTER_COMPACTION_SETTLEMENT = Symbol("afterCompactionSettlement");
 type AbortRecoverySingleResult = SingleResult & { [AFTER_COMPACTION_SETTLEMENT]?: true };
+const settledReadonlySource = new WeakMap<SingleResult, ChildSession>();
 
 const STOPPED_BEFORE_COMPLETION_ERROR = "Subagent stopped before completion.";
 
@@ -353,6 +357,7 @@ async function runSingleAttempt(
 	shared: {
 		sessionEnabled: boolean;
 		systemPrompt: string;
+		acceptancePrompt: string;
 		resolvedSkillNames?: string[];
 		modelCandidates?: string[];
 		skillsWarning?: string;
@@ -365,6 +370,9 @@ async function runSingleAttempt(
 		orcaProgressTab?: OrcaProgressTab;
 		launchWarnings: { emitted: boolean };
 		verifyModel: boolean;
+		readonlyExpected?: SettledReadonlyEvidence;
+		readonlyModel?: string;
+		readonlyHandoffAllowed?: () => boolean;
 	},
 ): Promise<SingleResult> {
 	const effectiveThinking = options.thinkingOverride ?? agent.thinking;
@@ -405,7 +413,8 @@ async function runSingleAttempt(
 		allowNestedSubagents: agent.allowNestedSubagents,
 		extensions: agent.extensions,
 		subagentOnlyExtensions: agent.subagentOnlyExtensions,
-		systemPrompt: shared.systemPrompt,
+		// Exact terminal protocol belongs to session resources, not compactable history.
+		systemPrompt: shared.acceptancePrompt ? `${shared.systemPrompt}\n${shared.acceptancePrompt}` : shared.systemPrompt,
 		mcpDirectTools: agent.mcpDirectTools,
 		cwd: options.cwd ?? runtimeCwd,
 		intercomSessionName: options.intercomSessionName,
@@ -425,7 +434,8 @@ async function runSingleAttempt(
 		permissionRules,
 		permissionAuditPath,
 		childWatchdog,
-		watchdogStatus: (event) => onWatchdogStatus?.(event),
+		// registerChildWatchdog returns before reading the sink when no watchdog exists.
+		watchdogStatus: childWatchdog ? (event) => onWatchdogStatus?.(event) : undefined,
 		waitToolEnabled: options.waitToolEnabled,
 		waitToolDefaultTimeoutMs: options.waitToolDefaultTimeoutMs,
 		capabilityCeiling: options.capabilityCeiling,
@@ -780,7 +790,10 @@ async function runSingleAttempt(
 				// JSONL artifact flush is best effort.
 			});
 			// Report the run only after the child's extensions have shut down.
-			void Promise.resolve().then(() => session?.dispose()).catch(() => undefined).then(() => resolve(code));
+			void Promise.resolve().then(() => session?.dispose()).catch(() => undefined).then(() => {
+				if (session && getReadonlySessionEvidence(session)) settledReadonlySource.set(result, session);
+				resolve(code);
+			});
 		};
 
 		const drainPendingControlEvents = (): ControlEvent[] | undefined => {
@@ -1105,6 +1118,10 @@ async function runSingleAttempt(
 						}
 					}
 					if (evt.message.errorMessage) assistantError = evt.message.errorMessage;
+					else if (hasToolCall && evt.message.stopReason === "toolUse") {
+						// A recovered request can finish via a terminating tool, without a text stop.
+						assistantError = undefined;
+					}
 					const assistantText = extractTextFromContent(evt.message.content);
 					appendRecentOutput(progress, assistantText.split("\n").slice(-10));
 					// Final assistant message: start the settle drain window.
@@ -1352,12 +1369,10 @@ async function runSingleAttempt(
 
 		void (async () => {
 			try {
-				const created = await childSessions.create({
-					...launch.session,
-					onExtensionError: (error) => {
-						shared.transcriptWriter?.writeStderrLine(`Extension error (${error.extensionPath}, ${error.event}): ${error.error instanceof Error ? error.error.message : String(error.error)}`);
-					},
-				});
+				const input = createReportedChildSessionInput(launch, shared.transcriptWriter);
+				requestReadonlySessionEvidence(input, shared.readonlyExpected);
+				if (shared.readonlyHandoffAllowed && !shared.readonlyHandoffAllowed()) throw new Error("Read-only continuation handoff vetoed.");
+				const created = await childSessions.create(input);
 				if (lifecycleFinished) {
 					void created.dispose();
 					return;
@@ -1369,6 +1384,10 @@ async function runSingleAttempt(
 					abortChild();
 				}
 				options.onChildSession?.({ steer: (text) => created.steer(text), followUp: (text) => created.followUp(text) });
+				const actualReadonlyModel = shared.readonlyExpected && getReadonlyChildModels(created)?.current;
+				if (shared.readonlyExpected && (!actualReadonlyModel || actualReadonlyModel.fullId !== shared.readonlyModel
+					|| actualReadonlyModel.api !== shared.readonlyExpected.api || created.modelId !== shared.readonlyModel || abortedBySignal || interruptedByControl || result.timedOut
+					|| !shared.readonlyHandoffAllowed?.())) throw new Error("Read-only continuation handoff vetoed.");
 				await created.prompt(`Task: ${task}`);
 				settle(undefined);
 			} catch (error) {
@@ -1497,7 +1516,7 @@ async function runSingleAttempt(
 			? `${timeoutMessage}\n\n${result.timeoutRecovery.message}\n\nPartial output before timeout:\n${fullOutput}`
 			: `${timeoutMessage}\n\n${result.timeoutRecovery.message}`;
 	}
-	const completionGuardEnabled = isAgentContractV1(options.agentContract) ? agent.completionGuard === true : agent.completionGuard !== false;
+	const completionGuardEnabled = isAgentContract(options.agentContract) ? agent.completionGuard === true : agent.completionGuard !== false;
 	const completionGuard = ((result.exitCode === 0 && !result.error) || toolAvailabilityError) && completionGuardEnabled
 		? evaluateCompletionMutationGuard({
 			agent: agent.name,
@@ -1537,7 +1556,7 @@ async function runSingleAttempt(
 		mutationAttemptObserved,
 		mutationEvidence,
 		arbiterRescued,
-		agentContractV1: isAgentContractV1(options.agentContract),
+		agentContractEnabled: isAgentContract(options.agentContract),
 	});
 	if (completionEvidence.fileMutation) {
 		result.effects = {
@@ -1733,7 +1752,7 @@ async function runSyncCompletionInner(
 		dynamicGroup: options.acceptanceContext?.dynamicGroup,
 		agentContract: options.agentContract,
 	});
-	const acceptancePrompt = formatAcceptancePrompt(effectiveAcceptance, { reportOptional: isAgentContractV1(options.agentContract), structuredOutput: Boolean(options.structuredOutput?.acceptanceReportPath) });
+	const acceptancePrompt = formatAcceptancePrompt(effectiveAcceptance, { reportOptional: isAgentContract(options.agentContract), structuredOutput: Boolean(options.structuredOutput?.acceptanceReportPath) });
 	const taskWithAcceptance = acceptancePrompt ? `${task}\n${acceptancePrompt}` : task;
 	options.onEffectivePrompt?.(taskWithAcceptance);
 	const sessionEnabled = Boolean(options.sessionFile || options.sessionDir) || shareEnabled;
@@ -1884,19 +1903,33 @@ async function runSyncCompletionInner(
 	};
 	let lastResult: SingleResult | undefined;
 	const modelsToTry = candidates.length > 0 ? candidates : [undefined];
-	let abortRecoveryAttempted = false;
-	let nextAttemptTask = taskWithAcceptance;
+	let recoveryState: LogicalRecoveryState = "unused";
+	let readonlyExpected: SettledReadonlyEvidence | undefined;
+	let readonlyModel: string | undefined;
+	let readonlySource: ChildSession | undefined;
+	// Ordinary startup retries retain their per-attempt timeout. Only retained
+	// continuation uses the original logical deadline, never a renewed allowance.
+	const continuationDeadline = options.deadlineAt ?? (options.timeoutMs === undefined ? undefined : Date.now() + options.timeoutMs);
+	const readonlyHandoffAllowed = () => !options.signal?.aborted && !options.interruptSignal?.aborted
+		&& !intercomDetached && !detachedReason && !options.workflowChildPermitLaunch
+		&& options.usageBudget === undefined && options.toolBudget === undefined
+		&& (continuationDeadline === undefined || Date.now() < continuationDeadline)
+		&& (!readonlySource || getReadonlySessionEvidence(readonlySource) === readonlyExpected)
+		&& !readonlySource?.detached && !readonlySource?.shutDown;
+	let nextAttemptTask = task;
 	modelAttemptsLoop: for (let modelIndex = 0; modelIndex < modelsToTry.length; modelIndex++) {
 		const candidate = modelsToTry[modelIndex];
 		// The inner loop re-runs the same candidate at most once, for abort recovery.
 		for (;;) {
-			const recoveringAbort = abortRecoveryAttempted;
+			const recoveringAbort = recoveryState === "abort-recovery";
 			const attemptTask = nextAttemptTask;
 			const verifyModel = Boolean(candidate) && !(options.modelOverrideFromParent && modelIndex === 0);
 			const outputSnapshot = captureSingleOutputSnapshot(options.outputPath);
+			if (recoveryState === "readonly-continuation") attemptOptions.deadlineAt = continuationDeadline;
 			const result = await runSingleAttempt(runtimeCwd, agent, attemptTask, candidate, attemptOptions, {
 				sessionEnabled,
 				systemPrompt,
+				acceptancePrompt,
 				resolvedSkillNames: resolvedSkills.length > 0 ? resolvedSkills.map((skill) => skill.name) : undefined,
 				skillsWarning: missingSkills.length > 0 ? `Skills not found: ${missingSkills.join(", ")}` : undefined,
 				jsonlPath,
@@ -1911,6 +1944,9 @@ async function runSyncCompletionInner(
 				orcaProgressTab,
 				launchWarnings,
 				verifyModel,
+				readonlyExpected,
+				readonlyModel,
+				readonlyHandoffAllowed: readonlyExpected ? readonlyHandoffAllowed : undefined,
 			});
 			lastResult = result;
 			if (!recoveringAbort) {
@@ -1929,6 +1965,46 @@ async function runSyncCompletionInner(
 				usage: { ...result.usage },
 			};
 			modelAttempts.push(attempt);
+			// A consumed retained continuation is terminal even on a startup error or abort.
+			if (recoveryState === "readonly-continuation") break modelAttemptsLoop;
+			const source = settledReadonlySource.get(result);
+			const evidence = source && getReadonlySessionEvidence(source);
+			const models = source && getReadonlyChildModels(source);
+			// Deny non-text retained inputs, including unknown blocks. Count bytes once,
+			// not restored usage (the latter belongs to earlier attempts/runs).
+			const textOnly = evidence && (JSON.parse(evidence.contextJson) as Array<{ role: string; content: unknown }>).every((message) =>
+				typeof message.content === "string" || Array.isArray(message.content) && message.content.every((block) =>
+					block?.type === "text" || message.role === "assistant" && block?.type === "toolCall"));
+			const retainedBytes = evidence && models ? Buffer.byteLength(evidence.contextJson) + models.requestBytes : Infinity;
+			const resolvedCandidates = modelsToTry.map((reference, index) => index === modelIndex ? models?.current : reference ? models?.resolve(reference) : undefined);
+			const continuation = planReadonlyModelContinuation({
+				source, recoveryState, currentIndex: modelIndex,
+				candidates: resolvedCandidates.map((resolved, index) => {
+					// A conservative byte ceiling includes serialized history, actual system
+					// prompt/tools, framing/continuation headroom and full output allowance.
+					const required = resolved?.maxTokens ? retainedBytes + 4096 + resolved.maxTokens : Infinity;
+					return {
+						resolved: resolved?.api ? { provider: resolved.provider, model: resolved.id, api: resolved.api } : undefined,
+						tried: index <= modelIndex,
+						compatibility: textOnly && resolved?.input?.includes("text") && (resolved.contextWindow ?? 0) >= required ? "compatible" as const : "unknown" as const,
+					};
+				}),
+				lifecycleAllowsContinuation: !attemptSucceeded && readonlyHandoffAllowed() && !result.stopped && !result.detached && !result.interrupted && !result.timedOut,
+				effectsAllowContinuation: !result.structuredOutputFailed && !result.toolBudgetBlocked && !result.progress?.currentTool
+					&& !result.outputSaveError && (!result.effects?.fileMutation || result.effects.fileMutation.status === "not-applicable"),
+				budget: options.toolBudget ? "tool-budget-configured" : options.usageBudget ? "unknown" : "unconfigured",
+				knownContextOverflow: Boolean(result.contextOverflow || isContextOverflow(result.error)),
+			});
+			if (continuation.kind === "continue") {
+				recoveryState = continuation.recoveryState; // consume BEFORE any sibling creation
+				readonlyExpected = continuation.expected;
+				readonlySource = source;
+				readonlyModel = resolvedCandidates[continuation.candidateIndex]?.fullId;
+				nextAttemptTask = continuation.prompt;
+				attemptNotes.push(`[readonly-continuation] ${attempt.model} failed with HTTP 429 after read-only progress; continuing retained session once with ${readonlyModel}.`);
+				modelIndex = continuation.candidateIndex - 1;
+				continue modelAttemptsLoop;
+			}
 			if (!attemptSucceeded) {
 				const afterCompactionSettlement = (result as AbortRecoverySingleResult)[AFTER_COMPACTION_SETTLEMENT];
 				const abortRecovery = planAbortRecovery({
@@ -1936,7 +2012,7 @@ async function runSyncCompletionInner(
 					error: result.error,
 					processSignal: result.processSignal,
 					sessionAvailable: Boolean(options.sessionFile && existsSync(options.sessionFile)),
-					alreadyResumed: abortRecoveryAttempted,
+					alreadyResumed: recoveryState !== "unused",
 					stopped: result.stopped || result.detached || options.signal?.aborted,
 					interrupted: result.interrupted || intercomDetached || options.interruptSignal?.aborted,
 					timedOut: result.timedOut,
@@ -1948,7 +2024,7 @@ async function runSyncCompletionInner(
 					afterCompactionSettlement,
 				});
 				if (abortRecovery.action === "resume") {
-					abortRecoveryAttempted = true;
+					recoveryState = "abort-recovery";
 					nextAttemptTask = abortRecovery.prompt;
 					attemptNotes.push("[abort-recovery] provider/transport abort after useful progress; resuming the retained child session once.");
 					continue;
@@ -2059,7 +2135,7 @@ async function runSyncCompletionInner(
 					? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only", durable: result.savedOutputPath !== undefined }
 					: undefined,
 				cwd: options.cwd ?? runtimeCwd,
-				reportOptional: isAgentContractV1(options.agentContract),
+				reportOptional: isAgentContract(options.agentContract),
 				artifactsDir: options.artifactsDir,
 				runId: options.runId,
 				watchdog: result.watchdog,
@@ -2071,7 +2147,7 @@ async function runSyncCompletionInner(
 	}
 	const acceptanceFailure = acceptanceFailureMessage(result.acceptance);
 	stripAcceptanceReportsFromMessages(result.messages);
-	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.interrupted && !result.timedOut && !isAgentContractV1(options.agentContract)) {
+	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.interrupted && !result.timedOut && !isAgentContract(options.agentContract)) {
 		result.exitCode = 1;
 		if (result.savedOutputPath) {
 			result.finalOutput = finalizeSingleOutput({
@@ -2104,7 +2180,7 @@ async function runSyncCompletionInner(
 			result.progress.error = result.error;
 		}
 	}
-	if (isAgentContractV1(options.agentContract)) attachContractProjections(result);
+	if (isAgentContract(options.agentContract)) attachContractProjections(result);
 	redactResultPrompt(result);
 	try {
 		persistResultMetadata(result);
@@ -2149,7 +2225,7 @@ export async function runSync(
 ): Promise<SingleResult> {
 	// Capture the strict contract before consumer-owned objects can be mutated
 	// after a detached receipt is published.
-	const strictContract = isAgentContractV1(options.agentContract);
+	const strictContract = isAgentContract(options.agentContract);
 	let detachedReason: string | undefined;
 	let publishedReceipt: SingleResult | undefined;
 	let activeDetachAttempt: ((reason?: string) => boolean) | undefined;
@@ -2247,13 +2323,13 @@ export async function runSync(
 	});
 
 	let terminalCallbackInvoked = false;
-	void authoritativeCompletion.then((terminalResult) => {
+	void authoritativeCompletion.then(async (terminalResult) => {
 		if (!detachedReason || terminalCallbackInvoked) return;
 		terminalCallbackInvoked = true;
 		terminalResult.detached = undefined;
 		terminalResult.detachedReason = detachedReason;
 		try {
-			options.onDetachedExit?.(terminalResult);
+			await options.onDetachedExit?.(terminalResult);
 		} catch {
 			// The authoritative result has settled. Consumer callback failures are
 			// contained here; each consumer owns cleanup through its own finally block.