pi-subagents 0.42.1 → 0.44.0

package/src/runs/background/run-status.ts

@@ -382,6 +382,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			const workflowEmitPreview = status.workflow?.emits.length ? formatWorkflowJsonPreview(status.workflow.emits.at(-1), 240) : undefined;
 			const lines = [
 				`Run: ${status.runId}`,
+				status.toolCallId ? `Tool call: ${status.toolCallId}` : undefined,
 				missionId ? `Mission: ${missionId}` : undefined,
 				`State: ${status.state}`,
 				processTerminal ? `Process terminal: ${processTerminal.state}${processTerminal.reason ? ` (${processTerminal.reason})` : ""}` : undefined,
@@ -454,7 +455,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 	if (resultPath) {
 		try {
 			const raw = fs.readFileSync(resultPath, "utf-8");
-			const data = JSON.parse(raw) as { id?: string; runId?: string; agent?: string; success?: boolean; summary?: string; output?: string; exitCode?: number; state?: string; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; processSignal?: string | null; sessionFile?: string; parallelHandoff?: { path?: string }; results?: Array<{ agent?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; interrupted?: boolean; processSignal?: string | null }> };
+			const data = JSON.parse(raw) as { id?: string; runId?: string; toolCallId?: string; agent?: string; success?: boolean; summary?: string; output?: string; exitCode?: number; state?: string; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; processSignal?: string | null; sessionFile?: string; parallelHandoff?: { path?: string }; results?: Array<{ agent?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; interrupted?: boolean; processSignal?: string | null }> };
 			if (params.view === "transcript") {
 				try {
 					return { content: [{ type: "text", text: formatAsyncResultTranscript(data, resultPath, { index: params.index, lines: params.lines }) }], details: { mode: "single", results: [] } };
@@ -479,7 +480,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				? "stopped"
 				: data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
 			const runId = data.runId ?? data.id ?? resolvedId;
-			const lines = [`Run: ${runId}`, `State: ${status}`, `Result: ${resultPath}`];
+			const lines = [`Run: ${runId}`, data.toolCallId ? `Tool call: ${data.toolCallId}` : undefined, `State: ${status}`, `Result: ${resultPath}`].filter((line): line is string => Boolean(line));
 			if (data.parallelHandoff?.path) lines.push(`Parallel handoff: ${data.parallelHandoff.path}`);
 			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
 			lines.push(formatResumeGuidance(runId, children, data.sessionFile, { stopped: status === "stopped" }));

package/src/runs/background/scheduled-runs.ts

@@ -9,6 +9,7 @@ import type { AsyncStatus, Details, ExtensionConfig } from "../../shared/types.t
 import type { SubagentParamsLike } from "../foreground/subagent-executor.ts";
 import { validateExecutionAcceptance } from "../shared/acceptance.ts";
 import type { ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
+import { previewSimpleWorkflowRun } from "../../workflows/scripted-workflow.ts";
 
 export const SCHEDULED_RUN_ACTIONS = [
 	"schedule.create",
@@ -34,7 +35,7 @@ export type ScheduleRunState = "running" | "skipped" | "missed" | "completed" |
 export type ScheduleTrigger =
 	| { kind: "once"; at: string; nextRunAt?: string }
 	| { kind: "interval"; every: string; everyMs: number; anchorAt: string; nextRunAt: string };
-export type ScheduleTarget = { workflowScript: string } | { agent: string; task?: string };
+export type ScheduleTarget = { workflowScript: string };
 
 export interface ScheduleRecord {
 	schemaVersion: 1;
@@ -188,6 +189,14 @@ function readJson(file: string, label: string): unknown {
 	}
 }
 
+function parseScheduleTarget(value: unknown, file: string): ScheduleTarget {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Schedule record '${file}' has invalid trigger or target.`);
+	const target = value as { workflowScript?: unknown; agent?: unknown; task?: unknown };
+	if (typeof target.workflowScript === "string" && target.workflowScript.trim()) return { workflowScript: target.workflowScript.trim() };
+	if (target.agent !== undefined || target.task !== undefined) throw new Error(`Schedule record '${file}' uses a removed legacy agent target; recreate it with target.workflowScript.`);
+	throw new Error(`Schedule record '${file}' requires a workflowScript target.`);
+}
+
 function parseSchedule(value: unknown, file: string): ScheduleRecord {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Schedule record '${file}' must be a JSON object.`);
 	const record = value as Partial<ScheduleRecord>;
@@ -200,10 +209,7 @@ function parseSchedule(value: unknown, file: string): ScheduleRecord {
 	} else if (record.trigger.kind === "interval") {
 		if (typeof record.trigger.every !== "string" || typeof record.trigger.everyMs !== "number" || typeof record.trigger.anchorAt !== "string" || typeof record.trigger.nextRunAt !== "string") throw new Error(`Schedule record '${file}' has an invalid interval trigger.`);
 	} else throw new Error(`Schedule record '${file}' has an unsupported trigger.`);
-	const workflow = "workflowScript" in record.target && typeof record.target.workflowScript === "string";
-	const agent = "agent" in record.target && typeof record.target.agent === "string";
-	if (workflow === agent) throw new Error(`Schedule record '${file}' has an invalid target.`);
-	return record as ScheduleRecord;
+	return { ...record, target: parseScheduleTarget(record.target, file) } as ScheduleRecord;
 }
 
 class ScheduleStore {
@@ -304,27 +310,25 @@ function textResult(text: string, schedules?: ScheduleRecord[], runs?: ScheduleR
 }
 
 function targetLabel(target: ScheduleTarget): string {
-	return "workflowScript" in target ? "workflowScript" : `agent ${target.agent}`;
+	const preview = previewSimpleWorkflowRun(target.workflowScript);
+	return preview?.agent ? `workflowScript -> agent ${preview.agent}` : "workflowScript (dynamic)";
 }
 
 function sanitizeTarget(params: SubagentParamsLike): { target?: ScheduleTarget; error?: string } {
-	if (params.tasks || params.chain) return { error: "Recurring schedules support workflowScript or one agent/task target, not legacy tasks or chain inputs." };
-	const hasWorkflow = typeof params.workflowScript === "string" && params.workflowScript.trim().length > 0;
-	const hasAgent = typeof params.agent === "string" && params.agent.trim().length > 0;
-	if (hasWorkflow === hasAgent) return { error: "schedule.create requires exactly one target: workflowScript or agent with optional task." };
+	if (params.tasks || params.chain) return { error: "Recurring schedules require workflowScript; legacy tasks and chain inputs are unsupported." };
+	if (params.agent !== undefined || params.task !== undefined) return { error: "schedule.create requires workflowScript. Use workflowScript: \"return runs.run('main', { agent, task })\"." };
+	if (typeof params.workflowScript !== "string" || !params.workflowScript.trim()) return { error: "schedule.create requires a non-empty workflowScript." };
 	if (params.context === "fork") return { error: "Scheduled runs require fresh context." };
 	if (params.async === false) return { error: "Scheduled runs are always async." };
-	if (params.clarify === true) return { error: "Scheduled runs cannot open clarify UI." };
 	const acceptanceErrors = validateExecutionAcceptance(params as Parameters<typeof validateExecutionAcceptance>[0]);
 	if (acceptanceErrors.length) return { error: acceptanceErrors.join(" ") };
-	return hasWorkflow ? { target: { workflowScript: params.workflowScript!.trim() } } : { target: { agent: params.agent!.trim(), ...(params.task === undefined ? {} : { task: params.task }) } };
+	return { target: { workflowScript: params.workflowScript.trim() } };
 }
 
 function executionParams(schedule: ScheduleRecord): SubagentParamsLike {
 	return {
 		...schedule.target,
 		async: true,
-		clarify: false,
 		context: "fresh",
 		cwd: schedule.cwd,
 		mission: false,

package/src/runs/background/steering.ts

@@ -47,7 +47,7 @@ export function recordSteeringRequest(
 
 function incrementStateCount(status: SteeringStatus, state: SteeringTargetState): void {
 	if (state === "scheduled") status.scheduled++;
-	else if (state === "routed") status.pending++;
+	else if (state === "routed" || state === "queued") status.pending++;
 	else if (state === "delivered" || state === "late") status.delivered++;
 	else if (state === "failed") status.failed++;
 	else if (state === "recovered") status.recovered++;
@@ -81,7 +81,7 @@ export function updateSteeringTarget(
 		if (fields.replacementRunId) target.replacementRunId = fields.replacementRunId;
 		return target;
 	}
-	if (target.state === "routed" && state !== "routed") status.pending = Math.max(0, status.pending - 1);
+	if ((target.state === "routed" || target.state === "queued") && state !== "routed" && state !== "queued") status.pending = Math.max(0, status.pending - 1);
 	target.state = state;
 	if (state === "routed") target.routedAt = now;
 	if (state === "delivered") {
@@ -123,16 +123,18 @@ export function actionResultFromSteeringStatus(status: SteeringStatus, sourceRun
 	else if (states.length > 0 && states.every((candidate) => candidate === "failed" || candidate === "late")) state = "failed";
 	else if (states.some((candidate) => candidate === "failed" || candidate === "late") && states.some((candidate) => candidate !== "failed" && candidate !== "late")) state = "partial";
 	const effectiveReplacementRunId = replacementRunId ?? request.targets.find((target) => target.replacementRunId)?.replacementRunId;
-	return { requestId, state, sourceRunId, ...(effectiveReplacementRunId ? { replacementRunId: effectiveReplacementRunId } : {}), targets };
+	const deliveryStatus = states.length > 0 && states.every((candidate) => candidate === "delivered" || candidate === "recovered") ? "delivered" as const : "queued" as const;
+	return { requestId, state, deliveryStatus, sourceRunId, ...(effectiveReplacementRunId ? { replacementRunId: effectiveReplacementRunId } : {}), targets };
 }
 
 export function steeringActionIsTerminal(result: SteerActionResult | undefined): boolean {
-	return result?.state === "delivered" || result?.state === "scheduled" || result?.state === "partial" || result?.state === "recovered" || result?.state === "failed";
+	return (result?.targets.length ?? 0) > 0 && result?.targets.every((target) => target.state === "queued" || target.state === "delivered") === true
+		|| result?.state === "delivered" || result?.state === "scheduled" || result?.state === "partial" || result?.state === "recovered" || result?.state === "failed";
 }
 
 export function terminalSteeringNoticeState(status: SteeringStatus, requestId: string): "failed" | "partial" | undefined {
 	const request = status.recent.find((candidate) => candidate.id === requestId);
-	if (!request || request.targets.some((target) => target.state === "routed" || target.state === "scheduled")) return undefined;
+	if (!request || request.targets.some((target) => target.state === "routed" || target.state === "queued" || target.state === "scheduled")) return undefined;
 	const hasSuccess = request.targets.some((target) => target.state === "delivered" || target.state === "recovered");
 	const hasFailure = request.targets.some((target) => target.state === "failed" || target.state === "late");
 	if (hasSuccess && hasFailure) return "partial";

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

@@ -69,7 +69,7 @@ import {
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
 import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
 import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
-import { createStructuredOutputRuntime, readStructuredOutput } from "../shared/structured-output.ts";
+import { createStructuredOutputRuntime, MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput } from "../shared/structured-output.ts";
 import { formatProcessSignalError, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
@@ -503,6 +503,8 @@ interface RunPiStreamingResult {
 	toolBudget?: ToolBudgetState;
 	toolBudgetBlocked?: boolean;
 	observedMutationAttempt?: boolean;
+	structuredOutputToolInvoked?: boolean;
+	structuredOutputMessageStartIndex?: number;
 	watchdog?: ChildWatchdogStateSnapshot;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
 	processInstanceId: string;
@@ -568,6 +570,8 @@ function runPiStreaming(
 		let turnBudgetMessage: string | undefined;
 		let turnBudget: TurnBudgetState | undefined;
 		let observedMutationAttempt = false;
+		let structuredOutputToolInvoked = false;
+		let structuredOutputMessageStartIndex: number | undefined;
 		let toolCount = 0;
 		const childWatchdogConfig = decodeChildWatchdogConfig(env?.[CHILD_WATCHDOG_CONFIG_ENV]);
 		let childWatchdogState: ChildWatchdogStateSnapshot | undefined;
@@ -658,6 +662,10 @@ function runPiStreaming(
 
 			if (event.type === "tool_execution_start" && event.toolName) {
 				toolCount += 1;
+				if (event.toolName === "structured_output") {
+					structuredOutputToolInvoked = true;
+					structuredOutputMessageStartIndex = messages.length;
+				}
 				observedMutationAttempt = observedMutationAttempt || isMutatingTool(event.toolName, event.args);
 				const toolArgs = extractToolArgsPreview(event.args ?? {});
 				writeOutputLine(toolArgs ? `${event.toolName}: ${toolArgs}` : event.toolName);
@@ -923,6 +931,8 @@ function runPiStreaming(
 				turnBudgetExceeded,
 				wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined,
 				observedMutationAttempt,
+				structuredOutputToolInvoked,
+				structuredOutputMessageStartIndex,
 				watchdog: childWatchdogState,
 				processInstanceId,
 				processCloseObservedAt,
@@ -949,7 +959,7 @@ function runPiStreaming(
 			const stderr = stderrTail.text();
 			const finalOutput = getFinalOutput(messages) || rawStdoutTail.text().trim();
 			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, watchdog: childWatchdogState, processInstanceId }));
+			resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, structuredOutputToolInvoked, structuredOutputMessageStartIndex, watchdog: childWatchdogState, processInstanceId }));
 		});
 	});
 }
@@ -1444,31 +1454,42 @@ async function runSingleStep(
 		const runtimeAcknowledgedExtensions = readRuntimeAcknowledgedExtensions(runtimeAcknowledgedExtensionsPath);
 		cleanupTempDir(tempDir);
 
-		const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError ? detectSubagentError(run.messages) : null;
-		const missingStructuredOutput = effectiveStructuredOutput
-			? !fs.existsSync(effectiveStructuredOutput.outputPath)
-			: false;
+		let structuredOutput: unknown;
+		let structuredError: string | undefined;
+		let validatedStructuredOutput = false;
+		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError) {
+			if (!run.structuredOutputToolInvoked) {
+				structuredError = MISSING_STRUCTURED_OUTPUT_CALL_ERROR;
+			} else {
+				const structured = await readStructuredOutput({
+					schema: effectiveStructuredOutput.schema,
+					schemaPath: effectiveStructuredOutput.schemaPath,
+					outputPath: effectiveStructuredOutput.outputPath,
+				});
+				if (structured.error) structuredError = structured.error;
+				else {
+					structuredOutput = structured.value;
+					validatedStructuredOutput = true;
+				}
+			}
+		}
+		const errorMessages = validatedStructuredOutput
+			? run.messages.slice(run.structuredOutputMessageStartIndex ?? run.messages.length)
+			: run.messages;
+		const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError
+			? detectSubagentError(errorMessages)
+			: null;
 		const emptyOutputError = run.exitCode === 0
 			&& !run.error
 			&& !toolAvailabilityError
+			&& !structuredError
 			&& !run.finalOutput.trim()
-			&& (!effectiveStructuredOutput || missingStructuredOutput)
+			&& !validatedStructuredOutput
 			&& (!hiddenError?.hasError || hasEmptyTerminalAssistantResponse(run.messages))
 			? "Subagent produced no output (possible model cold-start or empty response)."
 			: undefined;
-		let structuredOutput: unknown;
-		let structuredError: string | undefined;
-		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError && !hiddenError?.hasError && !emptyOutputError) {
-			const structured = await readStructuredOutput({
-				schema: effectiveStructuredOutput.schema,
-				schemaPath: effectiveStructuredOutput.schemaPath,
-				outputPath: effectiveStructuredOutput.outputPath,
-			});
-			if (structured.error) structuredError = structured.error;
-			else structuredOutput = structured.value;
-		}
 		const completionGuardEnabled = isAgentContractV1(step.agentContract) ? step.completionGuard === true : step.completionGuard !== false;
-		const completionGuard = run.exitCode === 0 && !run.error && !toolAvailabilityError && !hiddenError?.hasError && !emptyOutputError && completionGuardEnabled
+		const completionGuard = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError && !hiddenError?.hasError && !emptyOutputError && completionGuardEnabled
 			? evaluateCompletionMutationGuard(omitUndefinedProperties({
 				agent: step.agent,
 				task: taskForCompletionGuard,
@@ -1635,6 +1656,8 @@ async function runSingleStep(
 			signal: combinedAbortSignal([ctx.timeoutSignal, ctx.stopSignal]),
 			abortMessage: ctx.stopSignal?.aborted ? ctx.stopMessage ?? "Subagent stopped by user." : ctx.timeoutMessage ?? "Subagent timed out.",
 			reportOptional: isAgentContractV1(step.agentContract),
+			artifactsDir: ctx.artifactsDir,
+			runId: ctx.id,
 		}))
 		: undefined;
 	const stoppedAfterAcceptance = finalResult?.stopped === true || ctx.stopSignal?.aborted === true;
@@ -2611,7 +2634,10 @@ async function runSubagent(
 		const now = Date.now();
 		if (ack.state === "delivered") {
 			updateSteeringLifecycleTarget(ack.requestId, ack.index, late ? "late" : "delivered", now, omitUndefinedProperties({ reason: late ? "acknowledged after recovery commit" : undefined }));
-			emitSteeringEvent("subagent.steer.delivered", { type: "steer", id: ack.requestId, ts: now, message: ack.message }, ack.index, { late, message: ack.message });
+			emitSteeringEvent("subagent.steer.delivered", { type: "steer", id: ack.requestId, ts: now, message: ack.message }, ack.index, { late, deliveryStatus: "delivered", message: ack.message });
+		} else if (ack.state === "queued") {
+			updateSteeringLifecycleTarget(ack.requestId, ack.index, "queued", now);
+			emitSteeringEvent("subagent.steer.queued", { type: "steer", id: ack.requestId, ts: now, message: ack.message }, ack.index, { deliveryStatus: "queued", message: ack.message });
 		} else {
 			markSteeringAttention(ack.index);
 			updateSteeringLifecycleTarget(ack.requestId, ack.index, "failed", now, { reason: ack.message });
@@ -4370,11 +4396,12 @@ async function runSubagent(
 	for (const request of steeringLifecycle.recent) {
 		let changed = false;
 		for (const target of request.targets) {
-			if (target.state !== "scheduled" && target.state !== "routed") continue;
+			if (target.state !== "scheduled" && target.state !== "routed" && target.state !== "queued") continue;
 			changed = true;
-			updateSteeringLifecycleTarget(request.id, target.index, "failed", Date.now(), { reason: "child terminated before steering delivery" });
+			const reason = target.state === "queued" ? "run ended before queued follow-up delivery" : "child terminated before steering delivery";
+			updateSteeringLifecycleTarget(request.id, target.index, "failed", Date.now(), { reason });
 			markSteeringAttention(target.index);
-			emitSteeringEvent("subagent.steer.failed", { type: "steer", id: request.id, ts: request.requestedAt, message: "child terminated before steering delivery" }, target.index, { reason: "child terminated before steering delivery" });
+			emitSteeringEvent("subagent.steer.failed", { type: "steer", id: request.id, ts: request.requestedAt, message: reason }, target.index, { reason });
 		}
 		if (changed) emitTerminalSteeringNotice(request.id, `Steering failed for run ${id}: child terminated before delivery.`);
 	}

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

@@ -5,15 +5,16 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import type { AsyncStatus, Details, SubagentState, ToolBudgetConfig, TurnBudgetConfig } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
-import { consumeSteerAcks, deliverInterruptRequest, requestAsyncSteer } from "../background/control-channel.ts";
+import { consumeSteerAcks, deliverInterruptRequest, queueRevivalBrief, requestAsyncSteer, type SteerDeliveryMode, type SteerRequest } from "../background/control-channel.ts";
 import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
 import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
-import { actionResultFromSteeringStatus, claimSteeringRecovery, remainingSteeringRecoveryLimits, updateSteeringTarget, waitForSteeringAction } from "../background/steering.ts";
+import { actionResultFromSteeringStatus, claimSteeringRecovery, createSteeringStatus, recordSteeringRequest, remainingSteeringRecoveryLimits, updateSteeringTarget, waitForSteeringAction } from "../background/steering.ts";
 
 export async function steerAsyncRun(input: {
 	state: SubagentState;
 	runId: string;
 	message: string;
+	mode?: SteerDeliveryMode;
 	index?: number;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	location: { asyncDir: string | null };
@@ -41,14 +42,38 @@ export async function steerAsyncRun(input: {
 			details: { mode: "management", results: [] },
 		};
 	}
-	if (!status || (status.state !== "running" && status.state !== "queued")) {
+	if (!status) {
 		return {
-			content: [{ type: "text", text: `Async run '${input.runId}' is not running or queued and cannot be steered.` }],
+			content: [{ type: "text", text: `Async run '${input.runId}' was not found.` }],
 			isError: true,
 			details: { mode: "management", results: [] },
 		};
 	}
 	const steps = status.steps ?? [];
+	if (status.state !== "running" && status.state !== "queued") {
+		const retained = input.mode === "follow_up" && status.state === "complete" && Boolean(status.parentWorkflowRunId) && steps.length === 1 && (steps[0]?.status === "complete" || steps[0]?.status === "completed") && Boolean(steps[0]?.sessionFile ?? status.sessionFile);
+		if (!retained) {
+			return {
+				content: [{ type: "text", text: `Async run '${input.runId}' is not running or queued and cannot be steered.` }],
+				isError: true,
+				details: { mode: "management", results: [] },
+			};
+		}
+		if (input.index !== undefined && input.index !== 0) {
+			return { content: [{ type: "text", text: `Retained async run '${status.runId}' has one child. Index ${input.index} is out of range.` }], isError: true, details: { mode: "management", results: [] } };
+		}
+		const request: SteerRequest = { type: "steer", id: randomUUID(), ts: Date.now(), message: input.message.trim(), mode: "follow_up", targetIndex: 0, source: "steer-action" };
+		try {
+			queueRevivalBrief(asyncDir, request);
+		} catch (error) {
+			return { content: [{ type: "text", text: `Failed to queue retained follow-up for async run ${status.runId}: ${error instanceof Error ? error.message : String(error)}` }], isError: true, details: { mode: "management", results: [] } };
+		}
+		status.steering ??= createSteeringStatus();
+		recordSteeringRequest(status.steering, { id: request.id, requestedAt: request.ts, source: request.source, message: request.message, targets: [{ index: 0, state: "scheduled" }] });
+		writeAtomicJson(path.join(asyncDir, "status.json"), status);
+		const queued = { requestId: request.id, state: "scheduled" as const, deliveryStatus: "queued" as const, sourceRunId: status.runId, targets: [{ index: 0, state: "scheduled" as const }] };
+		return { content: [{ type: "text", text: `Follow-up queued for the next resume of retained async run ${status.runId} (request ${request.id}).` }], details: { mode: "management", results: [], steering: queued } };
+	}
 	if (input.index !== undefined) {
 		if (input.index < 0 || input.index >= steps.length) {
 			return {
@@ -92,6 +117,7 @@ export async function steerAsyncRun(input: {
 	try {
 		requestPath = requestAsyncSteer(asyncDir, {
 			message: input.message,
+			mode: input.mode,
 			...(effectiveTargetIndex !== undefined ? { targetIndex: effectiveTargetIndex } : { targetIndexes }),
 			source: "steer-action",
 			id: requestId,
@@ -108,11 +134,11 @@ export async function steerAsyncRun(input: {
 	if (tracked) tracked.updatedAt = Date.now();
 	const targets = targetIndexes.map((index) => ({ index, state: status.steps?.[index]?.status === "pending" ? "scheduled" as const : "pending" as const }));
 	if (targets.every((target) => target.state === "scheduled")) {
-		const scheduled = { requestId, state: "scheduled" as const, sourceRunId: status.runId, targets };
+		const scheduled = { requestId, state: "scheduled" as const, deliveryStatus: "queued" as const, sourceRunId: status.runId, targets };
 		return { content: [{ type: "text", text: `Steering scheduled for async run ${status.runId} (request ${requestId}).` }], details: { mode: "management", results: [], steering: scheduled } };
 	}
 	const waited = await waitForSteeringAction({ asyncDir, sourceRunId: status.runId, requestId, timeoutMs: input.ackTimeoutMs ?? 3_000, signal: input.signal });
-	const result = waited ?? { requestId, state: "pending" as const, sourceRunId: status.runId, targets };
+	const result = waited ?? { requestId, state: "pending" as const, deliveryStatus: "queued" as const, sourceRunId: status.runId, targets };
 	if (input.signal?.aborted) {
 		return { content: [{ type: "text", text: `Steering pending for async run ${status.runId} (request ${requestId}); caller aborted before recovery.` }], details: { mode: "management", results: [], steering: result } };
 	}
@@ -122,7 +148,7 @@ export async function steerAsyncRun(input: {
 		return { content: [{ type: "text", text: `Steering delivered for async run ${status.runId} (request ${requestId}).` }], details: { mode: "management", results: [], steering: finalResult } };
 	}
 	const running = (finalStatus?.steps ?? status.steps ?? []).filter((step) => step.status === "running");
-	const recoveryAllowed = status.mode === "single" && status.isNested !== true && running.length === 1 && Boolean(finalStatus?.steering) && (input.index === undefined || input.index === 0);
+	const recoveryAllowed = (input.mode ?? "steer") === "steer" && status.mode === "single" && status.isNested !== true && running.length === 1 && Boolean(finalStatus?.steering) && (input.index === undefined || input.index === 0);
 	if (recoveryAllowed && finalResult?.state !== "scheduled" && input.recover) {
 		const appendSteeringNotice = (state: "failed" | "recovered", message: string): void => {
 			try {
@@ -203,7 +229,7 @@ export async function steerAsyncRun(input: {
 			}
 			const recovered = sourceStatus?.steering ? actionResultFromSteeringStatus(sourceStatus.steering, status.runId, requestId, revived.details.asyncId) : undefined;
 			appendSteeringNotice("recovered", `Steering recovered for run ${status.runId}; replacement ${revived.details.asyncId} launched.`);
-			return { content: [{ type: "text", text: `Steering recovered for async run ${status.runId}; replacement ${revived.details.asyncId} launched after the source paused.` }], details: { mode: "management", results: [], steering: recovered ?? { requestId, state: "recovered", sourceRunId: status.runId, replacementRunId: revived.details.asyncId, targets: [{ index: input.index ?? 0, state: "recovered" }] } } };
+			return { content: [{ type: "text", text: `Steering recovered for async run ${status.runId}; replacement ${revived.details.asyncId} launched after the source paused.` }], details: { mode: "management", results: [], steering: recovered ?? { requestId, state: "recovered", sourceRunId: status.runId, replacementRunId: revived.details.asyncId, deliveryStatus: "delivered", targets: [{ index: input.index ?? 0, state: "recovered" }] } } };
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
 			const failedStatus = readStatus(asyncDir);
@@ -217,10 +243,10 @@ export async function steerAsyncRun(input: {
 			}
 			const failed = failedStatus?.steering ? actionResultFromSteeringStatus(failedStatus.steering, status.runId, requestId) : undefined;
 			appendSteeringNotice("failed", `Steering failed for run ${status.runId}: ${reason}`);
-			return { content: [{ type: "text", text: `Steering failed for async run ${status.runId} (request ${requestId}): ${reason}` }], isError: true, details: { mode: "management", results: [], steering: failed ?? { requestId, state: "failed", sourceRunId: status.runId, targets: [{ index: input.index ?? 0, state: "failed", reason }] } } };
+			return { content: [{ type: "text", text: `Steering failed for async run ${status.runId} (request ${requestId}): ${reason}` }], isError: true, details: { mode: "management", results: [], steering: failed ?? { requestId, state: "failed", sourceRunId: status.runId, deliveryStatus: "queued", targets: [{ index: input.index ?? 0, state: "failed", reason }] } } };
 		}
 	}
-	const stateText = result.state === "delivered" ? "delivered" : result.state === "scheduled" ? "scheduled" : result.state === "recovered" ? "recovered" : result.state === "failed" ? "failed" : result.state === "partial" ? "partial" : "pending";
+	const stateText = result.state === "failed" ? "failed" : result.state === "partial" ? "partial" : result.deliveryStatus === "queued" ? "queued" : result.state === "delivered" ? "delivered" : result.state === "scheduled" ? "scheduled" : result.state === "recovered" ? "recovered" : "pending";
 	const isError = result.state === "failed" || result.state === "partial";
 	return {
 		content: [{ type: "text", text: `Steering ${stateText} for async run ${status.runId} (request ${requestId}).` }],

package/src/runs/foreground/chain-clarify.ts

@@ -532,7 +532,7 @@ export class ChainClarifyComponent implements Component {
 			buffer = template.split("\n")[0] ?? "";
 		} else if (mode === "output") {
 			const behavior = this.getEffectiveBehavior(this.selectedStep);
-			buffer = behavior.output === false ? "" : (behavior.output || "");
+			buffer = typeof behavior.output === "string" ? behavior.output : "";
 		} else if (mode === "reads") {
 			const behavior = this.getEffectiveBehavior(this.selectedStep);
 			buffer = behavior.reads === false ? "" : (behavior.reads?.join(", ") || "");
@@ -1165,7 +1165,9 @@ export class ChainClarifyComponent implements Component {
 
 		const writesValue = behavior.output === false
 			? th.fg("dim", "(disabled)")
-			: (behavior.output || th.fg("dim", "(none)"));
+			: (typeof behavior.output === "string" && behavior.output
+				? behavior.output
+				: th.fg("dim", "(none)"));
 		const writesLabel = th.fg("dim", "writes: ");
 		lines.push(this.row(`     ${writesLabel}${truncateToWidth(writesValue, innerW - 14)}`));
 
@@ -1296,7 +1298,9 @@ export class ChainClarifyComponent implements Component {
 
 			const writesValue = behavior.output === false
 				? th.fg("dim", "(disabled)")
-				: (behavior.output || th.fg("dim", "(none)"));
+				: (typeof behavior.output === "string" && behavior.output
+					? behavior.output
+					: th.fg("dim", "(none)"));
 			const writesLabel = th.fg("dim", "writes: ");
 			lines.push(this.row(`     ${writesLabel}${truncateToWidth(writesValue, innerW - 14)}`));
 

package/src/runs/foreground/execution.ts

@@ -7,6 +7,7 @@ import { existsSync, unlinkSync } from "node:fs";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig } from "../../agents/agents.ts";
+import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
 import {
 	ensureArtifactsDir,
 	formatOutputArtifactContent,
@@ -458,6 +459,7 @@ async function runSingleAttempt(
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 	let observedMutationAttempt = false;
 	let structuredOutputToolInvoked = false;
+	let structuredOutputMessageStartIndex: number | undefined;
 
 	const exitCode = await new Promise<number>((resolve) => {
 		const spawnSpec = getPiSpawnCommand(args);
@@ -873,7 +875,10 @@ async function runSingleAttempt(
 				const toolArgs = evt.args && typeof evt.args === "object" && !Array.isArray(evt.args)
 					? evt.args as Record<string, unknown>
 					: {};
-				if (options.structuredOutput && evt.toolName === "structured_output") structuredOutputToolInvoked = true;
+				if (options.structuredOutput && evt.toolName === "structured_output") {
+					structuredOutputToolInvoked = true;
+					structuredOutputMessageStartIndex = result.messages?.length ?? 0;
+				}
 				if (options.allowIntercomDetach && (evt.toolName === "intercom" || evt.toolName === "contact_supervisor")) {
 					intercomStarted = true;
 				}
@@ -1182,24 +1187,7 @@ async function runSingleAttempt(
 	if (result.error && result.exitCode === 0) {
 		result.exitCode = 1;
 	}
-	if (result.exitCode === 0 && !result.error) {
-		const messages = result.messages ?? [];
-		const finalText = getFinalOutput(messages);
-		const missingStructuredOutput = options.structuredOutput
-			? !existsSync(options.structuredOutput.outputPath)
-			: false;
-		const errInfo = detectSubagentError(messages);
-		const missingOutput = !finalText?.trim() && (!options.structuredOutput || missingStructuredOutput);
-		if (missingOutput && (!errInfo.hasError || hasEmptyTerminalAssistantResponse(messages))) {
-			result.exitCode = 1;
-			result.error = "Subagent produced no output (possible model cold-start or empty response).";
-		} else if (errInfo.hasError) {
-			result.exitCode = errInfo.exitCode ?? 1;
-			result.error = errInfo.details
-				? `${errInfo.errorType} failed (exit ${errInfo.exitCode}): ${errInfo.details}`
-				: `${errInfo.errorType} failed with exit code ${errInfo.exitCode}`;
-		}
-	}
+	let validatedStructuredOutput = false;
 	if (options.structuredOutput && result.exitCode === 0 && !result.error) {
 		result.structuredOutputSchemaPath = options.structuredOutput.schemaPath;
 		result.structuredOutputPath = options.structuredOutput.outputPath;
@@ -1219,9 +1207,28 @@ async function runSingleAttempt(
 				result.structuredOutputFailed = true;
 			} else {
 				result.structuredOutput = structured.value;
+				validatedStructuredOutput = true;
 			}
 		}
 	}
+	if (result.exitCode === 0 && !result.error) {
+		const messages = result.messages ?? [];
+		const finalText = getFinalOutput(messages);
+		const errorMessages = validatedStructuredOutput
+			? messages.slice(structuredOutputMessageStartIndex ?? messages.length)
+			: messages;
+		const errInfo = detectSubagentError(errorMessages);
+		const missingOutput = !finalText?.trim() && !validatedStructuredOutput;
+		if (missingOutput && (!errInfo.hasError || hasEmptyTerminalAssistantResponse(messages))) {
+			result.exitCode = 1;
+			result.error = "Subagent produced no output (possible model cold-start or empty response).";
+		} else if (errInfo.hasError) {
+			result.exitCode = errInfo.exitCode ?? 1;
+			result.error = errInfo.details
+				? `${errInfo.errorType} failed (exit ${errInfo.exitCode}): ${errInfo.details}`
+				: `${errInfo.errorType} failed with exit code ${errInfo.exitCode}`;
+		}
+	}
 
 	progress.status = result.exitCode === 0 ? "completed" : "failed";
 	progress.durationMs = Date.now() - startTime;
@@ -1438,6 +1445,7 @@ async function runSyncCompletion(
 	if (memoryInjection) {
 		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${memoryInjection}` : memoryInjection;
 	}
+	systemPrompt = appendAgentRefinementOverlay(systemPrompt, { cwd: skillCwd, agentName });
 	systemPrompt = injectOutputPathSystemPrompt(systemPrompt, options.outputPath, agent);
 
 	const candidates = buildModelCandidates(
@@ -1699,6 +1707,8 @@ async function runSyncCompletion(
 					: undefined,
 				cwd: options.cwd ?? runtimeCwd,
 				reportOptional: isAgentContractV1(options.agentContract),
+				artifactsDir: options.artifactsDir,
+				runId: options.runId,
 			});
 		}
 	} catch (error) {