pi-subagents 0.42.0 → 0.43.0

package/src/missions/workflow-state.ts

@@ -0,0 +1,77 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
+import { assertWorkflowJsonValue } from "../workflows/scripted-workflow.ts";
+import type { MissionStoreLocation } from "./types.ts";
+import { validateMissionId } from "./store.ts";
+
+const STATE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const MISSION_STATE_MAX_BYTES = 256 * 1024;
+
+export interface MissionWorkflowState {
+	path: string;
+	get(key: string): unknown;
+	set(key: string, value: unknown): void;
+}
+
+export function missionStatePath(location: MissionStoreLocation, missionId: string): string {
+	return path.join(location.missionDir, validateMissionId(missionId), "state.json");
+}
+
+function validateStateKey(value: unknown): string {
+	if (typeof value !== "string" || !STATE_KEY_PATTERN.test(value)) {
+		throw new Error("state key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+	}
+	return value;
+}
+
+export function createMissionWorkflowState(location: MissionStoreLocation, missionId: string): MissionWorkflowState {
+	const filePath = missionStatePath(location, missionId);
+	let loaded = false;
+	let values: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+
+	const load = (): Record<string, unknown> => {
+		if (loaded) return values;
+		let raw: string;
+		try {
+			raw = fs.readFileSync(filePath, "utf-8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				loaded = true;
+				return values;
+			}
+			throw new Error(`Failed to read mission state '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const bytes = Buffer.byteLength(raw);
+		if (bytes > MISSION_STATE_MAX_BYTES) throw new Error(`Mission state file '${filePath}' exceeds the 256 KiB limit (${bytes} bytes).`);
+		try {
+			const parsed: unknown = JSON.parse(raw);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("root must be a JSON object");
+			assertWorkflowJsonValue(parsed, "mission state");
+			values = Object.assign(Object.create(null) as Record<string, unknown>, parsed);
+			loaded = true;
+			return values;
+		} catch (error) {
+			throw new Error(`Invalid mission state file '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+
+	return {
+		path: filePath,
+		get(key) {
+			const validKey = validateStateKey(key);
+			const current = load();
+			return Object.hasOwn(current, validKey) ? current[validKey] : undefined;
+		},
+		set(key, value) {
+			const validKey = validateStateKey(key);
+			assertWorkflowJsonValue(value, `state.set('${validKey}') value`);
+			const next = Object.assign(Object.create(null) as Record<string, unknown>, load(), { [validKey]: value });
+			const bytes = Buffer.byteLength(JSON.stringify(next, null, 2));
+			if (bytes > MISSION_STATE_MAX_BYTES) throw new Error(`Mission state exceeds the 256 KiB limit (${bytes} bytes; maximum ${MISSION_STATE_MAX_BYTES} bytes).`);
+			writePrivateAtomicJson(filePath, next);
+			values = next;
+			loaded = true;
+		},
+	};
+}

package/src/profiles/profiles.ts

@@ -260,7 +260,7 @@ function qualityTierToRoleTier(quality: QualityTier, cost: CostTier): Recommende
 
 function agentsForRoleTier(roleTier: RecommendedRoleTier): BuiltinAgentName[] {
 	if (roleTier === "cheap") return ["scout", "delegate"];
-	if (roleTier === "medium") return ["planner", "context-builder", "researcher"];
+	if (roleTier === "medium") return ["researcher", "reviewer"];
 	return ["worker", "reviewer", "oracle"];
 }
 
@@ -405,8 +405,6 @@ function buildProfileFile(kind: ProfileKind, models: { cheap: string; medium: st
 			agentOverrides: {
 				scout: { model: models.cheap },
 				delegate: { model: models.cheap },
-				planner: { model: models.medium },
-				"context-builder": { model: models.medium },
 				researcher: { model: models.medium },
 				worker: { model: models.strong },
 				reviewer: { model: models.strong },

package/src/runs/background/async-execution.ts

@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
+import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
 import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
 import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
 import { injectOutputPathSystemPrompt, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
@@ -693,6 +694,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		if (memoryInjection) {
 			systemPrompt = systemPrompt ? `${systemPrompt}\n\n${memoryInjection}` : memoryInjection;
 		}
+		systemPrompt = appendAgentRefinementOverlay(systemPrompt, { cwd: stepCwd, agentName: a.name });
 
 		const readInstructions = buildChainInstructions({ ...behavior, output: false, progress: false }, instructionCwd, false);
 		const isFirstProgressAgent = behavior.progress && !progressPrecreated && !progressInstructionCreated;
@@ -1260,6 +1262,7 @@ export function executeAsyncSingle(
 	if (memoryInjection) {
 		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${memoryInjection}` : memoryInjection;
 	}
+	systemPrompt = appendAgentRefinementOverlay(systemPrompt, { cwd: runnerCwd, agentName: agentConfig.name });
 
 	const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
 	const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;

package/src/runs/background/async-job-tracker.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { renderWidget, requestWidgetRender, widgetRenderKey } from "../../tui/render.ts";
+import { renderWidget, widgetRenderKey } from "../../tui/render.ts";
 import { formatControlNoticeMessage } from "../shared/subagent-control.ts";
 import {
 	type AsyncJobState,
@@ -34,7 +34,6 @@ const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
 const MAX_CONTROL_EVENT_LINE_BYTES = 1024 * 1024;
 const CONTROL_EVENT_SCAN_WINDOW_BYTES = 2 * 1024 * 1024;
 const MAX_RECENT_FLEET_JOBS = 20;
-const WIDGET_ANIMATION_REFRESH_MS = 500;
 
 function rememberFleetJob(state: SubagentState, job: AsyncJobState): void {
 	state.fleetJobs ??= new Map();
@@ -57,14 +56,9 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
 	const resultsDir = options.resultsDir ?? DIRS.results;
 	const steeringNoticeSeen = new Map<string, number>();
-	let lastWidgetAnimationAt = 0;
-	const requestStatusRender = (ctx: ExtensionContext) => {
-		if (requestWidgetRender()) return;
-		(ctx.ui as { requestRender?: () => void }).requestRender?.();
-	};
 	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
 		renderWidget(ctx, options.widgetEnabled === false ? [] : jobs);
-		requestStatusRender(ctx);
+		(ctx.ui as { requestRender?: () => void }).requestRender?.();
 	};
 	const rerenderLastWidget = (jobs = Array.from(state.asyncJobs.values())) => {
 		const ctx = state.lastUiContext;
@@ -80,14 +74,6 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		}
 	};
 	const refreshWidget = (ctx: ExtensionContext) => rerenderWidget(ctx);
-	const hasRunningWidgetJobs = () => options.widgetEnabled !== false && [...state.asyncJobs.values()].some((job) => job.status === "running");
-	const refreshWidgetAnimation = () => {
-		if (!hasRunningWidgetJobs()) return;
-		const now = Date.now();
-		if (now - lastWidgetAnimationAt < WIDGET_ANIMATION_REFRESH_MS) return;
-		lastWidgetAnimationAt = now;
-		requestWidgetRender();
-	};
 	const restoredControlEventCursor = (asyncDir: string) => {
 		try {
 			return fs.statSync(path.join(asyncDir, "events.jsonl")).size;
@@ -414,7 +400,6 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			}
 
 			if (widgetChanged) rerenderLastWidget();
-			else refreshWidgetAnimation();
 		}, pollIntervalMs);
 		state.poller.unref?.();
 	};

package/src/runs/background/control-channel.ts

@@ -60,11 +60,15 @@ export interface CheckpointDecisionRequest {
 	reason?: string;
 }
 
+export type SteerDeliveryMode = "steer" | "follow_up" | "auto";
+export type SteerDeliveryStatus = "delivered" | "queued";
+
 export interface SteerRequest {
 	type: "steer";
 	id: string;
 	ts: number;
 	message: string;
+	mode?: SteerDeliveryMode;
 	targetIndex?: number;
 	targetIndexes?: number[];
 	source?: string;
@@ -85,11 +89,14 @@ export interface SteerAck {
 	requestId: string;
 	index: number;
 	ts: number;
-	state: "delivered" | "failed";
+	state: "delivered" | "queued" | "failed";
+	deliveryStatus?: SteerDeliveryStatus;
 	message: string;
 }
 
 const STEER_REQUESTS_DIR = "steer-requests";
+const REVIVAL_BRIEFS_DIR = "revival-briefs";
+export const MAX_STEER_QUEUE_SIZE = 20;
 const STEER_TARGETS_DIR = "steer-targets";
 const STEER_CAPABILITIES_DIR = "steer-capabilities";
 const STEER_ACKS_DIR = "steer-acks";
@@ -186,6 +193,7 @@ function validSteerRequest(request: Partial<SteerRequest>): request is SteerRequ
 		&& typeof request.message === "string"
 		&& Boolean(request.message.trim())
 		&& Buffer.byteLength(request.message, "utf8") <= MAX_STEER_MESSAGE_BYTES
+		&& (request.mode === undefined || request.mode === "steer" || request.mode === "follow_up" || request.mode === "auto")
 		&& (request.targetIndex === undefined || (Number.isInteger(request.targetIndex) && request.targetIndex >= 0 && request.targetIndex <= 1_000_000))
 		&& (request.targetIndexes === undefined || (
 			request.targetIndex === undefined
@@ -218,14 +226,26 @@ export function writeSteerCapability(asyncDir: string, capability: Omit<SteerCap
 	return writeSteerCapabilityAt(steerCapabilityPath(asyncDir, capability.index), capability);
 }
 
+function steerAckWritePath(filePath: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
+	const parsed = path.parse(filePath);
+	const stateOrder = ack.state === "queued" ? "0" : ack.state === "delivered" ? "1" : "2";
+	const timestamp = String(Math.trunc(ack.ts)).padStart(13, "0");
+	for (let suffix = 0; suffix < 1_000; suffix += 1) {
+		const candidate = path.join(parsed.dir, `${parsed.name}-${timestamp}-${stateOrder}-${ack.state}${suffix === 0 ? "" : `-${suffix}`}${parsed.ext}`);
+		if (!fs.existsSync(candidate)) return candidate;
+	}
+	throw new Error("steer acknowledgment queue is full.");
+}
+
 export function writeSteerAckAt(filePath: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
 	assertChildIndex(ack.index);
 	if (!/^[^\s]+$/.test(ack.requestId) || ack.requestId.length > 256) throw new Error("steer acknowledgment requestId is invalid.");
 	if (!Number.isFinite(ack.ts) || ack.ts <= 0) throw new Error("steer acknowledgment ts must be a finite timestamp.");
 	if (!ack.message.trim() || ack.message.length > 1000) throw new Error("steer acknowledgment message is invalid.");
 	const record: SteerAck = { type: "steer-ack", protocolVersion: 1, ...ack, message: ack.message.trim() };
-	writeAtomicJson(filePath, record);
-	return filePath;
+	const ackPath = steerAckWritePath(filePath, ack);
+	writeAtomicJson(ackPath, record);
+	return ackPath;
 }
 
 export function writeSteerAck(asyncDir: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
@@ -283,7 +303,7 @@ export function requestAsyncCheckpointDecision(
 
 export function requestAsyncSteer(
 	asyncDir: string,
-	payload: { message: string; targetIndex?: number; targetIndexes?: number[]; source?: string; id?: string; ts?: number },
+	payload: { message: string; mode?: SteerDeliveryMode; targetIndex?: number; targetIndexes?: number[]; source?: string; id?: string; ts?: number },
 	deps: { now?: () => number; randomId?: () => string } = {},
 ): string {
 	const message = payload.message.trim();
@@ -309,6 +329,7 @@ export function requestAsyncSteer(
 		id: payload.id ?? deps.randomId?.() ?? randomUUID(),
 		ts: payload.ts ?? deps.now?.() ?? Date.now(),
 		message,
+		...(payload.mode && payload.mode !== "steer" ? { mode: payload.mode } : {}),
 		...(payload.targetIndex !== undefined ? { targetIndex: payload.targetIndex } : {}),
 		...(payload.targetIndexes !== undefined ? { targetIndexes: [...payload.targetIndexes] } : {}),
 		...(payload.source ? { source: payload.source } : {}),
@@ -343,9 +364,10 @@ function parseSteerAck(raw: unknown): SteerAck | undefined {
 	if (input.type !== "steer-ack" || input.protocolVersion !== 1 || typeof input.requestId !== "string" || !/^[^\s]+$/.test(input.requestId) || input.requestId.length > 256) return undefined;
 	const { index, ts, state, message } = input;
 	if (typeof index !== "number" || typeof ts !== "number" || !Number.isInteger(index) || index < 0 || index > 1_000_000 || !Number.isFinite(ts) || ts <= 0) return undefined;
-	if (state !== "delivered" && state !== "failed") return undefined;
+	if (state !== "delivered" && state !== "queued" && state !== "failed") return undefined;
+	if (input.deliveryStatus !== undefined && input.deliveryStatus !== "delivered" && input.deliveryStatus !== "queued") return undefined;
 	if (typeof message !== "string" || !message.trim() || message.length > 1000) return undefined;
-	return { type: "steer-ack", protocolVersion: 1, requestId: input.requestId, index, ts, state, message: message.trim() };
+	return { type: "steer-ack", protocolVersion: 1, requestId: input.requestId, index, ts, state, ...(input.deliveryStatus ? { deliveryStatus: input.deliveryStatus } : {}), message: message.trim() };
 }
 
 export function readSteerCapability(asyncDir: string, index: number): SteerCapability | undefined {
@@ -401,6 +423,7 @@ function parseSteerRequest(raw: unknown): SteerRequest | undefined {
 		id: input.id.trim(),
 		ts: input.ts,
 		message: input.message.trim(),
+		...(input.mode ? { mode: input.mode } : {}),
 		...(input.targetIndex !== undefined ? { targetIndex: input.targetIndex } : {}),
 		...(input.targetIndexes !== undefined ? { targetIndexes: [...input.targetIndexes] } : {}),
 		...(typeof input.source === "string" && input.source.trim() ? { source: input.source } : {}),
@@ -440,6 +463,27 @@ export function consumeSteerRequests(asyncDir: string, fsImpl: Pick<typeof fs, "
 	return consumeSteerRequestsFromDir(steerRequestsDir(asyncDir), fsImpl);
 }
 
+export function queueRevivalBrief(asyncDir: string, request: SteerRequest): string {
+	const dir = path.join(controlInboxDir(asyncDir), REVIVAL_BRIEFS_DIR);
+	const queued = fs.existsSync(dir) ? fs.readdirSync(dir).filter((entry) => entry.endsWith(".json")).length : 0;
+	if (queued >= MAX_STEER_QUEUE_SIZE) throw new Error(`Follow-up queue is full (${MAX_STEER_QUEUE_SIZE} messages).`);
+	return writeSteerRequestToDir(dir, { ...request, mode: "follow_up" });
+}
+
+export function readRevivalBriefs(asyncDir: string): Array<{ request: SteerRequest; path: string }> {
+	const dir = path.join(controlInboxDir(asyncDir), REVIVAL_BRIEFS_DIR);
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir).filter((entry) => entry.endsWith(".json")).sort().flatMap((entry) => {
+		const filePath = path.join(dir, entry);
+		try {
+			const request = parseSteerRequest(JSON.parse(fs.readFileSync(filePath, "utf-8")));
+			return request ? [{ request, path: filePath }] : [];
+		} catch {
+			return [];
+		}
+	});
+}
+
 /**
  * Runner side: consume a pending interrupt request. Idempotent — removes the file
  * so each distinct request fires exactly once. Returns whether one was pending.

package/src/runs/background/retained-children.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import { listAsyncRuns } from "./async-status.ts";
+import type { TokenUsage } from "../../shared/types.ts";
+
+const MAX_RETAINED_CHILDREN = 10;
+const MAX_TASK_SUMMARY_LENGTH = 120;
+
+export interface RetainedChild {
+	runId: string;
+	parentRunId?: string;
+	agent: string;
+	taskSummary: string;
+	completedAt: number;
+	sessionPath: string;
+	tokenTotals?: TokenUsage;
+}
+
+function retainedSessionFile(sessionFile: string | undefined): sessionFile is string {
+	if (!sessionFile?.endsWith(".jsonl")) return false;
+	try {
+		const stat = fs.lstatSync(sessionFile);
+		return stat.isFile() && !stat.isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+function boundedTaskSummary(value: string | undefined): string {
+	const normalized = value?.replace(/\s+/g, " ").trim() ?? "";
+	return normalized.length > MAX_TASK_SUMMARY_LENGTH
+		? `${normalized.slice(0, MAX_TASK_SUMMARY_LENGTH - 1)}…`
+		: normalized;
+}
+
+export function listRetainedChildren(asyncDirRoot: string, sessionId: string): RetainedChild[] {
+	return listAsyncRuns(asyncDirRoot, { sessionId, states: ["complete"], reconcile: false })
+		.flatMap((run) => {
+			if (!run.parentWorkflowRunId || run.steps.length !== 1) return [];
+			const step = run.steps[0]!;
+			if ((step.status !== "complete" && step.status !== "completed") || !retainedSessionFile(step.sessionFile ?? run.sessionFile)) return [];
+			const completedAt = run.endedAt;
+			if (completedAt === undefined) return [];
+			return [{
+				runId: run.id,
+				...(run.parentWorkflowRunId ? { parentRunId: run.parentWorkflowRunId } : {}),
+				agent: step.agent,
+				taskSummary: boundedTaskSummary(step.description),
+				completedAt,
+				sessionPath: step.sessionFile ?? run.sessionFile!,
+				...(step.tokens ?? run.totalTokens ? { tokenTotals: step.tokens ?? run.totalTokens } : {}),
+			}];
+		})
+		.sort((left, right) => right.completedAt - left.completedAt)
+		.slice(0, MAX_RETAINED_CHILDREN);
+}
+
+export function formatRetainedChildren(children: RetainedChild[]): string {
+	if (children.length === 0) return "No completed retained children in the active parent session.";
+	return [
+		`Completed retained children (newest first, last ${MAX_RETAINED_CHILDREN}):`,
+		...children.flatMap((child) => [
+			`- ${child.runId} | ${child.agent} | ${new Date(child.completedAt).toISOString()}`,
+			`  task: ${child.taskSummary || "(no task summary)"}`,
+			`  session: ${child.sessionPath}`,
+			...(child.tokenTotals ? [`  tokens: input ${child.tokenTotals.input}, output ${child.tokenTotals.output}, total ${child.tokenTotals.total}`] : []),
+		]),
+	].join("\n");
+}

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

@@ -1635,6 +1635,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 +2613,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 +4375,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.`);
 	}