pi-subagents 0.42.0 → 0.43.0

package/src/slash/slash-commands.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { keyText, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey, type Component, type TUI } from "@earendil-works/pi-tui";
+import { Key, matchesKey, truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
 import { BUILTIN_AGENT_NAMES, discoverAgents } from "../agents/agents.ts";
 import {
 	DEFAULT_PROVIDER_MODELS_MAX_AGE_DAYS,
@@ -281,7 +281,7 @@ class SubagentsStopSelector implements Component {
 	invalidate(): void {}
 
 	render(width: number): string[] {
-		const contentWidth = Math.max(40, Math.min(this.width, width || this.width));
+		const contentWidth = Math.max(0, Math.min(this.width, Math.floor(width)));
 		const lines = [this.theme.bold("Stop subagent run"), this.theme.fg("dim", "Select a current-session async run to stop, or a scheduled run to cancel."), ""];
 		const maxRows = 10;
 		const start = Math.max(0, Math.min(this.selected - maxRows + 1, Math.max(0, this.targets.length - maxRows)));
@@ -305,7 +305,7 @@ class SubagentsStopSelector implements Component {
 		} else {
 			lines.push(this.theme.fg("dim", "↑↓/jk select · Enter confirm · Esc cancel"));
 		}
-		return lines;
+		return lines.map((line) => truncateToWidth(line, contentWidth));
 	}
 }
 
@@ -621,6 +621,9 @@ function launchSlashSubagent(
 	void runSlashSubagent(pi, ctx, params);
 }
 
+function slashRunWorkflowScript(key: string, child: Record<string, unknown>): string {
+	return `return runs.run(${JSON.stringify(key)}, ${JSON.stringify(child)})`;
+}
 
 export function registerSlashCommands(
 	pi: ExtensionAPI,
@@ -653,7 +656,7 @@ export function registerSlashCommands(
 	});
 
 	pi.registerCommand("run", {
-		description: "Run a subagent directly: /run agent[output=file] [task] [--bg] [--fork]",
+		description: "Run one subagent through workflowScript: /run agent[output=file] [task] [--bg] [--fork]",
 		getArgumentCompletions: makeAgentCompletions(state),
 		handler: async (args, ctx) => {
 			const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
@@ -671,14 +674,13 @@ export function registerSlashCommands(
 			if (inline.reads && Array.isArray(inline.reads) && inline.reads.length > 0) {
 				finalTask = `[Read from: ${inline.reads.join(", ")}]\n\n${finalTask}`;
 			}
-			const params: SubagentParamsLike = { agent: agentName, task: finalTask, clarify: false, agentScope: "both" };
-			if (inline.output !== undefined) params.output = inline.output;
-			if (inline.outputMode !== undefined) params.outputMode = inline.outputMode;
-			if (inline.skill !== undefined) params.skill = inline.skill;
-			if (inline.model) params.model = inline.model;
-			if (bg) params.async = true;
-			if (fork) params.context = "fork";
-			launchSlashSubagent(pi, ctx, params);
+			const child: Record<string, unknown> = { agent: agentName, task: finalTask, agentScope: "both" };
+			if (inline.output !== undefined) child.output = inline.output;
+			if (inline.outputMode !== undefined) child.outputMode = inline.outputMode;
+			if (inline.skill !== undefined) child.skill = inline.skill;
+			if (inline.model) child.model = inline.model;
+			if (fork) child.context = "fork";
+			launchSlashSubagent(pi, ctx, { workflowScript: slashRunWorkflowScript("run", child), async: bg ? true : false });
 		},
 	});
 
@@ -696,6 +698,19 @@ export function registerSlashCommands(
 		},
 	});
 
+	pi.registerCommand("subagents-refine", {
+		description: "Generate a bounded project-local refinement overlay for one subagent",
+		getArgumentCompletions: makeAgentCompletions(state),
+		handler: async (args, ctx) => {
+			const parts = args.trim().split(/\s+/).filter(Boolean);
+			if (parts.length !== 1) {
+				ctx.ui.notify("Usage: /subagents-refine <agent>", "error");
+				return;
+			}
+			await runSlashSubagent(pi, ctx, { action: "refine", agent: parts[0] });
+		},
+	});
+
 	pi.registerCommand("subagents-fleet", {
 		description: "Open the live subagent fleet inspector",
 		handler: async (_args, ctx) => showFleet(ctx),

package/src/slash/slash-live-state.ts

@@ -1,6 +1,7 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { previewSimpleWorkflowRun } from "../workflows/scripted-workflow.ts";
 import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
 import { type Details, type SingleResult, type Usage, SLASH_RESULT_TYPE } from "../shared/types.ts";
 
@@ -156,8 +157,9 @@ function buildChainInitialResult(params: SubagentParamsLike): AgentToolResult<De
 }
 
 function buildSingleInitialResult(params: SubagentParamsLike): AgentToolResult<Details> {
-	const agent = params.agent ?? "subagent";
-	const task = params.task ?? "";
+	const preview = previewSimpleWorkflowRun(params.workflowScript) ?? {};
+	const agent = params.agent ?? preview.agent ?? "subagent";
+	const task = params.task ?? preview.task ?? "";
 	return {
 		content: [{ type: "text", text: task }],
 		details: {

package/src/tui/fleet-status.ts

@@ -100,21 +100,25 @@ function nestedFleetRows(children: NestedRunSummary[] | undefined): FleetNestedR
 		const steps = (child.mode === "parallel" || child.mode === "chain") ? child.steps ?? [] : [];
 		if (steps.length > 0) {
 			for (const step of steps) {
+				const modelThinking = formatModelThinking(step.model, step.thinking) || undefined;
+				const activity = nestedActivity(step);
 				rows.push({
 					name: step.agent,
 					state: step.status,
-					...(formatModelThinking(step.model, step.thinking) ? { modelThinking: formatModelThinking(step.model, step.thinking) } : {}),
-					...(nestedActivity(step) ? { activity: nestedActivity(step) } : {}),
+					...(modelThinking ? { modelThinking } : {}),
+					...(activity ? { activity } : {}),
 					...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
 				});
 			}
 			continue;
 		}
+		const modelThinking = formatModelThinking(child.model, child.thinking) || undefined;
+		const activity = nestedActivity(child);
 		rows.push({
 			name: nestedRunLabel(child),
 			state: child.state,
-			...(formatModelThinking(child.model, child.thinking) ? { modelThinking: formatModelThinking(child.model, child.thinking) } : {}),
-			...(nestedActivity(child) ? { activity: nestedActivity(child) } : {}),
+			...(modelThinking ? { modelThinking } : {}),
+			...(activity ? { activity } : {}),
 			...(child.startedAt !== undefined ? { startedAt: child.startedAt } : {}),
 		});
 	}

package/src/tui/fleet.ts

@@ -10,6 +10,7 @@ import { readStatus } from "../shared/utils.ts";
 import { formatAsyncRunTranscript } from "../runs/background/fleet-view.ts";
 import { listAsyncRuns, type AsyncRunSummary } from "../runs/background/async-status.ts";
 import { steerAsyncRun } from "../runs/foreground/async-steering-action.ts";
+import type { SteerDeliveryMode } from "../runs/background/control-channel.ts";
 import { stopAsyncRun } from "../runs/foreground/async-stop-action.ts";
 import { contextModeBadge, contextModeLabel } from "../runs/shared/context-mode.ts";
 import { FLEET_STATUS_WIDGET_KEY } from "./fleet-status.ts";
@@ -45,7 +46,7 @@ export interface FleetActionResult {
 }
 
 export interface FleetActionHandlers {
-	steer(input: { runId: string; asyncDir: string; index?: number; message: string }): Promise<FleetActionResult>;
+	steer(input: { runId: string; asyncDir: string; index?: number; message: string; mode: SteerDeliveryMode }): Promise<FleetActionResult>;
 	stop(input: { runId: string; asyncDir: string; index?: number }): Promise<FleetActionResult> | FleetActionResult;
 	inspect?(input: { runId: string; asyncDir: string; index?: number }): Promise<FleetActionResult>;
 }
@@ -484,6 +485,7 @@ export class SubagentFleetComponent implements Component {
 	private expandedTools = false;
 	private actionNotice: FleetActionResult | undefined;
 	private steerDraft: string | undefined;
+	private steerMode: SteerDeliveryMode = "steer";
 	private stopConfirming = false;
 	private actionBusy = false;
 	private transcriptCache: FleetTranscriptCache | undefined;
@@ -538,6 +540,7 @@ export class SubagentFleetComponent implements Component {
 
 	private resetActionInput(): void {
 		this.steerDraft = undefined;
+		this.steerMode = "steer";
 		this.stopConfirming = false;
 	}
 
@@ -553,8 +556,8 @@ export class SubagentFleetComponent implements Component {
 		const lines: string[] = [];
 		if (this.actionBusy) lines.push(this.theme.fg("accent", "Action pending..."));
 		if (this.steerDraft !== undefined) {
-			lines.push(this.theme.fg("accent", `Steer message: ${this.steerDraft}${this.theme.fg("dim", "▌")}`));
-			lines.push(this.theme.fg("dim", "Enter sends · Esc cancels · Backspace edits"));
+			lines.push(this.theme.fg("accent", `Steer message (${this.steerMode}): ${this.steerDraft}${this.theme.fg("dim", "▌")}`));
+			lines.push(this.theme.fg("dim", "Enter sends · Tab changes mode · Esc cancels · Backspace edits"));
 		} else if (this.stopConfirming) {
 			const selected = this.snapshot.items[this.selected];
 			lines.push(this.theme.fg("warning", `Confirm stop for async run ${selected?.runId ?? "selected run"}?`));
@@ -618,7 +621,13 @@ export class SubagentFleetComponent implements Component {
 					this.setActionNotice({ text: "reason" in target ? target.reason : "Fleet controls are unavailable in this context.", isError: true });
 					return;
 				}
-				this.runAction(() => this.options.actions!.steer({ runId: target.item.runId, asyncDir: target.item.run.asyncDir, ...(target.item.index !== undefined ? { index: target.item.index } : {}), message }));
+				this.runAction(() => this.options.actions!.steer({ runId: target.item.runId, asyncDir: target.item.run.asyncDir, ...(target.item.index !== undefined ? { index: target.item.index } : {}), message, mode: this.steerMode }));
+				return;
+			}
+			if (matchesKey(data, "tab") || data === "\t") {
+				const modes: SteerDeliveryMode[] = ["steer", "follow_up", "auto"];
+				this.steerMode = modes[(modes.indexOf(this.steerMode) + 1) % modes.length]!;
+				this.tui.requestRender();
 				return;
 			}
 			if (matchesKey(data, "backspace") || data === "\x7f") {
@@ -836,11 +845,12 @@ export async function openSubagentFleet(ctx: ExtensionContext, state: SubagentSt
 	state.fleetInspectorOpen = true;
 	if (typeof ctx.ui.setWidget === "function") ctx.ui.setWidget(FLEET_STATUS_WIDGET_KEY, undefined);
 	const actions = options.actions ?? {
-		steer: async (input: { runId: string; asyncDir: string; index?: number; message: string }) => firstToolResultText(await steerAsyncRun({
+		steer: async (input: { runId: string; asyncDir: string; index?: number; message: string; mode: SteerDeliveryMode }) => firstToolResultText(await steerAsyncRun({
 			state,
 			runId: input.runId,
 			...(input.index !== undefined ? { index: input.index } : {}),
 			message: input.message,
+			mode: input.mode,
 			location: { asyncDir: input.asyncDir, resolvedId: input.runId } as Parameters<typeof steerAsyncRun>[0]["location"],
 		}), `Failed to steer async run ${input.runId}.`),
 		stop: (input: { runId: string; asyncDir: string; index?: number }) => firstToolResultText(stopAsyncRun(state, input.runId, undefined, { asyncDir: input.asyncDir, resolvedId: input.runId }), `Failed to stop async run ${input.runId}.`),

package/src/tui/render.ts

@@ -53,6 +53,7 @@ const ansiStylePattern = /\x1b\[[0-9;]*m/y;
  * Uses Intl.Segmenter for proper Unicode/emoji handling (not char-by-char).
  */
 export function truncLine(text: string, maxWidth: number): string {
+	if (maxWidth <= 0) return "";
 	if (visibleWidth(text) <= maxWidth) return text;
 
 	const targetWidth = maxWidth - 1;
@@ -83,7 +84,7 @@ export function truncLine(text: string, maxWidth: number): string {
 		const textPortion = text.slice(i, end);
 		for (const seg of segmenter.segment(textPortion)) {
 			const grapheme = seg.segment;
-			const graphemeWidth = visibleWidth(grapheme);
+			const graphemeWidth = grapheme === "\x1b" ? 0 : visibleWidth(grapheme);
 
 			if (currentWidth + graphemeWidth > targetWidth) {
 				return result + activeStyles.join("") + "…";
@@ -111,6 +112,7 @@ function wrapPlainText(text: string, maxWidth: number): string[] {
 		for (const seg of segmenter.segment(rawLine)) {
 			const grapheme = seg.segment;
 			const graphemeWidth = visibleWidth(grapheme);
+			if (graphemeWidth > maxWidth) continue;
 			if (currentWidth > 0 && currentWidth + graphemeWidth > maxWidth) {
 				lines.push(current);
 				current = grapheme;
@@ -144,24 +146,11 @@ function runningGlyph(seed?: number): string {
 	return RUNNING_FRAMES[Math.abs(seed) % RUNNING_FRAMES.length]!;
 }
 
-const WIDGET_ANIMATION_FRAME_MS = 500;
-let widgetRequestRender: (() => void) | undefined;
-
 function animatedSeed(seed: number | undefined, frame: number | undefined): number | undefined {
 	if (frame === undefined) return seed;
 	return (seed ?? 0) + frame;
 }
 
-function widgetAnimationFrame(): number {
-	return Math.floor(Date.now() / WIDGET_ANIMATION_FRAME_MS);
-}
-
-export function requestWidgetRender(): boolean {
-	if (!widgetRequestRender) return false;
-	widgetRequestRender();
-	return true;
-}
-
 function progressRunningSeed(progress: ProgressSeedSource | undefined): number | undefined {
 	if (!progress) return undefined;
 	return runningSeed(
@@ -1291,7 +1280,8 @@ function collapsedWidgetLineBudget(rows: number): number {
 }
 
 function paddedWidgetLine(line: string, width: number): string {
-	const text = ` ${line} `;
+	if (width <= 2) return " ".repeat(Math.max(0, width));
+	const text = ` ${truncLine(line, width - 2)} `;
 	return `${text}${" ".repeat(Math.max(0, width - visibleWidth(text)))}`;
 }
 
@@ -1346,26 +1336,19 @@ function fitAdaptiveWidgetLines(jobs: AsyncJobState[], lines: string[], theme: T
 	return rendered.lines;
 }
 
-function buildWidgetComponent(jobs: AsyncJobState[], expanded: boolean): (tui: { requestRender(): void }, theme: Theme) => Component & { dispose?(): void } {
-	return (tui, theme) => {
-		const requestRender = () => tui.requestRender();
-		widgetRequestRender = requestRender;
+function buildWidgetComponent(jobs: AsyncJobState[], expanded: boolean): (_tui: unknown, theme: Theme) => Component {
+	return (_tui, theme) => {
 		const container = new Container();
 		container.render = (renderWidth: number): string[] => {
-			const width = getTermWidth();
-			const frame = widgetAnimationFrame();
+			const width = Math.max(0, renderWidth - 2);
 			const lines = expanded
-				? buildWidgetLines(jobs, theme, width, true, frame)
+				? buildWidgetLines(jobs, theme, width, true)
 				: jobs.length === 1
-					? compactSingleWidgetLines(jobs[0]!, theme, width, frame)
-					: buildWidgetLines(jobs, theme, width, false, frame);
-			return fitAdaptiveWidgetLines(jobs, lines, theme, width, expanded, frame).map((line) => paddedWidgetLine(line, renderWidth));
-		};
-		const component = container as Component & { dispose?(): void };
-		component.dispose = () => {
-			if (widgetRequestRender === requestRender) widgetRequestRender = undefined;
+					? compactSingleWidgetLines(jobs[0]!, theme, width)
+					: buildWidgetLines(jobs, theme, width, false);
+			return fitAdaptiveWidgetLines(jobs, lines, theme, width, expanded).map((line) => paddedWidgetLine(line, renderWidth));
 		};
-		return component;
+		return container;
 	};
 }
 
@@ -1445,7 +1428,6 @@ export function buildWidgetLines(jobs: AsyncJobState[], theme: Theme, width = ge
 export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void {
 	if (jobs.length === 0) {
 		resetWidgetLayoutSession();
-		widgetRequestRender = undefined;
 		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
 		return;
 	}

package/src/workflows/chat-progress.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Details } from "../shared/types.ts";
 
-export const WORKFLOW_CHAT_PROGRESS_MODES = ["auto", "off", "terminal", "milestones", "live-card"] as const;
+export const WORKFLOW_CHAT_PROGRESS_MODES = ["auto", "off", "live-card"] as const;
 export type WorkflowChatProgressMode = typeof WORKFLOW_CHAT_PROGRESS_MODES[number];
 export type ResolvedWorkflowChatProgressMode = Exclude<WorkflowChatProgressMode, "auto">;
 
@@ -86,7 +86,7 @@ export function resolveWorkflowChatProgress(input: ResolveWorkflowChatProgressIn
 
 	const requestedMode = requested.mode ?? "auto";
 	let mode: ResolvedWorkflowChatProgressMode;
-	if (requestedMode === "auto") mode = sameRepo ? (input.background ? "milestones" : "live-card") : "terminal";
+	if (requestedMode === "auto") mode = sameRepo && !input.background ? "live-card" : "off";
 	else mode = requestedMode;
 
 	if (mode === "live-card" && !sameRepo) return { error: "chatProgress: 'live-card' is only available for workflowScript runs in the same Git repository." };

package/src/workflows/scripted-workflow.ts

@@ -37,11 +37,17 @@ const runFingerprints = new Map();
 function validateRunCall(key, params, label, fingerprints) {
   if (typeof key !== "string" || !runKeyPattern.test(key)) throw new Error(label + " has an invalid key.");
   if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error(label + " requires a params object.");
-  if (Object.prototype.hasOwnProperty.call(params, "action") || Object.prototype.hasOwnProperty.call(params, "workflowScript") || Object.prototype.hasOwnProperty.call(params, "tasks") || Object.prototype.hasOwnProperty.call(params, "chain") || Object.prototype.hasOwnProperty.call(params, "concurrency") || Object.prototype.hasOwnProperty.call(params, "chainDir")) {
+  if (Object.prototype.hasOwnProperty.call(params, "action") || Object.prototype.hasOwnProperty.call(params, "workflowScript") || Object.prototype.hasOwnProperty.call(params, "tasks") || Object.prototype.hasOwnProperty.call(params, "chain") || Object.prototype.hasOwnProperty.call(params, "parallel") || Object.prototype.hasOwnProperty.call(params, "concurrency") || Object.prototype.hasOwnProperty.call(params, "chainDir")) {
     const hint = label === "runs.run" ? "; use runs.all(...) and JavaScript control flow for orchestration." : ".";
     throw new Error(label + " accepts one child via { agent, task } and execution controls only" + hint);
   }
   if (params.worktree !== undefined && typeof params.worktree !== "boolean") throw new Error(label + " worktree must be true or false.");
+  if (params.gate !== undefined && (typeof params.gate !== "string" || !params.gate.trim())) throw new Error(label + " gate must be a non-empty command string.");
+  if (params.gate !== undefined && params.acceptance !== undefined) throw new Error(label + " gate cannot be combined with acceptance; use one gate command or acceptance.verify.");
+  if (params.gate !== undefined && params.resume !== undefined) throw new Error(label + " gate is not supported with retained resume.");
+  if (params.resume !== undefined && (typeof params.resume !== "string" || !params.resume.trim())) throw new Error(label + " resume must be a non-empty retained run id.");
+  if (params.resume !== undefined && params.agent !== undefined) throw new Error(label + " resume and agent are mutually exclusive.");
+  if (params.resume !== undefined && (typeof params.task !== "string" || !params.task.trim())) throw new Error(label + " resume requires a non-empty task follow-up.");
   assertJsonValue(params, label + " params");
   const fingerprint = stableRunJson(params);
   const existing = fingerprints.get(key);
@@ -77,6 +83,20 @@ const runs = Object.freeze({
   },
 });
 
+function validateStateKey(key) {
+  if (typeof key !== "string" || !runKeyPattern.test(key)) throw new Error("state key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+  return key;
+}
+
+const state = Object.freeze({
+  get(key) { return hostCall("state.get", { key: validateStateKey(key) }); },
+  set(key, value) {
+    const validKey = validateStateKey(key);
+    assertJsonValue(value, "state.set('" + validKey + "') value");
+    return hostCall("state.set", { key: validKey, value });
+  },
+});
+
 let contextObjectPrototype;
 
 const capturedConsole = Object.freeze(Object.fromEntries(
@@ -120,6 +140,7 @@ parentPort.on("message", async (message) => {
   if (message.type !== "start") return;
   try {
     const sandbox = { runs, emit(value) { assertJsonValue(value); parentPort.postMessage({ type: "emit", value }); }, console: capturedConsole };
+    if (message.stateEnabled) sandbox.state = state;
     const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
     contextObjectPrototype = vm.runInContext("Object.prototype", context);
     const compiled = new vm.Script("(async () => {\n" + message.script + "\n})()", { filename: "workflow-script.js" });
@@ -175,10 +196,14 @@ export class WorkflowScriptError extends Error {
 
 export interface RunWorkflowScriptOptions {
 	script: string;
-	timeoutMs: number;
+	timeoutMs?: number;
 	signal?: AbortSignal;
 	launch: (key: string, params: Record<string, unknown>, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
 	status: (keyOrRunId: string, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
+	state?: {
+		get: (key: string) => unknown | Promise<unknown>;
+		set: (key: string, value: unknown) => void | Promise<void>;
+	};
 	onTrace?: (trace: WorkflowScriptTraceEntry[]) => void;
 	onEmit?: (emits: unknown[]) => void;
 }
@@ -239,15 +264,39 @@ export function formatWorkflowJsonPreview(value: unknown, maxLength: number): st
 	}
 }
 
+export interface SimpleWorkflowRunPreview {
+	agent?: string;
+	task?: string;
+}
+
+/** Display-only preview for the exact simple `return runs.run(key, {...})` form. */
+export function previewSimpleWorkflowRun(script: string | undefined): SimpleWorkflowRunPreview | undefined {
+	const body = script?.match(/^\s*return\s+(?:await\s+)?runs\.run\s*\(\s*(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`[^`$\\]*`)\s*,\s*\{([\s\S]*)\}\s*\)\s*;?\s*$/)?.[1];
+	if (body === undefined) return undefined;
+	const readProperty = (name: "agent" | "task"): string | undefined => {
+		const match = body.match(new RegExp(`(?:^|,)\\s*(?:${name}|["']${name}["'])\\s*:\\s*("(?:\\\\.|[^"\\\\])*"|'(?:\\\\.|[^'\\\\])*'|\u0060[^\u0060$\\\\]*\u0060)`));
+		if (!match?.[1]) return undefined;
+		const literal = match[1];
+		if (literal.startsWith('"')) {
+			try { return JSON.parse(literal) as string; } catch { return undefined; }
+		}
+		if (literal.slice(1, -1).includes("\\")) return undefined;
+		return literal.slice(1, -1);
+	};
+	const agent = readProperty("agent");
+	const task = readProperty("task");
+	return { ...(agent !== undefined ? { agent } : {}), ...(task !== undefined ? { task } : {}) };
+}
+
 function stableJson(value: unknown): string {
 	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
 	if (isRecord(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
 	return JSON.stringify(value) ?? "undefined";
 }
 
-function validateKey(value: unknown): string {
+function validateKey(value: unknown, owner = "runs.run"): string {
 	if (typeof value !== "string" || !KEY_PATTERN.test(value)) {
-		throw new Error("runs.run key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+		throw new Error(`${owner} key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.`);
 	}
 	return value;
 }
@@ -261,7 +310,7 @@ function workflowStringMetadata(params: Record<string, unknown>): Pick<WorkflowS
 
 export async function runWorkflowScript(options: RunWorkflowScriptOptions): Promise<WorkflowScriptResult> {
 	if (!options.script.trim()) throw new Error("workflowScript must not be empty.");
-	if (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1) throw new Error("workflow script timeout must be a positive integer.");
+	if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1)) throw new Error("workflow script timeout must be a positive integer.");
 
 	const worker = new Worker(WORKER_SOURCE, { eval: true });
 	const emits: unknown[] = [];
@@ -283,7 +332,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 		const finish = (outcome: { value: unknown } | { error: Error }) => {
 			if (settled) return;
 			settled = true;
-			clearTimeout(timer);
+			if (timer) clearTimeout(timer);
 			options.signal?.removeEventListener("abort", onAbort);
 			void worker.terminate();
 			childController.abort("error" in outcome ? outcome.error : new Error("Workflow script completed; unawaited child launches are aborted."));
@@ -291,7 +340,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			else resolve({ value: outcome.value, ...partial() });
 		};
 		const onAbort = () => finish({ error: new Error("Workflow script aborted.") });
-		const timer = setTimeout(() => finish({ error: new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) }), options.timeoutMs);
+		const timer = options.timeoutMs === undefined
+			? undefined
+			: setTimeout(() => finish({ error: new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) }), options.timeoutMs);
 		options.signal?.addEventListener("abort", onAbort, { once: true });
 		if (options.signal?.aborted) return onAbort();
 
@@ -332,13 +383,31 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			if (message.type === "error") return finish({ error: new Error(typeof message.error === "string" ? message.error : "Workflow script failed.") });
 			if (message.type !== "call" || typeof message.callId !== "number" || typeof message.method !== "string" || !isRecord(message.args)) return;
 
-			const respond = (promise: Promise<WorkflowScriptChildResult>) => {
+			const respond = (promise: Promise<unknown>) => {
 				void promise.then(
 					(value) => worker.postMessage({ type: "response", callId: message.callId, ok: true, value: omitUndefinedWorkflowValues(value) }),
 					(error: unknown) => worker.postMessage({ type: "response", callId: message.callId, ok: false, error: error instanceof Error ? error.message : String(error) }),
 				);
 			};
 
+			if (message.method === "state.get" || message.method === "state.set") {
+				if (!options.state) return respond(Promise.reject(new Error("Workflow state is unavailable without a mission.")));
+				let key: string;
+				try {
+					key = validateKey(message.args.key, "state");
+				} catch (error) {
+					return respond(Promise.reject(error));
+				}
+				if (message.method === "state.get") return respond(Promise.resolve().then(() => options.state!.get(key)));
+				const value = message.args.value;
+				try {
+					assertWorkflowJsonValue(value, `state.set('${key}') value`);
+				} catch (error) {
+					return respond(Promise.reject(error));
+				}
+				return respond(Promise.resolve().then(() => options.state!.set(key, value)));
+			}
+
 			if (message.method === "status") {
 				const keyOrRunId = message.args.keyOrRunId;
 				if (typeof keyOrRunId !== "string" || !keyOrRunId.trim()) return respond(Promise.reject(new Error("runs.status(keyOrRunId) requires a non-empty string.")));
@@ -366,12 +435,30 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			if (!isRecord(params)) return respond(Promise.reject(new Error(`runs.run('${key}', params) requires a params object.`)));
 			if (params.action !== undefined) return respond(Promise.reject(new Error(`runs.run('${key}') accepts execution params only; management action is not allowed.`)));
 			if (params.workflowScript !== undefined) return respond(Promise.reject(new Error(`runs.run('${key}') cannot start a nested workflow script.`)));
-			if (params.tasks !== undefined || params.chain !== undefined || params.concurrency !== undefined || params.chainDir !== undefined) {
+			if (params.tasks !== undefined || params.chain !== undefined || params.parallel !== undefined || params.concurrency !== undefined || params.chainDir !== undefined) {
 				return respond(Promise.reject(new Error(`runs.run('${key}') accepts one child via { agent, task }; use runs.all(...) and JavaScript control flow for orchestration.`)));
 			}
 			if (params.worktree !== undefined && typeof params.worktree !== "boolean") {
 				return respond(Promise.reject(new Error(`runs.run('${key}') worktree must be true or false.`)));
 			}
+			if (params.gate !== undefined && (typeof params.gate !== "string" || !params.gate.trim())) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') gate must be a non-empty command string.`)));
+			}
+			if (params.gate !== undefined && params.acceptance !== undefined) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') gate cannot be combined with acceptance; use one gate command or acceptance.verify.`)));
+			}
+			if (params.gate !== undefined && params.resume !== undefined) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') gate is not supported with retained resume.`)));
+			}
+			if (params.resume !== undefined && (typeof params.resume !== "string" || !params.resume.trim())) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') resume must be a non-empty retained run id.`)));
+			}
+			if (params.resume !== undefined && params.agent !== undefined) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') resume and agent are mutually exclusive.`)));
+			}
+			if (params.resume !== undefined && (typeof params.task !== "string" || !params.task.trim())) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') resume requires a non-empty task follow-up.`)));
+			}
 			const collectFailure = message.args.collectFailure === true;
 			const deliver = (promise: Promise<WorkflowScriptChildResult>) => collectFailure
 				? promise
@@ -410,6 +497,6 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			respond(deliver(promise));
 		});
 
-		worker.postMessage({ type: "start", script: options.script });
+		worker.postMessage({ type: "start", script: options.script, stateEnabled: options.state !== undefined });
 	});
 }

package/agents/context-builder.md

@@ -1,46 +0,0 @@
----
-name: context-builder
-description: Analyzes requirements and codebase, generates context and meta-prompt
-tools: read, grep, find, ls, bash, write, web_search, intercom
-thinking: medium
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-output: context.md
----
-
-You are a requirements-to-context subagent.
-
-Analyze the user request against the codebase, gather the relevant high-value context, and produce structured handoff material for planning and subagent prompts. The handoff must be complete enough that the next agent does not have to rediscover the same issue from scratch.
-
-Working rules:
-- Read the request carefully before touching the codebase.
-- Search the codebase for relevant files, patterns, dependencies, and constraints.
-- Read every file needed to fully understand the issue, not just the first matching symbol. Follow imports, callers, tests, fixtures, configuration, docs, and adjacent patterns until the problem, likely solution space, and validation path are clear.
-- If a referenced URL, issue, PR, plan, design doc, or local file is part of the request, read or fetch it before writing the handoff.
-- Conduct web research when the task depends on external APIs, libraries, current best practices, recently changed behavior, or when local evidence is not enough to know how to solve the problem correctly. Use `web_search` if it is available; otherwise use whatever equivalent research capability is available.
-- Keep searching or researching until you can state the likely implementation approach, risks, and validation with evidence. If a gap remains, call it out explicitly instead of implying certainty.
-- Write the requested output files clearly and concretely.
-- Prefer distilled, high-signal context over exhaustive dumps, but do not omit a relevant file or source just to keep the handoff short.
-
-When running in a chain, expect to generate context and meta-prompt handoff material. Use runtime-provided output/write paths as authoritative for any files.
-
-Context handoff:
-- relevant files with line numbers and key snippets
-- important patterns already used in the codebase
-- dependencies, constraints, and implementation risks
-
-Meta-prompt handoff:
-- goal: the concrete outcome the next agent should produce
-- context/evidence: relevant files, diffs, decisions, constraints, and source-backed facts
-- success criteria: what must be true before the next agent can finish
-- hard constraints: true invariants only, such as no edits for review-only work or escalation for unapproved decisions
-- suggested approach: concise direction without over-specifying every step
-- validation: targeted checks to run, or the next-best check if validation is unavailable
-- stop/escalation rules: when to ask via `intercom`, when enough evidence is enough, and when to stop
-- resolved questions and assumptions
-
-The goal is to hand the planner or another role subagent exactly enough code and requirement context to act without rediscovering the same ground. Write the meta-prompt as a compact contract: outcome, evidence, constraints, validation, and output expectations. Avoid long procedural scripts unless each step is a real requirement.
-
-## Supervisor coordination
-If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed context normally.

package/agents/planner.md

@@ -1,56 +0,0 @@
----
-name: planner
-description: Creates implementation plans from context and requirements
-tools: read, grep, find, ls, intercom
-thinking: high
-acceptanceRole: read-only
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-output: plan.md
-defaultReads: context.md
-defaultContext: fork
----
-
-You are a planning subagent.
-
-Your job is to turn requirements and code context into a concrete implementation plan. Do not make code changes. Read, analyze, and write the plan only.
-
-Working rules:
-- Read the provided context before planning.
-- Read any additional code you need in order to make the plan concrete.
-- Name exact files whenever you can.
-- Prefer small, ordered, actionable tasks over vague phases.
-- Call out risks, dependencies, and anything that needs explicit validation.
-- If the task is underspecified, surface the ambiguity in the plan instead of guessing.
-
-Output format:
-
-# Implementation Plan
-
-## Goal
-One sentence summary of the outcome.
-
-## Tasks
-Numbered steps, each small and actionable.
-1. **Task 1**: Description
-   - File: `path/to/file.ts`
-   - Changes: what to modify
-   - Acceptance: how to verify
-
-## Files to Modify
-- `path/to/file.ts` - what changes there
-
-## New Files
-- `path/to/new.ts` - purpose
-
-## Dependencies
-Which tasks depend on others.
-
-## Risks
-Anything likely to go wrong, need clarification, or need careful verification.
-
-Keep the plan concrete. Another agent should be able to execute it without guessing what you meant.
-
-## Supervisor coordination
-If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed plan normally.