pi-subagents 0.45.1 → 0.45.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.45.2] - 2026-08-10
+
+### Fixed
+- Tell parents to revive resumable failed async runs before reporting failure or launching a replacement. Thanks to @Livan-pro for #938.
+- Persist the actual agent and session file for workflow children when they start so their sessions can resume after a parent restart. Thanks to @Livan-pro for #932.
+- Retry steering requests that remain pending after manual compaction and fail unresolved requests at shutdown. Thanks to @jtac for #933.
+- Omit undefined object fields from `workflowScript` return values so completed `runs.all` results are not discarded when callers include unsupported fields such as `status` (#930).
+- Keep child steering inbox `auto` requests queued between `agent_end` and `agent_settled` so settlement-time guidance is not sent as an idle prompt too early. Thanks to @jtac for #928.
+
 ## [0.45.1] - 2026-08-09
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.45.1",
+  "version": "0.45.2",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",

package/src/runs/background/resume-guidance.ts

@@ -0,0 +1,33 @@
+import * as fs from "node:fs";
+import type { AsyncRunSummary } from "./async-status.ts";
+
+export function formatAsyncReviveCommand(run: AsyncRunSummary): string | undefined {
+	const step = run.steps.find((candidate) => candidate.status === "failed" && candidate.sessionFile && fs.existsSync(candidate.sessionFile));
+	if (!step) {
+		if (run.steps.length === 1 && run.sessionFile && fs.existsSync(run.sessionFile)) {
+			return `subagent({ action: "resume", id: "${run.id}", message: "Continue from the persisted child session and report the result." })`;
+		}
+		return undefined;
+	}
+	const index = run.steps.length === 1 ? "" : `, index: ${step.index}`;
+	return `subagent({ action: "resume", id: "${run.id}"${index}, message: "Continue from the persisted child session and report the result." })`;
+}
+
+export function formatResumeFirstFailedRunDetail(run: AsyncRunSummary): string | undefined {
+	if (run.state !== "failed") return undefined;
+	const command = formatAsyncReviveCommand(run);
+	if (!command) return undefined;
+	return `Resume-first: failed run "${run.id}" has a persisted child session. Revive the original run with ${command} before reporting failure or launching a replacement. Launch a replacement only if revive fails or the user explicitly asks for one.`;
+}
+
+export function formatResumeFirstFailedRunsNote(runs: AsyncRunSummary[]): string {
+	const resumable = runs
+		.filter((run) => run.state === "failed")
+		.map((run) => ({ run, command: formatAsyncReviveCommand(run) }))
+		.filter((entry): entry is { run: AsyncRunSummary; command: string } => Boolean(entry.command));
+	if (resumable.length === 0) return "";
+	const guidance = resumable.length === 1
+		? `failed run "${resumable[0]!.run.id}" has a persisted child session. Revive the original run with ${resumable[0]!.command}`
+		: `${resumable.length} failed runs have persisted child sessions. Inspect status and revive each original run before retrying`;
+	return ` Resume-first: ${guidance} before reporting failure or launching a replacement. Launch a replacement only if revive fails or the user explicitly asks for one.`;
+}

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

@@ -62,6 +62,7 @@ import {
 } from "../../shared/types.ts";
 import { formatDuration, shortenPath } from "../../shared/formatters.ts";
 import { collectWaitCompletions } from "./wait-completions.ts";
+import { formatResumeFirstFailedRunsNote } from "./resume-guidance.ts";
 export { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from "./wait-config.ts";
 
 /** States that mean a run is still in flight (not yet resolved). */
@@ -604,6 +605,7 @@ export async function waitForSubagents(
 	let finishedAsyncCount: number;
 	let failedAsyncCount: number;
 	let completions: WaitCompletion[] | undefined;
+	let resumeGuidance = "";
 	const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
 	const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
 	try {
@@ -612,6 +614,7 @@ export async function waitForSubagents(
 		finishedAsyncCount = terminal.length;
 		failedAsyncCount = terminal.filter((run) => run.state === "failed").length;
 		terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
+		resumeGuidance = formatResumeFirstFailedRunsNote(terminal);
 		completions = collectWaitCompletions(terminal, deps.state, deps.resultsDir ?? DIRS.results);
 	} catch (error) {
 		return result(error instanceof Error ? error.message : String(error), true);
@@ -637,7 +640,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}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
+			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
 			deps.failOnFailedRuns === true && failedAsyncCount > 0,
 			completions,
 		);
@@ -654,7 +657,7 @@ export async function waitForSubagents(
 		? `${relevantAttention.length} of ${initialCount} ${subject} need attention`
 		: `${finishedCount} of ${initialCount} ${subject} finished`;
 	return result(
-		`Waited ${elapsed}; ${progress}.${outcome}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
+		`Waited ${elapsed}; ${progress}.${outcome}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
 		deps.failOnFailedRuns === true && failedAsyncCount > 0,
 		completions,
 	);

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

@@ -2,7 +2,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { listAsyncRuns } from "./async-status.ts";
+import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
+import { formatResumeFirstFailedRunDetail } from "./resume-guidance.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import {
 	DIRS,
@@ -61,7 +62,7 @@ function parseRecord(value: unknown): WaitSubscriptionRecord | undefined {
 	return record as WaitSubscriptionRecord;
 }
 
-function needsAttention(run: ReturnType<typeof listAsyncRuns>[number]): boolean {
+function needsAttention(run: AsyncRunSummary): boolean {
 	return run.activityState === "needs_attention" || run.steps.some((step) => step.activityState === "needs_attention");
 }
 
@@ -166,7 +167,7 @@ export function createWaitSubscriptionManager(
 			return;
 		}
 		if (run.state !== "queued" && run.state !== "running") {
-			settle(record, run.state === "complete" ? "completed" : run.state, "Inspect the run status for its final output.");
+			settle(record, run.state === "complete" ? "completed" : run.state, formatResumeFirstFailedRunDetail(run) ?? "Inspect the run status for its final output.");
 		}
 	};
 

package/src/runs/foreground/subagent-executor.ts

@@ -3942,6 +3942,8 @@ function duplicateSubagentCallResult(params: SubagentParamsLike): AgentToolResul
 	};
 }
 
+const workflowLaunchObservers = new WeakMap<object, (launch: { agent: string; sessionFile?: string }) => void>();
+
 function workflowChildResult(key: string, result: AgentToolResult<Details>): WorkflowScriptChildResult {
 	const receiptOutput = result.content.map((part) => part.type === "text" ? part.text : "").filter(Boolean).join("\n");
 	const output = result.details.results.length === 1 && result.details.results[0]?.finalOutput !== undefined
@@ -4159,6 +4161,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		ctx: ExtensionContext,
 		preserveActiveSession = false,
 	): Promise<AgentToolResult<Details>> => {
+		const workflowLaunchObserver = workflowLaunchObservers.get(params);
 		const delegatedThinkingOverride = delegatedThinkingOverrides.get(params);
 		const allowZeroToolBudget = delegatedZeroToolBudgets.has(params);
 		if (!preserveActiveSession) deps.state.baseCwd = ctx.cwd;
@@ -4349,6 +4352,13 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 								if (budgetState?.exhausted) return workflowChildResult(key, buildRequestedModeError(childParams as SubagentParamsLike, usageBudgetExceededMessage(budgetState)));
 								patchMissionObjective(childParams.task);
 								const childRequest = prepareWorkflowLaunchParams(workflowChildDefaults, childParams, workflowRunId, key, { missionDetached: detachWorkflowChildMissions });
+								workflowLaunchObservers.set(childRequest, (launch) => {
+									const step = status.steps?.find((candidate) => candidate.workflowKey === key);
+									if (!step) return;
+									step.agent = launch.agent;
+									step.sessionFile = launch.sessionFile;
+									persist();
+								});
 								const result = await execute(randomUUID(), childRequest, workflowSignal, (update) => {
 									const progress = update.details.progress?.[0];
 									const step = status.steps?.find((candidate) => candidate.workflowKey === key);
@@ -5421,6 +5431,18 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 
 		let nestedForegroundStarted = false;
 		try {
+			if (workflowLaunchObserver) {
+				const singleTask = hasTasks && effectiveParams.tasks?.length === 1 ? effectiveParams.tasks[0] : undefined;
+				const launch = hasSingle
+					? { agent: effectiveParams.agent!, sessionFile: childSessionFileForTask(effectiveParams.agent!, 0, effectiveParams.model) }
+					: singleTask
+						? { agent: singleTask.agent, sessionFile: childSessionFileForTask(singleTask.agent, 0, singleTask.model) }
+						: undefined;
+				if (launch) {
+					workflowLaunchObservers.delete(params);
+					workflowLaunchObserver(launch);
+				}
+			}
 			const asyncResult = runAsyncPath(execData, deps);
 			if (asyncResult) return attachMission(withResolvedContext(withForkThinkingNotes(asyncResult, forkThinkingDowngrades), contextPolicy.contextSummary));
 			if (foregroundControl) {

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -30,6 +30,7 @@ import { drainOutstandingWork } from "../background/auto-drain.ts";
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
 export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
+const STEERING_LEGACY_SETTLE_FALLBACK_MS = 1000;
 
 const STRUCTURED_OUTPUT_INSTRUCTIONS = [
 	"This subagent step has a strict structured output contract.",
@@ -330,7 +331,7 @@ function registerToolBudget(pi: ExtensionAPI, budget: ResolvedToolBudget | undef
 
 export function registerSteeringInbox(
 	pi: ExtensionAPI,
-	deps: { watch?: typeof fs.watch; nativeRealpath?: (filePath: string) => string } = {},
+	deps: { watch?: typeof fs.watch; nativeRealpath?: (filePath: string) => string; legacySettleFallbackMs?: number } = {},
 ): void {
 	const steerInbox = process.env[SUBAGENT_STEER_INBOX_ENV]?.trim();
 	if (!steerInbox) return;
@@ -343,11 +344,14 @@ export function registerSteeringInbox(
 	let disposed = false;
 	let agentRunning = false;
 	let inTurn = false;
+	let awaitingSettlement = false;
 	let flushing = false;
 	let started = false;
 	let canSteer = typeof sendUserMessage === "function";
 	let watcher: fs.FSWatcher | undefined;
 	let interval: NodeJS.Timeout | undefined;
+	let settleFallback: NodeJS.Timeout | undefined;
+	const legacySettleFallbackMs = deps.legacySettleFallbackMs ?? STEERING_LEGACY_SETTLE_FALLBACK_MS;
 	const acknowledge = (request: SteerRequest, state: "delivered" | "queued" | "failed", message: string, deliveryStatus?: SteerDeliveryStatus): void => {
 		if (!ackDir || !Number.isInteger(childIndex) || childIndex < 0) return;
 		writeSteerAckAt(steerAckPathFromDir(ackDir, request.id), {
@@ -375,7 +379,8 @@ export function registerSteeringInbox(
 					continue;
 				}
 				const requestedMode = request.mode ?? "steer";
-				const delivery = requestedMode === "follow_up" || (requestedMode === "auto" && inTurn) ? "followUp" as const : "steer" as const;
+				const autoCanUseIdle = requestedMode === "auto" && !agentRunning && !awaitingSettlement;
+				const delivery = requestedMode === "follow_up" || (requestedMode === "auto" && (inTurn || awaitingSettlement)) ? "followUp" as const : "steer" as const;
 				const pendingFollowUps = [...pending.values()].reduce((count, entries) => count + entries.filter((entry) => entry.deliveryStatus === "queued").length, 0);
 				if (delivery === "followUp" && queued.length + pendingFollowUps >= MAX_STEER_QUEUE_SIZE) {
 					acknowledge(request, "failed", `Follow-up queue is full (${MAX_STEER_QUEUE_SIZE} messages).`);
@@ -386,7 +391,7 @@ export function registerSteeringInbox(
 				entries.push({ request, deliveryStatus: delivery === "followUp" ? "queued" : "delivered" });
 				pending.set(formatted, entries);
 				try {
-					sendUserMessage(formatted, requestedMode === "auto" && !agentRunning ? undefined : { deliverAs: delivery });
+					sendUserMessage(formatted, autoCanUseIdle ? undefined : { deliverAs: delivery });
 				} catch (error) {
 					entries.pop();
 					if (entries.length === 0) pending.delete(formatted);
@@ -440,14 +445,71 @@ export function registerSteeringInbox(
 		flush();
 		return undefined;
 	};
+	const clearSettleFallback = (): void => {
+		if (!settleFallback) return;
+		clearTimeout(settleFallback);
+		settleFallback = undefined;
+	};
+	const markSettled = (): undefined => {
+		clearSettleFallback();
+		agentRunning = false;
+		inTurn = false;
+		awaitingSettlement = false;
+		return activate();
+	};
+	const armLegacySettleFallback = (): void => {
+		clearSettleFallback();
+		settleFallback = setTimeout(() => {
+			settleFallback = undefined;
+			if (disposed || !awaitingSettlement) return;
+			agentRunning = false;
+			inTurn = false;
+			awaitingSettlement = false;
+			activate();
+		}, legacySettleFallbackMs);
+		settleFallback.unref?.();
+	};
 
 	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown, ctx?: unknown) => unknown) => void;
 	// Register input before the watcher so an accepted extension input cannot race request dispatch.
 	onRuntimeEvent("input", onInput);
 	onRuntimeEvent("session_start", () => start());
-	onRuntimeEvent("agent_start", () => { agentRunning = true; return activate(); });
-	onRuntimeEvent("agent_end", () => { agentRunning = false; inTurn = false; return activate(); });
+	onRuntimeEvent("agent_start", () => {
+		clearSettleFallback();
+		agentRunning = true;
+		awaitingSettlement = false;
+		return activate();
+	});
+	onRuntimeEvent("agent_end", (event) => {
+		inTurn = false;
+		if ((event as { willRetry?: unknown } | undefined)?.willRetry === true) {
+			clearSettleFallback();
+			agentRunning = true;
+			awaitingSettlement = true;
+			return activate();
+		}
+		agentRunning = true;
+		awaitingSettlement = true;
+		armLegacySettleFallback();
+		return activate();
+	});
+	onRuntimeEvent("agent_settled", markSettled);
+	onRuntimeEvent("session_compact", () => {
+		const unresolved = [...pending.values()].flat();
+		pending.clear();
+		for (const entry of unresolved) {
+			try {
+				writeSteerRequestToDir(steerInbox, { ...entry.request, mode: "follow_up" });
+			} catch (error) {
+				acknowledge(entry.request, "failed", `Could not retry steering after compaction: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		return activate();
+	});
 	onRuntimeEvent("turn_start", () => {
+		clearSettleFallback();
+		agentRunning = true;
+		awaitingSettlement = false;
 		inTurn = true;
 		const next = queued.findIndex((entry) => entry.ready);
 		if (next >= 0) {
@@ -466,7 +528,11 @@ export function registerSteeringInbox(
 	}
 	onRuntimeEvent("session_shutdown", () => {
 		for (const entry of queued) acknowledge(entry.request, "failed", "Run ended before queued follow-up delivery.", "queued");
+		for (const entries of pending.values()) {
+			for (const entry of entries) acknowledge(entry.request, "failed", "Run ended before Pi confirmed steering input delivery.");
+		}
 		disposed = true;
+		clearSettleFallback();
 		try { watcher?.close(); } catch {}
 		if (interval) clearInterval(interval);
 	});

package/src/workflows/scripted-workflow.ts

@@ -139,6 +139,25 @@ function assertJsonValue(value, path = "emit", seen = new Set()) {
   seen.delete(value);
 }
 
+function isPlainWorkflowObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype || prototype === contextObjectPrototype;
+}
+
+function omitUndefinedWorkflowValues(value, seen = new Set()) {
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  const normalized = Array.isArray(value)
+    ? value.map((entry) => entry === undefined ? null : omitUndefinedWorkflowValues(entry, seen))
+    : isPlainWorkflowObject(value) && Object.getOwnPropertySymbols(value).length === 0
+      ? Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => entry === undefined ? [] : [[key, omitUndefinedWorkflowValues(entry, seen)]]))
+      : value;
+  seen.delete(value);
+  return normalized;
+}
+
 parentPort.on("message", async (message) => {
   if (message.type === "response") {
     const entry = pending.get(message.callId);
@@ -163,7 +182,7 @@ parentPort.on("message", async (message) => {
       return;
     }
     const value = await compiled.runInContext(context);
-    const persistedValue = value === undefined ? null : value;
+    const persistedValue = value === undefined ? null : omitUndefinedWorkflowValues(value);
     assertJsonValue(persistedValue, "return");
     parentPort.postMessage({ type: "complete", value: persistedValue });
   } catch (error) {