acpus 0.0.1 → 0.0.2

package/dist/cli.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { At as __require, Ct as writeRunIndex, Dt as runDir, Et as projectWorkflowsDir, O as compileExecutionPlan, Ot as runsDir, S as syncRun, St as readRunIndex, Tt as globalWorkflowsDir, _ as applyInputDefaults, a as previewRunView, b as issue, d as recoverDriver, f as runWorkflowWorker, ft as WorkflowSpecSchema, g as lintWorkflowSpec, gt as resolveRunLocator, h as loadWorkflowSpec, jt as __toESM, kt as __commonJSMin, l as buildRunMonitorView, m as workerIsActive, mt as getOutputContract, o as runViewFromIndex, p as spawnBackgroundWorker, t as prepareRun, u as buildTaskDetailView, v as validateWorkflowInput, wt as draftsDir, x as resultFromIssues, xt as appendEvent, yt as buildRunDiagnosticsView } from "./run-workflow-CbxKhAqF.mjs";
+import { A as terminalRunStatus, At as appendEvent, D as readFinalOutput, E as buildTaskDetailView, Ft as runDir, It as runsDir, Lt as __commonJSMin, M as workerSummary, Mt as writeRunIndex, N as syncRun, Nt as globalWorkflowsDir, O as runWorkflowWorker, Ot as WorkflowSpecSchema, Pt as projectWorkflowsDir, Rt as __require, S as resultFromIssues, T as buildRunMonitorView, _ as applyInputDefaults, d as previewRunView, g as lintWorkflowSpec, h as stringifyWorkflowSpec, j as workerIsActive, jt as readRunIndex, k as spawnBackgroundWorker, m as loadWorkflowSpec, r as compileExecutionPlan, t as prepareRun, v as validateWorkflowInput, x as issue, y as staticLimitOrDefault, zt as __toESM } from "./run-workflow-DdIAC8Zu.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
+import YAML from "yaml";
 import React from "react";
 import { render } from "ink";
 import { fileURLToPath } from "node:url";
@@ -3016,110 +3017,158 @@ const { program: program$1, createCommand, createArgument, createOption, Command
 	exports.InvalidOptionArgumentError = InvalidArgumentError;
 })))(), 1)).default;
 //#endregion
-//#region src/runtime/diagnose-run.ts
-async function startDiagnosticRun(cwd, logicalRunId) {
-	const index = await readRunIndex(cwd, logicalRunId);
-	const dir = runDir(logicalRunId, cwd);
-	const spec = WorkflowSpecSchema.parse(JSON.parse(await fs.readFile(path.join(dir, "workflow.spec.json"), "utf8")));
-	const role = recoveryRole(spec.roles);
-	const diagnosticId = `diagnostic-${index.agentUsage.recoveryCalls + 1}`;
-	const output = {
-		status: "completed",
-		summary: "Diagnostic prompt prepared. Run recovery review as a normal workflow stage in a follow-up run if needed.",
-		artifacts: [{
-			kind: "prompt",
-			path: `prompts/${diagnosticId}.md`,
-			label: "Diagnostic prompt"
-		}],
-		nextFocus: "review recovery plan",
-		data: {
-			role,
-			contract: getOutputContract("diagnostic").schemaForPrompt
-		}
-	};
-	await fs.mkdir(path.join(dir, "prompts"), { recursive: true });
-	const diagnostics = await buildRunDiagnosticsView(cwd, index, { eventTailLimit: 50 });
-	await fs.writeFile(path.join(dir, "prompts", `${diagnosticId}.md`), diagnosticPrompt({
-		workflowName: spec.name,
-		runSnapshot: index,
-		outputs: await readExistingOutputs(dir),
-		diagnostics: diagnostics.diagnostics,
-		eventTail: diagnostics.eventTail
-	}), "utf8");
-	await fs.mkdir(path.join(dir, "diagnostics"), { recursive: true });
-	await fs.writeFile(path.join(dir, "diagnostics", `${diagnosticId}.json`), `${JSON.stringify(output, null, 2)}\n`, "utf8");
-	const next = {
-		...index,
-		status: index.status === "blocked" || index.status === "failed" ? "diagnosed_blocked" : index.status,
-		agentUsage: {
-			...index.agentUsage,
-			recoveryCalls: index.agentUsage.recoveryCalls + 1
+//#region src/run-index/locator.ts
+async function resolveRunLocator(locator, cwd = process.cwd()) {
+	const candidate = path.resolve(cwd, locator);
+	try {
+		const dir = (await fs.stat(candidate)).isDirectory() ? candidate : path.dirname(candidate);
+		await fs.access(path.join(dir, "run.json"));
+		const runsDir = path.dirname(dir);
+		const orchestratorDir = path.dirname(runsDir);
+		return {
+			cwd: path.dirname(orchestratorDir),
+			runId: path.basename(dir),
+			dir
+		};
+	} catch {
+		return {
+			cwd,
+			runId: locator,
+			dir: path.join(cwd, ".acpus", "runs", locator)
+		};
+	}
+}
+//#endregion
+//#region src/run-index/run-summary.ts
+async function listRunSummaries(cwd = process.cwd()) {
+	const dir = runsDir(cwd);
+	let entries;
+	try {
+		entries = (await fs.readdir(dir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).map((name) => ({
+			name,
+			mtimeMs: 0
+		}));
+	} catch (error) {
+		if (error.code === "ENOENT") return {
+			kind: "runs",
+			dir,
+			entries: []
+		};
+		throw error;
+	}
+	const withMtime = await Promise.all(entries.map(async (entry) => {
+		try {
+			const stat = await fs.stat(path.join(dir, entry.name));
+			return {
+				...entry,
+				mtimeMs: stat.mtimeMs
+			};
+		} catch {
+			return entry;
 		}
+	}));
+	const summaries = await Promise.all(withMtime.map((entry) => runSummary(cwd, dir, entry.name, entry.mtimeMs)));
+	summaries.sort((left, right) => parseTime(right.sortTime) - parseTime(left.sortTime) || right.runId.localeCompare(left.runId));
+	return {
+		kind: "runs",
+		dir,
+		entries: summaries
 	};
-	await writeRunIndex(cwd, next);
-	await appendEvent(cwd, logicalRunId, {
-		type: "diagnostic_prepared",
-		diagnosticId
-	});
-	return next;
 }
-function recoveryRole(roles) {
-	return roles.recovery_reviewer ?? Object.values(roles).find((role) => role.category === "validation" || role.category === "review") ?? {
-		category: "review",
-		agent: "aiden",
-		mode: "readOnly"
-	};
+function formatRunSummaryList(list) {
+	if (list.entries.length === 0) return `runs in ${list.dir}\nNo runs found.\n`;
+	const lines = [`runs in ${list.dir}`];
+	for (const entry of list.entries) {
+		const status = entry.status ?? "invalid";
+		const workflow = entry.workflowName ? ` ${entry.workflowName}` : "";
+		const progress = entry.progress ? ` ${entry.progress.label}` : "";
+		const worker = entry.worker ? ` worker=${entry.worker.status}` : "";
+		const updated = entry.updatedAt ?? entry.sortTime;
+		const invalid = entry.invalid && entry.error ? ` error=${entry.error}` : "";
+		lines.push(`- ${entry.runId} ${status}${progress}${worker}${workflow} updated=${updated}${invalid}`);
+	}
+	return `${lines.join("\n")}\n`;
 }
-async function readExistingOutputs(dir) {
-	const outputDir = path.join(dir, "outputs");
-	const outputs = {};
+async function runSummary(cwd, parentDir, runId, mtimeMs) {
+	const runDir = path.join(parentDir, runId);
+	const fallbackTime = timeFromRunId(runId) ?? new Date(mtimeMs || 0).toISOString();
 	try {
-		const entries = await fs.readdir(outputDir);
-		for (const entry of entries) {
-			if (!entry.endsWith(".json")) continue;
-			outputs[path.basename(entry, ".json")] = JSON.parse(await fs.readFile(path.join(outputDir, entry), "utf8"));
-		}
-	} catch {}
-	return outputs;
+		const index = await readRunIndex(cwd, runId);
+		const progress = stageProgress(index);
+		const terminalAt = terminalTime(index);
+		const updatedAt = index.updatedAt ?? terminalAt;
+		const createdAtMs = parseTimeOrUndefined(index.createdAt);
+		const terminalAtMs = terminalAt ? parseTimeOrUndefined(terminalAt) : void 0;
+		return {
+			runId,
+			runDir,
+			workflowName: index.workflowName,
+			status: index.status,
+			progress,
+			createdAt: index.createdAt,
+			updatedAt,
+			durationMs: terminalAtMs !== void 0 && createdAtMs !== void 0 ? terminalAtMs - createdAtMs : void 0,
+			elapsedMs: terminalAt ? void 0 : createdAtMs !== void 0 ? Date.now() - createdAtMs : void 0,
+			worker: workerSummary(index.worker),
+			sortTime: firstValidTime(updatedAt, index.createdAt, fallbackTime)
+		};
+	} catch (error) {
+		return {
+			runId,
+			runDir,
+			invalid: true,
+			error: error instanceof Error ? error.message : String(error),
+			sortTime: fallbackTime
+		};
+	}
 }
-function diagnosticPrompt(input) {
-	return `You are the recovery reviewer for a blocked acpus workflow.
-
-Workflow: ${input.workflowName}
-
-Run snapshot:
-\`\`\`json
-${JSON.stringify(input.runSnapshot, null, 2)}
-\`\`\`
-
-Author stage outputs:
-\`\`\`json
-${JSON.stringify(input.outputs, null, 2)}
-\`\`\`
-
-Runtime diagnostics:
-\`\`\`json
-${JSON.stringify(input.diagnostics, null, 2)}
-\`\`\`
-
-Recent runtime events:
-\`\`\`json
-${JSON.stringify(input.eventTail, null, 2)}
-\`\`\`
-
-Diagnose why the run is blocked and recommend the smallest safe recovery plan. Do not edit files. Do not rerun prior edit work.
-
-End the response with exactly one valid, parseable JSON object matching the diagnostic contract. Do not wrap the final JSON object in Markdown code fences. Do not use \`\`\`json.`;
+function stageProgress(index) {
+	const stages = Object.values(index.stages);
+	const completed = stages.filter((stage) => stage.status === "completed" || stage.status === "skipped").length;
+	return {
+		completedStages: completed,
+		totalStages: stages.length,
+		label: `${completed}/${stages.length} stages`
+	};
+}
+function terminalTime(index) {
+	return Object.values(index.stages).map((stage) => stage.completedAt).filter((value) => Boolean(value)).sort().at(-1);
+}
+function timeFromRunId(runId) {
+	const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/.exec(runId);
+	if (!match) return void 0;
+	const [, year, month, day, hour, minute, second, ms] = match;
+	return `${year}-${month}-${day}T${hour}:${minute}:${second}.${ms}Z`;
+}
+function firstValidTime(...values) {
+	return values.find((value) => value !== void 0 && parseTimeOrUndefined(value) !== void 0) ?? (/* @__PURE__ */ new Date(0)).toISOString();
+}
+function parseTime(value) {
+	return parseTimeOrUndefined(value) ?? 0;
+}
+function parseTimeOrUndefined(value) {
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : void 0;
 }
 //#endregion
 //#region src/commands/common.ts
+async function resolveSpecArg(options) {
+	if (options.spec) {
+		const hasPathSeparator = options.spec.includes("/") || options.spec.includes("\\");
+		const hasSpecExtension = options.spec.endsWith(".yaml") || options.spec.endsWith(".yml");
+		const hasUnsupportedSpecExtension = options.spec.endsWith(".json") || options.spec.endsWith(".workflow.spec.json");
+		if (hasPathSeparator || hasSpecExtension || hasUnsupportedSpecExtension) return options.spec;
+		return path.join(options.global ? globalWorkflowsDir() : projectWorkflowsDir(), options.spec, "workflow.spec.yaml");
+	}
+	throw new Error("Provide a spec file path or workflow name.");
+}
 async function loadAndLint(specPath) {
 	const loaded = await loadWorkflowSpec(specPath);
-	if (!loaded.spec) return { result: resultFromIssues("validate", loaded.issues) };
+	if (!loaded.spec) return { result: resultFromIssues("spec", loaded.issues) };
 	const issues = [...loaded.issues, ...lintWorkflowSpec(loaded.spec)];
 	return {
 		spec: loaded.spec,
-		result: resultFromIssues("validate", issues)
+		result: resultFromIssues("spec", issues)
 	};
 }
 function printJson(value) {
@@ -3145,109 +3194,195 @@ async function ensureEmptyOrOverwrite(target, overwrite) {
 		if (error.code !== "ENOENT") throw error;
 	}
 }
-async function readJsonFile(filePath) {
-	return JSON.parse(await fs.readFile(filePath, "utf8"));
+async function readInputArg(value) {
+	const trimmed = value.trimStart();
+	if (trimmed.startsWith("{")) return parseJsonObject(value, "--input");
+	return readInputFile(trimmed);
+}
+function parseJsonObject(raw, source) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`${source}: invalid JSON: ${message}`);
+	}
+	return assertInputObject(parsed, source);
+}
+async function readInputFile(filePath) {
+	const raw = await fs.readFile(filePath, "utf8");
+	if (isYamlPath(filePath)) return parseYamlObject(raw, filePath);
+	return parseJsonObject(raw, filePath);
 }
-function resolveSpecPath(options) {
-	if (options.spec && options.workflow) throw new Error("Use only one of --spec or --workflow.");
-	if (options.spec) return options.spec;
-	if (options.workflow) return path.join(options.global ? globalWorkflowsDir() : projectWorkflowsDir(), options.workflow, "workflow.spec.json");
-	throw new Error("Provide --spec <path> or --workflow <name>.");
+function parseYamlObject(raw, source) {
+	let parsed;
+	try {
+		parsed = YAML.parse(raw);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`${source}: invalid YAML: ${message}`);
+	}
+	return assertInputObject(parsed, source);
+}
+function assertInputObject(parsed, source) {
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${source} must contain one input object.`);
+	return parsed;
+}
+function isYamlPath(filePath) {
+	const lower = filePath.toLowerCase();
+	return lower.endsWith(".yaml") || lower.endsWith(".yml");
 }
 //#endregion
-//#region src/commands/diagnose.ts
-function registerDiagnose(program) {
-	program.command("diagnose").argument("<run>", "logical run id or run directory").option("--wait", "wait until diagnostic preparation is reflected in the run index").option("--json", "print JSON").action(async (runArg, options) => {
-		const locator = await resolveRunLocator(runArg);
-		const started = await startDiagnosticRun(locator.cwd, locator.runId);
-		const index = options.wait ? await waitForDiagnostic(locator.cwd, locator.runId) : started;
-		const diagnostics = await buildRunDiagnosticsView(locator.cwd, index, { eventTailLimit: 50 });
-		const output = {
-			ok: true,
-			runId: locator.runId,
-			diagnosticId: `diagnostic-${index.agentUsage.recoveryCalls}`,
-			status: index.status,
-			message: options.wait ? "Diagnostic preparation finished." : "Diagnostic preparation started.",
-			diagnostics
-		};
-		if (options.json) printJson(output);
-		else process.stdout.write(`${output.message}\n`);
-	});
+//#region src/commands/run-selection.tsx
+async function resolveOptionalRunArg(input) {
+	if (input.runArg) return input.runArg;
+	if (input.json) {
+		printJson(await listRunSummaries());
+		return;
+	}
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		process.stdout.write(formatRunSummaryList(await listRunSummaries()));
+		return;
+	}
+	return pickRun(input.title);
 }
-async function waitForDiagnostic(cwd, runId) {
-	return syncRun(cwd, runId, { startPending: false });
+async function pickRun(title) {
+	const { RunPickerApp } = await import("./run-picker-app-utJ2f5CU.mjs");
+	let selected;
+	await render(React.createElement(RunPickerApp, {
+		title,
+		onSelect: (runId) => {
+			selected = runId;
+		}
+	})).waitUntilExit();
+	return selected;
 }
 //#endregion
 //#region src/commands/follow.ts
+function printNdjson(value) {
+	process.stdout.write(`${JSON.stringify(value)}\n`);
+}
 function registerFollow(program) {
-	program.command("follow").argument("<run>", "logical run id or run directory").option("--json", "print JSON").action(async (runArg, options) => {
+	program.command("follow").argument("[run]", "logical run id or run directory").option("--json", "print JSON").action(async (runArg, options) => {
+		runArg = await resolveOptionalRunArg({
+			runArg,
+			json: options.json,
+			title: "Select a run to follow"
+		});
+		if (!runArg) return;
 		const locator = await resolveRunLocator(runArg);
 		const index = await syncRun(locator.cwd, locator.runId, { startPending: false });
-		const spec = WorkflowSpecSchema.parse(JSON.parse(await fs.readFile(path.join(runDir(locator.runId, locator.cwd), "workflow.spec.json"), "utf8")));
-		if (options.json) printJson(await buildRunMonitorView(locator.cwd, spec, index));
-		else {
-			const view = await runViewFromIndex(locator.cwd, spec, index);
-			process.stdout.write(`run ${locator.runId} status=${view.status} workflow=${view.workflowName}${view.gateVerdict ? ` verdict=${view.gateVerdict}` : ""}\n`);
+		const dir = runDir(locator.runId, locator.cwd);
+		const eventsPath = path.join(dir, "events.ndjson");
+		if (terminalRunStatus(index.status)) {
+			if (options.json) {
+				const spec = WorkflowSpecSchema.parse(YAML.parse(await fs.readFile(path.join(dir, "workflow.spec.yaml"), "utf8")));
+				printNdjson(await buildRunMonitorView(locator.cwd, spec, index));
+			} else process.stdout.write(`run ${locator.runId} ${index.status}\n`);
+			return;
 		}
-	});
-}
-//#endregion
-//#region src/commands/generate.ts
-function registerGenerate(program) {
-	program.command("generate").option("--name <name>", "draft name", "draft-workflow").option("--json", "print JSON").action(async (options) => {
-		const dir = draftsDir();
-		await fs.mkdir(dir, { recursive: true });
-		const file = path.join(dir, `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${options.name}.workflow.spec.json`);
-		const spec = {
-			schemaVersion: "acpus.workflow/v1",
-			name: options.name,
-			description: "Draft workflow scaffold. Main Agent should edit before running.",
-			root: "plan",
-			inputs: {
-				task: {
-					type: "string",
-					default: ""
-				},
-				cwd: {
-					type: "path",
-					default: "."
-				}
-			},
-			roles: { planner: {
-				category: "planning",
-				agent: "claude",
-				mode: "readOnly"
-			} },
-			limits: { stageTimeoutMinutes: 30 },
-			stages: [{
-				id: "plan",
-				kind: "agentTask",
-				role: "planner",
-				prompt: "Plan the requested workflow task: ${task}",
-				variables: [{
-					name: "task",
-					source: "input.task"
-				}]
-			}, {
-				id: "gate",
-				kind: "gate",
-				dependsOn: ["plan"]
-			}]
+		if (!workerIsActive(index.worker)) {
+			if (options.json) {
+				const spec = WorkflowSpecSchema.parse(YAML.parse(await fs.readFile(path.join(dir, "workflow.spec.yaml"), "utf8")));
+				printNdjson(await buildRunMonitorView(locator.cwd, spec, index));
+			} else process.stdout.write(`run ${locator.runId} ${index.status} (no active worker)\n`);
+			return;
+		}
+		let linesRead = 0;
+		let done = false;
+		const onSigint = () => {
+			done = true;
 		};
-		await fs.writeFile(file, `${JSON.stringify(spec, null, 2)}\n`, "utf8");
-		if (options.json) printJson({
-			ok: true,
-			path: file
-		});
-		else process.stdout.write(`${file}\n`);
+		process.on("SIGINT", onSigint);
+		linesRead = await readAndPrintNewEvents(eventsPath, linesRead, options.json ?? false);
+		while (!done) {
+			await sleep(500);
+			linesRead = await readAndPrintNewEvents(eventsPath, linesRead, options.json ?? false);
+			try {
+				const idx = await readRunIndex(locator.cwd, locator.runId);
+				if (terminalRunStatus(idx.status)) {
+					if (options.json) {
+						const spec = WorkflowSpecSchema.parse(YAML.parse(await fs.readFile(path.join(dir, "workflow.spec.yaml"), "utf8")));
+						printNdjson(await buildRunMonitorView(locator.cwd, spec, idx));
+					} else process.stdout.write(`run ${locator.runId} ${idx.status}\n`);
+					done = true;
+				}
+			} catch {}
+		}
+		process.removeListener("SIGINT", onSigint);
 	});
 }
+async function readAndPrintNewEvents(eventsPath, linesRead, jsonMode) {
+	let content;
+	try {
+		content = await fs.readFile(eventsPath, "utf8");
+	} catch {
+		return linesRead;
+	}
+	const lines = content.split("\n");
+	const totalLines = content.endsWith("\n") ? lines.length - 1 : lines.length;
+	for (let i = linesRead; i < totalLines; i++) {
+		const line = lines[i];
+		if (!line) continue;
+		if (jsonMode) process.stdout.write(`${line}\n`);
+		else formatEvent(line);
+	}
+	return totalLines;
+}
+function formatEvent(line) {
+	let event;
+	try {
+		event = JSON.parse(line);
+	} catch {
+		process.stdout.write(`${line}\n`);
+		return;
+	}
+	const type = typeof event.type === "string" ? event.type : "unknown";
+	switch (type) {
+		case "worker_started":
+			process.stdout.write(`worker started pid=${event.pid ?? "?"} run=${event.runId ?? "?"}\n`);
+			break;
+		case "run_progress": {
+			const stageParts = (Array.isArray(event.changedStages) ? event.changedStages : []).map((s) => `${s.id}=${s.status}`);
+			process.stdout.write(`progress status=${event.status ?? "?"}${stageParts.length > 0 ? ` ${stageParts.join(" ")}` : ""}\n`);
+			break;
+		}
+		case "worker_exited":
+			process.stdout.write(`worker exited pid=${event.pid ?? "?"} status=${event.status ?? "?"}\n`);
+			break;
+		case "runtime_fatal":
+			process.stdout.write(`fatal: ${event.message ?? String(event.error ?? "")}\n`);
+			break;
+		default:
+			process.stdout.write(`event ${type}\n`);
+			break;
+	}
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
 //#endregion
 //#region src/commands/list.ts
 function registerList(program) {
-	program.command("list").argument("<kind>", "workflows|runs|drafts").option("--global", "list global workflows").option("--json", "print JSON").action(async (kind, options) => {
-		const dir = kind === "workflows" ? options.global ? globalWorkflowsDir() : projectWorkflowsDir() : kind === "runs" ? runsDir() : kind === "drafts" ? draftsDir() : "";
-		if (!dir) throw new Error("kind must be workflows, runs, or drafts");
+	const list = program.command("list");
+	list.command("workflows").option("--global", "list global workflows").option("--json", "print JSON").action(async (options) => {
+		const kind = "workflows";
+		const dir = options.global ? globalWorkflowsDir() : projectWorkflowsDir();
+		const entries = await safeList(dir);
+		const output = {
+			kind,
+			dir,
+			entries
+		};
+		if (options.json) printJson(output);
+		else {
+			process.stdout.write(`${kind} in ${dir}\n`);
+			for (const entry of entries) process.stdout.write(`- ${entry}\n`);
+		}
+	});
+	list.command("runs").option("--json", "print JSON").action(async (options) => {
+		const kind = "runs";
+		const dir = runsDir();
 		const entries = await safeList(dir);
 		const output = {
 			kind,
@@ -3272,52 +3407,68 @@ async function safeList(dir) {
 //#endregion
 //#region src/commands/monitor.ts
 function registerMonitor(program) {
-	program.command("monitor").argument("<run>", "logical run id or run directory").option("--json", "print JSON").action(async (runArg, options) => {
-		if (!optionJson(options)) {
-			const { MonitorApp } = await import("./monitor-app-CSjUPe9j.mjs");
+	program.command("monitor").argument("[run]", "logical run id or run directory").option("--json", "print JSON").action(async (runArg, options) => {
+		const json = optionJson(options);
+		runArg = await resolveOptionalRunArg({
+			runArg,
+			json,
+			title: "Select a run to monitor"
+		});
+		if (!runArg) return;
+		if (!json) {
+			const { MonitorApp } = await import("./monitor-app-CPlEcyHR.mjs");
 			await render(React.createElement(MonitorApp, { runArg })).waitUntilExit();
 			return;
 		}
 		const { locator, spec, index } = await loadObservedRun(runArg);
 		printJson(await buildRunMonitorView(locator.cwd, spec, index));
-	}).command("detail").argument("<run>", "logical run id or run directory").argument("<task-id>", "Stage Task id").option("--json", "print JSON").action(async (runArg, taskId, options) => {
-		if (!optionJson(options)) throw new Error("Usage: monitor detail <run> <task-id> --json");
+	}).command("detail").argument("<run>", "logical run id or run directory").argument("<task-id>", "Stage Task id").option("--json", "print JSON").action(async (runArg, taskId, options, command) => {
+		if (!optionJson(command ?? options)) throw new Error("Usage: monitor detail <run> <task-id> --json");
 		const { locator, spec, index } = await loadObservedRun(runArg);
 		printJson(await buildTaskDetailView(locator.cwd, spec, index, taskId));
 	});
 }
 function optionJson(options) {
 	if ("json" in options && typeof options.json === "boolean") return options.json;
+	if ("getOptionValue" in options && typeof options.getOptionValue === "function" && options.getOptionValue("json")) return true;
 	if ("opts" in options && typeof options.opts === "function") {
 		if (options.opts().json) return true;
-		if (options.getOptionValue?.("json")) return true;
 		if (options.parent?.opts().json) return true;
 	}
-	return process.argv.includes("--json");
+	return false;
 }
 async function loadObservedRun(runArg) {
 	const locator = await resolveRunLocator(runArg);
 	return {
 		locator,
 		index: await syncRun(locator.cwd, locator.runId, { startPending: false }),
-		spec: WorkflowSpecSchema.parse(JSON.parse(await fs.readFile(path.join(runDir(locator.runId, locator.cwd), "workflow.spec.json"), "utf8")))
+		spec: WorkflowSpecSchema.parse(YAML.parse(await fs.readFile(path.join(runDir(locator.runId, locator.cwd), "workflow.spec.yaml"), "utf8")))
 	};
 }
 //#endregion
-//#region src/commands/preview.ts
-function registerPreview(program) {
-	program.command("preview").option("--spec <path>", "workflow spec path").option("--workflow <name>", "saved workflow name").option("--global", "resolve saved workflow from global directory").option("--json", "print JSON").action(async (options) => {
-		const specPath = resolveSpecPath(options);
-		const { spec, result } = await loadAndLint(specPath);
-		if (!spec) {
+//#region src/commands/plan.ts
+function registerPlan(program) {
+	program.command("plan").argument("<spec>", "spec file path or saved workflow name (auto-detected)").option("--global", "resolve saved workflow from global directory").option("--quiet", "suppress plan preview, show only issues").option("--json", "print JSON").action(async (spec, options) => {
+		const specPath = await resolveSpecArg({
+			spec,
+			global: options.global
+		});
+		const { spec: loaded, result } = await loadAndLint(specPath);
+		if (!loaded) {
 			if (options.json) printJson(result);
 			else printIssues(result);
 			process.exitCode = 1;
 			return;
 		}
-		const view = previewRunView(spec, [...result.warnings, ...result.errors], {
-			validate: `acpus validate --spec ${specPath}`,
-			run: `acpus run --spec ${specPath}`
+		if (options.quiet) {
+			if (options.json) printJson(result);
+			else printIssues(result);
+			if (!result.ok) process.exitCode = 1;
+			return;
+		}
+		const view = previewRunView(loaded, [...result.warnings, ...result.errors], {
+			plan: `acpus plan ${specPath}`,
+			run: `acpus run ${specPath}`
 		});
 		if (options.json) printJson(view);
 		else {
@@ -3338,27 +3489,6 @@ function registerPreview(program) {
 	});
 }
 //#endregion
-//#region src/commands/recover.ts
-function registerRecover(program) {
-	program.command("recover").argument("<run>", "logical run id or run directory").option("--json", "print JSON").action(async (runArg, options) => {
-		const recovered = await recoverDriver(runArg);
-		const output = {
-			ok: true,
-			runId: recovered.runId,
-			runDir: recovered.runDir,
-			worker: recovered.worker,
-			message: "Run worker recovered."
-		};
-		if (options.json) printJson(output);
-		else {
-			process.stdout.write(`${output.message}\n`);
-			process.stdout.write(`runId=${output.runId}\n`);
-			process.stdout.write(`runDir=${output.runDir}\n`);
-			process.stdout.write(`worker=${output.worker.pid} status=${output.worker.status}\n`);
-		}
-	});
-}
-//#endregion
 //#region src/runtime/resume-policy.ts
 function parseResumePolicyOptions(options) {
 	const fanout = {};
@@ -3409,7 +3539,7 @@ function parseResumePolicyOptions(options) {
 		issues
 	};
 }
-function validateResumePolicy(spec, policy) {
+function validateResumePolicy(spec, policy, plan) {
 	const issues = [];
 	const stageIds = spec.stages.map((stage) => stage.id);
 	for (const [stageId, fanoutPolicy] of Object.entries(policy.fanout)) {
@@ -3436,15 +3566,15 @@ function validateResumePolicy(spec, policy) {
 			}));
 			continue;
 		}
-		const hasEditLane = stage.laneGroups.some((group) => group.lanes.some((lane) => spec.roles[lane.role]?.mode === "edit"));
+		const hasEditLane = stage.lanes.some((lane) => lane.actor.mode === "edit");
 		if (fanoutPolicy.allowPartial && hasEditLane) issues.push(issue({
 			code: "RESUME_POLICY_PARTIAL_REQUIRES_READONLY",
 			severity: "error",
 			path: `${policyPath}/allowPartial`,
 			message: `Resume cannot enable partial results for edit fanout stage ${stageId}.`,
-			suggestions: ["Use diagnose for recovery advice, then start a new run if edit recovery is needed."]
+			suggestions: ["Inspect monitor details, then start a new run if edit recovery is needed."]
 		}));
-		const compiledMaxItems = stage.limits?.maxFanoutItems ?? 1;
+		const compiledMaxItems = plan?.fanout.find((entry) => entry.stageId === stageId)?.maxItems ?? staticLimitOrDefault(stage.limits?.maxFanoutItems, 1);
 		if (fanoutPolicy.maxItems !== void 0 && fanoutPolicy.maxItems > compiledMaxItems) issues.push(issue({
 			code: "RESUME_POLICY_MAX_ITEMS_NOT_TIGHTENING",
 			severity: "error",
@@ -3487,36 +3617,56 @@ function parseStageInteger(value) {
 }
 //#endregion
 //#region src/commands/resume.ts
+const TERMINAL_STATUSES = new Set(["completed", "cancelled"]);
 function registerResume(program) {
-	program.command("resume").argument("<run>", "logical run id or run directory").option("--allow-partial-fanout <stage...>", "allow partial results for read-only fanout stage(s) on resume").option("--max-fanout-items <stage=count...>", "tighten max fanout items for stage(s), bounded by the compiled snapshot").option("--skip-fanout-item <stage=index...>", "skip zero-based fanout item index(es) on resume").option("--wait", "advance until terminal").option("--json", "print JSON").action(async (runArg, options) => {
+	program.command("resume").argument("<run>", "logical run id or run directory").option("--allow-partial-fanout <stage...>", "allow partial results for read-only fanout stage(s) on resume").option("--max-fanout-items <stage=count...>", "tighten max fanout items for stage(s), bounded by the compiled snapshot").option("--skip-fanout-item <stage=index...>", "skip zero-based fanout item index(es) on resume").option("--force", "bypass active-worker check to restart a stale worker").option("--wait", "advance until terminal").option("--json", "print JSON").action(async (runArg, options) => {
 		const locator = await resolveRunLocator(runArg);
 		const spec = await readRunSpec(locator.cwd, locator.runId);
+		const plan = await readRunPlan(locator.cwd, locator.runId);
 		const parsedPolicy = parseResumePolicyOptions(options);
-		const policyIssues = [...parsedPolicy.issues, ...validateResumePolicy(spec, parsedPolicy.policy)];
+		const policyIssues = [...parsedPolicy.issues, ...validateResumePolicy(spec, parsedPolicy.policy, plan)];
 		if (policyIssues.some((entry) => entry.severity !== "warning")) {
 			printResumeIssues(options.json, policyIssues);
 			process.exitCode = 2;
 			return;
 		}
 		const index = await readRunIndex(locator.cwd, locator.runId);
-		if (index.status !== "blocked" && index.status !== "failed" && index.status !== "diagnosed_blocked") {
+		const allowedStatuses = options.force ? new Set([
+			"blocked",
+			"failed",
+			"running",
+			"pending"
+		]) : new Set(["blocked", "failed"]);
+		if (TERMINAL_STATUSES.has(index.status) || !allowedStatuses.has(index.status)) {
+			const hint = options.force && (index.status === "running" || index.status === "pending") ? "Use monitor to observe the active run." : index.status === "running" || index.status === "pending" ? "Use monitor to observe the active run, recover if its worker is stale, or use --force to bypass." : "Start a new run for completed workflows.";
 			printResumeIssues(options.json, [issue({
 				code: "RESUME_POLICY_INVALID",
 				severity: "error",
 				path: "/",
-				message: `Run ${locator.runId} is ${index.status}; resume is only for blocked, failed, or diagnosed_blocked runs.`,
-				suggestions: [index.status === "running" || index.status === "pending" ? "Use monitor to observe the active run, or recover if its worker is stale." : "Start a new run for completed workflows."]
+				message: `Run ${locator.runId} is ${index.status}; resume is only for blocked or failed runs${options.force ? " (or running with --force)" : ""}.`,
+				suggestions: [hint]
 			})]);
 			process.exitCode = 2;
 			return;
 		}
-		if (workerIsActive(index.worker)) {
+		if (workerIsActive(index.worker) && !options.force) {
 			printResumeIssues(options.json, [issue({
 				code: "RESUME_POLICY_INVALID",
 				severity: "error",
 				path: "/",
 				message: `Run ${locator.runId} already has an active worker pid=${index.worker?.pid}; resume cannot take ownership.`,
-				suggestions: ["Use monitor to observe the active run, or recover after the worker becomes stale."]
+				suggestions: ["Use monitor to observe the active run, recover after the worker becomes stale, or use --force to bypass."]
+			})]);
+			process.exitCode = 2;
+			return;
+		}
+		if (workerIsActive(index.worker) && options.force) {
+			printResumeIssues(options.json, [issue({
+				code: "RESUME_POLICY_INVALID",
+				severity: "error",
+				path: "/",
+				message: `Run ${locator.runId} has an active worker pid=${index.worker?.pid}; --force cannot take ownership of an active worker.`,
+				suggestions: ["Use monitor to observe the active run, or wait for the worker to become stale."]
 			})]);
 			process.exitCode = 2;
 			return;
@@ -3528,7 +3678,7 @@ function registerResume(program) {
 		await writeRunIndex(locator.cwd, reset);
 		let finalIndex;
 		try {
-			finalIndex = options.wait ? await runWorkflowWorker(locator.cwd, locator.runId) : await readRunIndex(locator.cwd, locator.runId);
+			finalIndex = options.wait ? await runWorkflowWorker(locator.cwd, locator.runId, { force: options.force }) : await readRunIndex(locator.cwd, locator.runId);
 			const worker = options.wait ? finalIndex.worker : await spawnBackgroundWorker(locator.cwd, locator.runId);
 			if (!options.wait) finalIndex = {
 				...await readRunIndex(locator.cwd, locator.runId),
@@ -3546,11 +3696,21 @@ function registerResume(program) {
 			message: options.wait ? "Run resume reached a terminal state." : "Run resume started a background worker."
 		};
 		if (options.json) printJson(output);
-		else process.stdout.write(`${output.message}\n`);
+		else {
+			process.stdout.write(`${output.message}\n`);
+			if (!options.wait) {
+				process.stdout.write(`runId=${output.runId}\n`);
+				process.stdout.write(`runDir=${runDir(locator.runId, locator.cwd)}\n`);
+				if (output.worker) process.stdout.write(`worker=${output.worker.pid ?? "unknown"}\n`);
+			}
+		}
 	});
 }
 async function readRunSpec(cwd, runId) {
-	return WorkflowSpecSchema.parse(JSON.parse(await fs.readFile(path.join(runDir(runId, cwd), "workflow.spec.json"), "utf8")));
+	return WorkflowSpecSchema.parse(YAML.parse(await fs.readFile(path.join(runDir(runId, cwd), "workflow.spec.yaml"), "utf8")));
+}
+async function readRunPlan(cwd, runId) {
+	return JSON.parse(await fs.readFile(path.join(runDir(runId, cwd), "execution-plan.json"), "utf8"));
 }
 function resetRecoverableStages(index, spec) {
 	const kindByStage = new Map(spec.stages.map((stage) => [stage.id, stage.kind]));
@@ -3605,8 +3765,17 @@ async function markKnownRunFatal$1(cwd, runId, error) {
 //#endregion
 //#region src/commands/run.ts
 function registerRun(program) {
-	program.command("run").option("--spec <path>", "workflow spec path").option("--workflow <name>", "saved workflow name").option("--global", "resolve saved workflow from global directory").option("--input-json <path>", "raw workflow input JSON file").option("--wait", "run in the foreground until the workflow reaches a terminal state").option("--json", "print JSON").action(async (options) => {
-		const specPath = resolveSpecPath(options);
+	program.command("run").argument("[spec]", "spec file path or workflow name").option("--global", "resolve saved workflow from global directory").option("--input <json-or-yaml-or-path>", "workflow input as an inline JSON object or JSON/YAML file path").option("--wait", "run in the foreground until the workflow reaches a terminal state").option("--json", "print JSON").action(async (specArg, options) => {
+		if (!specArg) {
+			if (options.json) printJson(resultFromIssues("run", []));
+			else process.stderr.write("Error: provide a spec file path or workflow name.\n");
+			process.exitCode = 1;
+			return;
+		}
+		const specPath = await resolveSpecArg({
+			spec: specArg,
+			global: options.global
+		});
 		const { spec, result } = await loadAndLint(specPath);
 		if (!spec || !result.ok) {
 			if (options.json) printJson(result);
@@ -3614,7 +3783,7 @@ function registerRun(program) {
 			process.exitCode = 1;
 			return;
 		}
-		const input = applyInputDefaults(spec, options.inputJson ? await readJsonFile(options.inputJson) : {});
+		const input = applyInputDefaults(spec, options.input ? await readInputArg(options.input) : {});
 		const inputResult = resultFromIssues("input", validateWorkflowInput(spec, input));
 		if (!inputResult.ok) {
 			if (options.json) printJson(inputResult);
@@ -3630,7 +3799,7 @@ function registerRun(program) {
 		try {
 			if (options.wait) {
 				const finalIndex = await runWorkflowWorker(process.cwd(), prepared.logicalRunId, { reporter: waitReporter(options.json) });
-				emitTerminalSummary(options.json, prepared.logicalRunId, prepared.dir, finalIndex);
+				await emitTerminalSummary(options.json, prepared.logicalRunId, prepared.dir, finalIndex, spec);
 				return;
 			}
 			const worker = await spawnBackgroundWorker(process.cwd(), prepared.logicalRunId);
@@ -3667,7 +3836,7 @@ function waitReporter(json) {
 		} else process.stdout.write(`worker exited pid=${event.pid} status=${event.status} exit=${event.exitCode ?? ""}\n`);
 	};
 }
-function emitTerminalSummary(json, runId, dir, index) {
+async function emitTerminalSummary(json, runId, dir, index, spec) {
 	const summary = {
 		type: "terminal_summary",
 		ok: index.status !== "failed" && index.status !== "cancelled",
@@ -3675,7 +3844,8 @@ function emitTerminalSummary(json, runId, dir, index) {
 		runDir: dir,
 		status: index.status,
 		blockedReason: index.blockedReason,
-		gateVerdict: index.gateVerdict
+		gateVerdict: index.gateVerdict,
+		finalOutput: json ? await readFinalOutput(dir, spec) : void 0
 	};
 	if (json) process.stdout.write(`${JSON.stringify(summary)}\n`);
 	else process.stdout.write(`terminal status=${summary.status}${summary.gateVerdict ? ` verdict=${summary.gateVerdict}` : ""}\n`);
@@ -3707,9 +3877,12 @@ function registerRunWorker(program) {
 //#endregion
 //#region src/commands/save.ts
 function registerSave(program) {
-	program.command("save").argument("<name>", "workflow name").requiredOption("--spec <path>", "workflow spec path").option("--overwrite", "overwrite existing workflow").option("--global", "save to global workflow directory").option("--json", "print JSON").action(async (name, options) => {
-		const { spec, result } = await loadAndLint(options.spec);
-		if (!spec || !result.ok) {
+	program.command("save").argument("<name>", "workflow name").argument("<spec>", "spec file path or workflow name").option("--overwrite", "overwrite existing workflow").option("--global", "save to global workflow directory").option("--json", "print JSON").action(async (name, spec, options) => {
+		const { spec: workflowSpec, result } = await loadAndLint(await resolveSpecArg({
+			spec,
+			global: options.global
+		}));
+		if (!workflowSpec || !result.ok) {
 			if (options.json) printJson(result);
 			else printIssues(result);
 			process.exitCode = 1;
@@ -3719,11 +3892,11 @@ function registerSave(program) {
 		const target = path.join(root, name);
 		await ensureEmptyOrOverwrite(target, options.overwrite);
 		await fs.mkdir(target, { recursive: true });
-		const plan = compileExecutionPlan(spec);
-		await fs.writeFile(path.join(target, "workflow.spec.json"), `${JSON.stringify(spec, null, 2)}\n`, "utf8");
+		const plan = compileExecutionPlan(workflowSpec, { input: applyInputDefaults(workflowSpec) });
+		await fs.writeFile(path.join(target, "workflow.spec.yaml"), stringifyWorkflowSpec(workflowSpec), "utf8");
 		await fs.writeFile(path.join(target, "execution-plan.json"), `${JSON.stringify(plan, null, 2)}\n`, "utf8");
 		await writeHelperSnapshot(target);
-		await fs.writeFile(path.join(target, "README.md"), `# ${name}\n\n${spec.description || "Saved acpus workflow."}\n\nThis directory is a saved runtime-driven workflow snapshot. The stable authoring interface is workflow.spec.json; execution-plan.json is the derived runtime plan and should normally be regenerated from the spec.\n\nRun with acpus using workflow.spec.json.\n`, "utf8");
+		await fs.writeFile(path.join(target, "README.md"), `# ${name}\n\n${workflowSpec.description || "Saved acpus workflow."}\n\nThis directory is a saved runtime-driven workflow snapshot. The stable authoring interface is workflow.spec.yaml; execution-plan.json is the derived runtime plan and should normally be regenerated from the spec.\n\nRun with acpus using workflow.spec.yaml.\n`, "utf8");
 		const output = {
 			ok: true,
 			workflow: name,
@@ -3799,48 +3972,32 @@ async function ascendToPackageRoot(start) {
 //#endregion
 //#region src/commands/show.ts
 function registerShow(program) {
-	program.command("show").argument("<kind>", "workflow|run|draft").argument("<name>", "name or run id").option("--global", "show global workflow").option("--json", "print JSON").action(async (kind, name, options) => {
-		const file = await resolveShowFile(kind, name, options.global);
-		if (!file) throw new Error("kind must be workflow, run, or draft");
+	const show = program.command("show");
+	show.command("workflow").argument("<name>", "workflow name").option("--global", "show global workflow").option("--json", "print JSON").action(async (name, options) => {
+		const file = path.join(options.global ? globalWorkflowsDir() : projectWorkflowsDir(), name, "workflow.spec.yaml");
 		const text = await fs.readFile(file, "utf8");
-		if (options.json) printJson(JSON.parse(text));
+		if (options.json) printJson(YAML.parse(text));
 		else process.stdout.write(text);
 	});
-}
-async function resolveShowFile(kind, name, global) {
-	if (kind === "workflow") return path.join(global ? globalWorkflowsDir() : projectWorkflowsDir(), name, "workflow.spec.json");
-	if (kind === "run") {
-		const locator = await resolveRunLocator(name);
-		return path.join(runDir(locator.runId, locator.cwd), "run.json");
-	}
-	if (kind === "draft") return path.join(draftsDir(), name);
-	return "";
-}
-//#endregion
-//#region src/commands/validate.ts
-function registerValidate(program) {
-	program.command("validate").option("--spec <path>", "workflow spec path").option("--workflow <name>", "saved workflow name").option("--global", "resolve saved workflow from global directory").option("--json", "print JSON").action(async (options) => {
-		const { result } = await loadAndLint(resolveSpecPath(options));
-		if (options.json) printJson(result);
-		else printIssues(result);
-		if (!result.ok) process.exitCode = 1;
+	show.command("run").argument("<id>", "run id or directory").option("--json", "print JSON").action(async (id, options) => {
+		const locator = await resolveRunLocator(id);
+		const file = path.join(runDir(locator.runId, locator.cwd), "run.json");
+		const text = await fs.readFile(file, "utf8");
+		if (options.json) printJson(JSON.parse(text));
+		else process.stdout.write(text);
 	});
 }
 //#endregion
 //#region src/cli.ts
 const program = new Command();
-program.name("acpus").description("Acpus — compose, conduct, recover, catalogue.").version("0.1.0");
-registerValidate(program);
-registerPreview(program);
+program.name("acpus").description("Acpus — compose, conduct, catalogue.").version("0.1.0");
+registerPlan(program);
 registerSave(program);
-registerGenerate(program);
 registerRun(program);
 registerFollow(program);
 registerMonitor(program);
 registerResume(program);
 registerRunWorker(program);
-registerRecover(program);
-registerDiagnose(program);
 registerList(program);
 registerShow(program);
 program.parseAsync(process.argv).catch((error) => {
@@ -3857,4 +4014,4 @@ program.parseAsync(process.argv).catch((error) => {
 	process.exitCode = 1;
 });
 //#endregion
-export {};
+export { resolveRunLocator as n, listRunSummaries as t };