@duyquangnvx/create-agent-cli 0.3.0 → 0.5.0

package/dist/bin.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
+import { parseArgs, parseEnv } from "node:util";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { access, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { access, chmod, link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { constants, existsSync, readFileSync, realpathSync } from "node:fs";
+import { constants as constants$1, homedir, tmpdir } from "node:os";
 import { spawn } from "node:child_process";
-import { constants, homedir, tmpdir } from "node:os";
-import { constants as constants$1, existsSync, readFileSync, realpathSync } from "node:fs";
-import { parseArgs, parseEnv } from "node:util";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 //#region ../../node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/core/util.js
 function getEnumValues(entries) {
@@ -2817,7 +2818,7 @@ function bucketFor(state, inst) {
 	return bucket;
 }
 let handoff;
-const open = [];
+const open$1 = [];
 const memo = {
 	alloc(_inst, payload, empty) {
 		const bucket = handoff;
@@ -2828,7 +2829,7 @@ const memo = {
 			issues: null
 		};
 		bucket.set(payload.value, entry);
-		open.push(entry);
+		open$1.push(entry);
 		return empty;
 	},
 	guard(inst) {
@@ -2894,10 +2895,10 @@ const memo = {
 					return payload;
 				}
 				handoff = bucket;
-				const depth = open.length;
+				const depth = open$1.length;
 				const result = base(payload, ctx);
 				handoff = void 0;
-				const entry = open.length > depth ? open.pop() : void 0;
+				const entry = open$1.length > depth ? open$1.pop() : void 0;
 				if (result instanceof Promise) return result.then((r) => {
 					if (entry) entry.issues = r.issues.length ? cloneIssues(r.issues) : NO_ISSUES;
 					return r;
@@ -5581,6 +5582,54 @@ function untilAborted(signal) {
 	});
 }
 //#endregion
+//#region ../agent-cli/dist/stdin.js
+const STDIN_META = "stdin";
+function isStdinSchema(schema) {
+	return globalRegistry.get(schema)?.[STDIN_META] === true;
+}
+function endOfInputKeys(platform) {
+	return platform === "win32" ? "Ctrl-Z then Enter" : "Ctrl-D";
+}
+/** The progress line shown before reading a terminal, so a person isn't left facing silence. */
+function readingLine(name, platform) {
+	return `reading <${name}> from stdin; end it with ${endOfInputKeys(platform)}`;
+}
+function isTerminal(source) {
+	return typeof source !== "string" && "isTTY" in source && source.isTTY === true;
+}
+/** The whole of `source` as UTF-8; rejects with the signal's reason once it aborts. */
+function readStdin(source, signal) {
+	if (typeof source === "string") return signal.aborted ? Promise.reject(signal.reason) : Promise.resolve(source);
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		const onData = (chunk) => {
+			chunks.push(chunk instanceof Uint8Array ? chunk : Buffer.from(String(chunk)));
+		};
+		const onEnd = () => {
+			stop();
+			resolve(Buffer.concat(chunks).toString("utf8"));
+		};
+		const onError = (error) => {
+			stop();
+			reject(error);
+		};
+		const onAbort = () => {
+			stop();
+			reject(signal.reason);
+		};
+		const stop = () => {
+			source.off("data", onData).off("end", onEnd).off("error", onError).pause();
+			signal.removeEventListener("abort", onAbort);
+		};
+		if (signal.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+		source.on("data", onData).once("end", onEnd).once("error", onError);
+	});
+}
+//#endregion
 //#region ../agent-cli/dist/input.js
 function isWrapper(schema) {
 	return schema instanceof ZodOptional || schema instanceof ZodNullable || schema instanceof ZodDefault || schema instanceof ZodPrefault;
@@ -5597,27 +5646,39 @@ function describe(schema) {
 	let description = current.description;
 	let required = true;
 	let defaultValue;
+	let stdin = isStdinSchema(current);
 	while (isWrapper(current)) {
 		if (current instanceof ZodDefault || current instanceof ZodPrefault) defaultValue = current.def.defaultValue;
 		required = false;
 		current = current.unwrap();
 		description ??= current.description;
+		stdin ||= isStdinSchema(current);
 	}
+	const variadic = current instanceof ZodArray;
+	if (current instanceof ZodArray) current = current.element;
 	return {
 		type: typeOf(current),
 		required,
 		defaultValue,
 		description,
-		choices: current instanceof ZodEnum ? current.options.map(String) : void 0
+		choices: current instanceof ZodEnum ? current.options.map(String) : void 0,
+		variadic,
+		stdin
 	};
 }
+function argLabel(key, { variadic, required, stdin }) {
+	if (stdin) return required ? `<${key}|->` : `[${key}|-]`;
+	if (!variadic) return `<${key}>`;
+	return required ? `<${key}...>` : `[${key}...]`;
+}
 function argField(key, schema) {
-	const label = `<${key}>`;
+	const described = describe(schema);
+	const label = argLabel(key, described);
 	return {
 		key,
 		name: key,
 		schema,
-		...describe(schema),
+		...described,
 		label,
 		usage: label
 	};
@@ -5627,7 +5688,8 @@ function optionField(key, schema) {
 	const name = kebab(key);
 	const isBoolean = described.type === "boolean";
 	const label = isBoolean && described.defaultValue === true ? `--no-${name}` : `--${name}`;
-	const usage = isBoolean ? label : `${label} <${described.choices?.join("|") ?? "value"}>`;
+	const value = `<${described.choices?.join("|") ?? "value"}>${described.variadic ? "..." : ""}`;
+	const usage = isBoolean ? label : `${label} ${value}`;
 	return {
 		key,
 		name,
@@ -5643,9 +5705,32 @@ function fieldsOf$1(schema, toField) {
 function argFields(schema) {
 	return fieldsOf$1(schema, argField);
 }
+function keysOf(fields) {
+	return fields.map(({ key }) => `'${key}'`).join(", ");
+}
+/** Throws when an arg that takes every remaining operand is not the last arg. */
+function checkArrayArgLast(name, args) {
+	const misplaced = argFields(args).slice(0, -1).filter((field) => field.variadic);
+	if (misplaced.length > 0) throw new Error(`Command '${name}' declares array arg ${keysOf(misplaced)} before its last arg; only the last arg may be an array`);
+}
+/** Throws unless at most one arg, and no option, is marked with `orStdin`. */
+function checkStdinFields(name, args, options) {
+	const stdinArgs = argFields(args).filter((field) => field.stdin);
+	if (stdinArgs.length > 1) throw new Error(`Command '${name}' marks args ${keysOf(stdinArgs)} with orStdin; only one arg may read stdin`);
+	const stdinOptions = optionFields(options).filter((field) => field.stdin);
+	if (stdinOptions.length > 0) {
+		const noun = stdinOptions.length === 1 ? "option" : "options";
+		throw new Error(`Command '${name}' marks ${noun} ${keysOf(stdinOptions)} with orStdin; only an arg may read stdin`);
+	}
+}
 function optionFields(schema) {
 	return fieldsOf$1(schema, optionField);
 }
+/** Throws when an option is an array of booleans, which a switch cannot express. */
+function checkNoBooleanArrayOption(name, options) {
+	const booleans = optionFields(options).filter((field) => field.variadic && field.type === "boolean");
+	if (booleans.length > 0) throw new Error(`Command '${name}' declares boolean array option ${keysOf(booleans)}; a switch cannot repeat, use a boolean`);
+}
 //#endregion
 //#region ../agent-cli/dist/errors.js
 var CliError = class extends Error {
@@ -5676,6 +5761,9 @@ function errnoOf(error) {
 function isMissingFile(error) {
 	return errnoOf(error) === "ENOENT";
 }
+function isNothingThere(error) {
+	return isMissingFile(error) || errnoOf(error) === "ENOTDIR";
+}
 function debugVariable(cliName) {
 	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
 }
@@ -5740,6 +5828,89 @@ function formatRuntimeError(error, format) {
 	}
 	return errors.map((each) => errorLines(each, format)).join("");
 }
+//#endregion
+//#region ../agent-cli/dist/tokenize.js
+const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
+function isOptionLike(word) {
+	return word !== void 0 && word.length > 1 && word[0] === "-" && !NEGATIVE_NUMBER.test(word);
+}
+function parseArgsOptions(known) {
+	return Object.fromEntries(known.map(({ flag, takes }) => [flag.slice(2), { type: takes === "value" ? "string" : "boolean" }]));
+}
+function flagItem(token, { flag, takes }, words) {
+	if (takes !== "optional value" || token.inlineValue === true) return {
+		kind: "flag",
+		flag,
+		value: token.value ?? true
+	};
+	const took = token.index + 1;
+	const next = words[took];
+	return next === void 0 || isOptionLike(next) ? {
+		kind: "flag",
+		flag,
+		value: true
+	} : {
+		kind: "flag",
+		flag,
+		value: next,
+		took
+	};
+}
+function itemOf(token, words, byFlag) {
+	const word = words[token.index] ?? "";
+	if (token.kind === "option-terminator") return { kind: "end" };
+	if (token.kind === "positional" || NEGATIVE_NUMBER.test(word)) return {
+		kind: "operand",
+		value: word
+	};
+	const flag = byFlag.get(token.rawName);
+	return flag === void 0 || flag.takes === "nothing" && token.inlineValue === true ? {
+		kind: "unknown option",
+		word
+	} : flagItem(token, flag, words);
+}
+/** Splits a Command's words into operands, unknown options and the values of known flags. */
+function tokenize(words, known) {
+	const byFlag = new Map(known.map((flag) => [flag.flag, flag]));
+	const { tokens } = parseArgs({
+		args: [...words],
+		options: parseArgsOptions(known),
+		strict: false,
+		allowPositionals: true,
+		tokens: true
+	});
+	const operands = [];
+	const unknownOptions = [];
+	const occurrences = /* @__PURE__ */ new Map();
+	const done = /* @__PURE__ */ new Set();
+	let literal = false;
+	let afterUnknownOption = false;
+	for (const token of tokens) {
+		if (done.has(token.index)) continue;
+		done.add(token.index);
+		const item = itemOf(token, words, byFlag);
+		if (item.kind === "end") literal = true;
+		else if (item.kind === "operand") {
+			operands.push({
+				value: item.value,
+				afterUnknownOption: !literal && afterUnknownOption
+			});
+			afterUnknownOption = false;
+		} else if (item.kind === "unknown option") {
+			unknownOptions.push(item.word);
+			afterUnknownOption = true;
+		} else {
+			occurrences.set(item.flag, [...occurrences.get(item.flag) ?? [], item.value]);
+			if (item.took !== void 0) done.add(item.took);
+		}
+	}
+	return {
+		operands,
+		unknownOptions,
+		values: new Map([...occurrences].map(([flag, all]) => [flag, all[all.length - 1] ?? true])),
+		occurrences
+	};
+}
 const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
 function quoted$1(token) {
 	return SHELL_SAFE.test(token) ? token : `'${token.replaceAll("'", `'\\''`)}'`;
@@ -5747,10 +5918,6 @@ function quoted$1(token) {
 function pasteable(cliName, tokens) {
 	return [cliName, ...tokens].map(quoted$1).join(" ");
 }
-/** The caller's command line as typed, ready to paste. */
-function commandLineOf({ cliName, argv }) {
-	return pasteable(cliName, argv);
-}
 function split(argv) {
 	const end = argv.indexOf("--");
 	return end === -1 ? {
@@ -5761,19 +5928,29 @@ function split(argv) {
 		operands: argv.slice(end)
 	};
 }
-function without(flag, tokens) {
-	return tokens.filter((token, index) => token !== flag && !token.startsWith(`${flag}=`) && tokens[index - 1] !== flag);
+function tookValue(takes, next) {
+	return takes === "value" || takes === "optional value" && next !== void 0 && !isOptionLike(next);
+}
+function without(flag, takes, tokens) {
+	const kept = [];
+	for (let index = 0; index < tokens.length; index += 1) {
+		const token = tokens[index] ?? "";
+		if (token === flag) {
+			if (tookValue(takes, tokens[index + 1])) index += 1;
+		} else if (!token.startsWith(`${flag}=`)) kept.push(token);
+	}
+	return kept;
 }
 /**
-* The caller's command line, ready to paste, with `flag value` (or `flag` alone, for a flag that
-* takes nothing) replacing any value they gave.
+* The caller's command line as typed, ready to paste, with each flag in `remove` dropped along with
+* its value and the words in `add` placed before any `--`.
 */
-function commandLineWith({ cliName, argv }, flag, value) {
+function commandLineOf({ cliName, argv, flags }, { add = [], remove = [] } = {}) {
 	const { options, operands } = split(argv);
-	const added = value === void 0 ? [flag] : [flag, value];
+	const takes = new Map(flags.map((known) => [known.flag, known.takes]));
 	return pasteable(cliName, [
-		...without(flag, options),
-		...added,
+		...remove.reduce((tokens, flag) => without(flag, takes.get(flag) ?? "nothing", tokens), options),
+		...add,
 		...operands
 	]);
 }
@@ -5926,7 +6103,10 @@ function renderRows(rows, fields) {
 function printedPage(page, invocation) {
 	return page.nextCursor === void 0 ? { items: page.items } : {
 		items: page.items,
-		next: commandLineWith(invocation, PAGE_FLAGS.cursor.flag, String(page.nextCursor))
+		next: commandLineOf(invocation, {
+			remove: [PAGE_FLAGS.cursor.flag],
+			add: [PAGE_FLAGS.cursor.flag, String(page.nextCursor)]
+		})
 	};
 }
 /** The line that ends a rendered page, so the caller always knows whether and how to get more. */
@@ -5935,6 +6115,12 @@ function pageFooter({ items, next }) {
 	return `${items.length} shown; ${more}\n`;
 }
 //#endregion
+//#region ../agent-cli/dist/planned.js
+/** Whether `command` changes something through a Plan: a write or destructive Command. */
+function hasPlan(command) {
+	return command.effect === "write" || command.effect === "destructive";
+}
+//#endregion
 //#region ../agent-cli/dist/flags.js
 const HELP_FLAG = "--help";
 const VERSION_FLAG = "--version";
@@ -5997,10 +6183,14 @@ const RESERVED = new Map([
 	...LIST_FLAGS
 ].map((flag) => [nameOf(flag), flag]));
 /** The Standard flags of a Command with this Effect and declarations, and of a List Command. */
-function standardFlagsFor(effect, { outputs, cost }, list) {
+function standardFlagsFor(effect, { outputs, force, cost }, list) {
+	const forceFlag = force === void 0 ? FORCE_FLAG : {
+		...FORCE_FLAG,
+		description: force
+	};
 	return [
 		...EFFECT_FLAGS[effect],
-		...outputs ? [FORCE_FLAG] : [],
+		...outputs || force !== void 0 ? [forceFlag] : [],
 		...cost ? [YES_FLAG] : [],
 		...list?.standardFlags ?? []
 	];
@@ -6019,10 +6209,21 @@ function checkNoStandardFlags(command) {
 	});
 	if (lines.length > 0) throw new Error([`Command '${command.name}' declares Standard flags the Runtime adds; rename them:`, ...lines].join("\n"));
 }
+/** Throws when `force` is declared on a Command with no Plan, or says nothing. */
+function checkForce(command) {
+	const force = "force" in command ? command.force : void 0;
+	if (force === void 0) return;
+	if (!hasPlan(command)) throw new Error(`Command '${command.name}' declares force, which only a write or destructive Command may`);
+	if (force.trim() === "") throw new Error(`Command '${command.name}' declares an empty force; say what ${FORCE_FLAG.flag} replaces`);
+}
 //#endregion
 //#region ../agent-cli/dist/define.js
 function checkedCommand(command) {
 	checkNoStandardFlags(command);
+	checkForce(command);
+	checkArrayArgLast(command.name, command.args);
+	checkStdinFields(command.name, command.args, command.options);
+	checkNoBooleanArrayOption(command.name, command.options);
 	return command;
 }
 function defineCommandFor() {
@@ -6100,22 +6301,259 @@ function lastLines(output, count) {
 	return output.trim().split("\n").slice(-count).join("\n");
 }
 //#endregion
+//#region ../agent-cli/dist/tools.js
+const TOOL_MISSING = "TOOL_MISSING";
+const WINDOWS_EXTENSIONS = ".COM;.EXE;.BAT;.CMD";
+function pathOf(env) {
+	return env[Object.keys(env).find((name) => name.toUpperCase() === "PATH") ?? "PATH"] ?? "";
+}
+function extensionsOf(env) {
+	return process.platform === "win32" ? (env.PATHEXT ?? WINDOWS_EXTENSIONS).split(";") : [""];
+}
+async function isExecutable(file) {
+	try {
+		await access(file, constants.X_OK);
+		return true;
+	} catch (error) {
+		if (isNothingThere(error) || errnoOf(error) === "EACCES") return false;
+		throw error;
+	}
+}
+/** The file names `name` may have on `PATH`: itself when it already ends in one of the extensions. */
+function fileNamesOf(name, env) {
+	const extensions = extensionsOf(env);
+	const own = extname(name).toUpperCase();
+	return own !== "" && extensions.some((extension) => extension.toUpperCase() === own) ? [name] : extensions.map((extension) => `${name}${extension}`);
+}
+/** Where `name` is found on `PATH` from `env`, or undefined. */
+async function findTool(name, env) {
+	const candidates = pathOf(env).split(delimiter).filter((folder) => folder !== "").flatMap((folder) => fileNamesOf(name, env).map((file) => join(folder, file)));
+	for (const file of candidates) if (await isExecutable(file)) return file;
+}
+/** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
+async function checkTools(tools, env) {
+	const found = await Promise.all(tools.map((tool) => findTool(tool.name, env)));
+	const missing = tools.filter((_tool, index) => found[index] === void 0);
+	if (missing.length === 0) return;
+	const names = missing.map(({ name }) => name).join(", ");
+	throw new CliError({
+		code: TOOL_MISSING,
+		message: `${missing.length === 1 ? "a tool it runs is" : "tools it runs are"} not on PATH: ${names}`,
+		hint: `install ${missing.length === 1 ? "it" : "them"}, then run the same command again: ${missing.map(({ install }) => install).join("; ")}`
+	});
+}
+function toolsIn(node) {
+	return isCommand(node) ? [...node.tools ?? []] : Object.values(node).flatMap(toolsIn);
+}
+/** One `doctor` row per distinct tool the CLI and its Commands declare, with its install command as the fix. */
+function toolRows(tools, commands) {
+	return [...new Map([...tools, ...toolsIn(commands)].map((tool) => [tool.name, tool])).values()].map(({ name, install }) => ({
+		name,
+		run: async (ctx) => {
+			const file = await findTool(name, ctx.env);
+			return file === void 0 ? {
+				state: "problem",
+				message: `${name} is not on PATH`,
+				fix: install
+			} : {
+				state: "ok",
+				message: `found at ${file}`
+			};
+		}
+	}));
+}
+//#endregion
+//#region ../agent-cli/dist/spawn.js
+const TOOL_FAILED = "TOOL_FAILED";
+const STDERR_TAIL_LINES$1 = 20;
+const SIGNAL_EXIT_BASE = 128;
+const BATCH_FILE = /\.(?:cmd|bat)$/i;
+const CMD_SHIM = /\.cmd$/i;
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+const PATH_SEPARATOR = /[\\/]/;
+const TRAILING_CR = /\r$/;
+function escapedForCmd(text) {
+	return text.replace(CMD_META, "^$1");
+}
+function batchArgument(arg, shim) {
+	const escaped = escapedForCmd(`"${arg.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\*)$/, "$1$1")}"`);
+	return shim ? escapedForCmd(escaped) : escaped;
+}
+function batchCommandLine(command, file, args) {
+	const shim = CMD_SHIM.test(file);
+	return [escapedForCmd(command), ...args.map((arg) => batchArgument(arg, shim))].join(" ");
+}
+async function windowsLaunch(command, args, env) {
+	const file = PATH_SEPARATOR.test(command) ? command : await findTool(command, env);
+	if (file === void 0 || !BATCH_FILE.test(file)) return {
+		command,
+		args,
+		shell: false
+	};
+	return {
+		command: batchCommandLine(command, file, args),
+		args: [],
+		shell: true
+	};
+}
+function stop(child) {
+	if (process.platform !== "win32" || child.pid === void 0) {
+		child.kill();
+		return Promise.resolve();
+	}
+	const pid = String(child.pid);
+	return new Promise((resolve) => {
+		const taskkill = spawn("taskkill", [
+			"/pid",
+			pid,
+			"/t",
+			"/f"
+		], {
+			stdio: "ignore",
+			windowsHide: true
+		});
+		taskkill.once("error", () => {
+			child.kill();
+			resolve();
+		});
+		taskkill.once("exit", () => resolve());
+	});
+}
+/** Calls `onLine` with each complete line pushed, and with the unterminated rest at the end. */
+function lineSplitter(onLine) {
+	let rest = "";
+	const emit = (line) => onLine?.(line.replace(TRAILING_CR, ""));
+	return {
+		push(text) {
+			if (onLine === void 0) return;
+			const lines = (rest + text).split("\n");
+			rest = lines.pop() ?? "";
+			for (const line of lines) emit(line);
+		},
+		end() {
+			if (rest !== "") emit(rest);
+			rest = "";
+		}
+	};
+}
+/**
+* Runs a child process to its end; it is killed on abort, and the promise settles only once it has
+* exited. A `detached` child leaves the terminal's process group on POSIX, and so its Ctrl-C.
+*/
+async function spawnChild(command, args, { cwd, env, signal, onLine, detached = false }) {
+	signal.throwIfAborted();
+	const launch = process.platform === "win32" ? await windowsLaunch(command, args, env) : {
+		command,
+		args,
+		shell: false
+	};
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const child = spawn(launch.command, launch.args, {
+			cwd,
+			env,
+			shell: launch.shell,
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			detached: detached && process.platform !== "win32"
+		});
+		let stdout = "";
+		let stderr = "";
+		const stdoutLines = lineSplitter(onLine);
+		const stderrLines = lineSplitter(onLine);
+		child.stdout.setEncoding("utf8").on("data", (chunk) => {
+			stdout += chunk;
+			stdoutLines.push(chunk);
+		});
+		child.stderr.setEncoding("utf8").on("data", (chunk) => {
+			stderr += chunk;
+			stderrLines.push(chunk);
+		});
+		let stopped = Promise.resolve();
+		const kill = () => {
+			stopped = stop(child);
+		};
+		signal.addEventListener("abort", kill, { once: true });
+		child.on("error", (error) => {
+			signal.removeEventListener("abort", kill);
+			reject(error);
+		});
+		child.on("close", (code, killedBy) => {
+			signal.removeEventListener("abort", kill);
+			if (signal.aborted) {
+				stopped.then(() => reject(signal.reason));
+				return;
+			}
+			stdoutLines.end();
+			stderrLines.end();
+			resolve({
+				stdout,
+				stderr,
+				exitCode: code ?? SIGNAL_EXIT_BASE + (killedBy === null ? 0 : constants$1.signals[killedBy])
+			});
+		});
+	});
+}
+const realSpawn = (command, args, options) => spawnChild(command, args, options);
+function failedError(command, { exitCode, stderr }) {
+	const tail = lastLines(stderr, STDERR_TAIL_LINES$1);
+	return new CliError({
+		code: TOOL_FAILED,
+		message: tail === "" ? `${command} exited with ${exitCode} and wrote nothing to stderr` : `${command} exited with ${exitCode}; its stderr ends:\n${tail}`,
+		hint: `the output of ${command} above says why it failed`
+	});
+}
+function missingError(command, cause) {
+	return new CliError({
+		code: TOOL_MISSING,
+		message: `${command} could not be started: it is not on PATH`,
+		hint: `install ${command}, then run the same command again`
+	}, { cause });
+}
+/** `ctx.spawn`: `spawn` bound to the run, its start failures classified by errno. */
+function contextSpawn(run, defaults, fileError) {
+	return async (command, args = [], options = {}) => {
+		let result;
+		try {
+			result = await run(command, args, {
+				cwd: options.cwd ?? defaults.cwd,
+				env: options.env ?? defaults.env,
+				signal: defaults.signal,
+				onLine: options.progress === true ? defaults.progress : void 0
+			});
+		} catch (error) {
+			if (isMissingFile(error)) throw missingError(command, error);
+			throw fileError(error, {
+				path: command,
+				access: "read"
+			});
+		}
+		if (options.check === true && result.exitCode !== 0) throw failedError(command, result);
+		return result;
+	};
+}
+//#endregion
 //#region ../agent-cli/dist/npm.js
 const REGISTRY_UNREACHABLE = "REGISTRY_UNREACHABLE";
 const REGISTRY_AUTH = "REGISTRY_AUTH";
 const INSTALL_FAILED = "INSTALL_FAILED";
 const NPM_FAILED = "NPM_FAILED";
 const NO_LATEST = "NO_LATEST";
-function npmContext(cli, install, ctx) {
+function npmContext(cli, install, ctx, node) {
 	return {
 		cliName: cli.name,
 		install,
 		env: ctx.env,
-		signal: ctx.signal
+		signal: ctx.signal,
+		node
 	};
 }
 const NPMJS = "https://registry.npmjs.org/";
-const STDERR_TAIL_LINES$1 = 10;
+const STDERR_TAIL_LINES = 10;
 const RM_RETRIES = 3;
 const NETWORK_CODES = /* @__PURE__ */ new Set([
 	"ENOTFOUND",
@@ -6145,40 +6583,36 @@ function installCommandLine(install, version = "latest") {
 		...registryFlags(install)
 	].join(" ");
 }
+function npmOf(ctx, windows) {
+	const beside = ctx.node === void 0 ? void 0 : join(dirname(ctx.node), windows ? "npm.cmd" : "npm");
+	if (beside === void 0 || !existsSync(beside)) return {
+		path: "npm",
+		env: ctx.env
+	};
+	if (windows) return {
+		path: beside,
+		env: ctx.env
+	};
+	const PATH = [dirname(beside), ctx.env.PATH].filter(Boolean).join(delimiter);
+	return {
+		path: beside,
+		env: {
+			...ctx.env,
+			PATH
+		}
+	};
+}
 function spawnNpm(args, ctx, signal) {
-	const windows = process.platform === "win32";
-	const command = windows ? ["npm", ...args.map((arg) => `"${arg.replaceAll("\"", "\"\"")}"`)].join(" ") : "npm";
-	return new Promise((resolve, reject) => {
-		const child = spawn(command, windows ? [] : args, {
-			env: ctx.env,
-			shell: windows,
-			windowsHide: true,
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			],
-			detached: signal === null && !windows,
-			signal: signal ?? void 0
-		});
-		let stdout = "";
-		let stderr = "";
-		child.stdout.setEncoding("utf8").on("data", (chunk) => {
-			stdout += chunk;
-		});
-		child.stderr.setEncoding("utf8").on("data", (chunk) => {
-			stderr += chunk;
-		});
-		child.on("error", reject);
-		child.on("close", (exitCode) => resolve({
-			exitCode,
-			stdout,
-			stderr
-		}));
+	const npm = npmOf(ctx, process.platform === "win32");
+	return spawnChild(npm.path, args, {
+		cwd: process.cwd(),
+		env: npm.env,
+		signal: signal ?? new AbortController().signal,
+		detached: signal === null
 	});
 }
 function tail$1(stderr) {
-	const lines = lastLines(stderr, STDERR_TAIL_LINES$1);
+	const lines = lastLines(stderr, STDERR_TAIL_LINES);
 	return lines === "" ? "" : `\n${lines}`;
 }
 function failureOf(call, answer, ctx) {
@@ -6326,7 +6760,10 @@ const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
 const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
 function checkConfirmation({ invocation, commandLine, given }, expected) {
 	if (given === expected) return;
-	const hint = `to confirm, run \`${commandLineWith(invocation, CONFIRM_FLAG.flag, expected)}\``;
+	const hint = `to confirm, run \`${commandLineOf(invocation, {
+		remove: [CONFIRM_FLAG.flag],
+		add: [CONFIRM_FLAG.flag, expected]
+	})}\``;
 	if (given === void 0) throw new UsageError({
 		code: CONFIRMATION_REQUIRED,
 		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
@@ -6347,51 +6784,95 @@ function checkCost({ invocation, commandLine, yes }, cost) {
 	throw new CliError({
 		code: NOT_CONFIRMED,
 		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
-		hint: `to approve the cost, run \`${commandLineWith(invocation, YES_FLAG.flag)}\``
+		hint: `to approve the cost, run \`${commandLineOf(invocation, { add: [YES_FLAG.flag] })}\``
 	});
 }
 //#endregion
 //#region ../agent-cli/dist/agent.js
-const AGENT_VARIABLES = [
-	"CLAUDECODE",
-	"CODEX_CI",
-	"CODEX_SANDBOX",
-	"GEMINI_CLI",
-	"CURSOR_AGENT",
-	"CI"
+const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
+const isSet = (name) => (env) => (env[name] ?? "") !== "";
+const equals = (name, value) => (env) => env[name] === value;
+const MARKERS = [
+	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
+	equals("AGENT", "amp"),
+	isSet("CODEX_SANDBOX"),
+	isSet("CODEX_CI"),
+	isSet("CODEX_THREAD_ID"),
+	isSet("GEMINI_CLI"),
+	isSet("COPILOT_CLI"),
+	isSet("OPENCODE"),
+	isSet("ANTIGRAVITY_AGENT"),
+	isSet("AUGMENT_AGENT"),
+	isSet("REPL_ID"),
+	isSet("CLAUDE_CODE_IS_COWORK"),
+	isSet("CLAUDECODE"),
+	isSet("CLAUDE_CODE"),
+	isSet("CURSOR_TRACE_ID"),
+	isSet("CURSOR_AGENT"),
+	equals("CURSOR_EXTENSION_HOST_ROLE", "agent-exec"),
+	equals("TERM_PROGRAM", "kiro"),
+	(env) => ["/.pi/agent", "\\.pi\\agent"].some((dir) => (env.PATH ?? "").includes(dir)),
+	isSet("GOOSE_PROVIDER")
 ];
-/** Whether a Coding agent, not a person, is running the Agent CLI. */
+/**
+* Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
+* in a PTY, so a TTY alone doesn't mean a person is watching.
+*/
 function isAgent(env) {
-	return AGENT_VARIABLES.some((name) => env[name] !== void 0);
+	return MARKERS.some((marker) => marker(env));
 }
 //#endregion
 //#region ../agent-cli/dist/errno.js
 const PERMISSION_DENIED = "PERMISSION_DENIED";
 const DISK_FULL = "DISK_FULL";
 const NOT_FOUND = "NOT_FOUND";
-function permissionHint({ path, callerLine, env }) {
-	return isAgent(env) ? `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or to allow ${path} in the sandbox's write list` : `check the permissions of ${path} and its folder`;
+const ALREADY_EXISTS = "ALREADY_EXISTS";
+const NOT_A_FILE = "NOT_A_FILE";
+function permissionHint({ path, access, callerLine, env, platform }) {
+	if (platform === "win32") return `a program may hold ${path} open: close it, then run the same command again`;
+	if (!isAgent(env)) return `check the permissions of ${path} and its folder`;
+	return `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`;
+}
+function fileErrorOf(scope) {
+	return (error, at) => classifyErrno(error, {
+		...at,
+		...scope
+	});
 }
-/** The error a file system failure on `path` stands for; any other error comes back unchanged. */
 function classifyErrno(error, context) {
 	const { path } = context;
 	switch (errnoOf(error)) {
 		case "EACCES":
-		case "EPERM": return new CliError({
+		case "EPERM":
+		case "EROFS":
+		case "EBUSY": return new CliError({
 			code: PERMISSION_DENIED,
 			message: `permission denied: ${path}`,
 			hint: permissionHint(context)
 		}, { cause: error });
-		case "ENOSPC": return new CliError({
+		case "ENOSPC":
+		case "EDQUOT": return new CliError({
 			code: DISK_FULL,
 			message: `no space left on the disk holding ${path}`,
 			hint: "free space on that disk, then run the same command again"
 		}, { cause: error });
-		case "ENOENT": return new CliError({
+		case "ENOENT":
+		case "ENOTDIR":
+		case "ENAMETOOLONG": return new CliError({
 			code: NOT_FOUND,
 			message: `not found: ${path}`,
 			hint: `check that ${path} and its folder exist`
 		}, { cause: error });
+		case "EEXIST": return new CliError({
+			code: ALREADY_EXISTS,
+			message: `already exists: ${path}`,
+			hint: `pass another path, or remove ${path}`
+		}, { cause: error });
+		case "EISDIR": return new CliError({
+			code: NOT_A_FILE,
+			message: `not a file: ${path} is a folder`,
+			hint: `pass the path of a file, not of the folder ${path}`
+		}, { cause: error });
 		default: return error;
 	}
 }
@@ -6480,7 +6961,7 @@ var RunControl = class {
 		else outer?.addEventListener("abort", this.#onOuterAbort, { once: true });
 		if (runDeadline !== void 0) {
 			const { ms, hint } = runDeadline;
-			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, hint)));
+			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, hint())));
 		}
 	}
 	deadline(ms) {
@@ -6512,7 +6993,7 @@ var RunControl = class {
 			return value;
 		} finally {
 			await this.#stepsDone();
-			this.#dispose();
+			this.close();
 		}
 	}
 	/**
@@ -6541,13 +7022,192 @@ var RunControl = class {
 	async #stepsDone() {
 		while (this.#steps.size > 0) await Promise.all(this.#steps.keys());
 	}
-	#dispose() {
+	/** Stops the run's timers and its hold on the caller's signal, for a run that never settles. */
+	close() {
 		this.#graceCancel.abort();
 		this.#disposed.abort();
 		this.#outer?.removeEventListener("abort", this.#onOuterAbort);
 	}
 };
 //#endregion
+//#region ../agent-cli/dist/operator.js
+const NEEDS_OPERATOR = "NEEDS_OPERATOR";
+/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
+function checkOperator({ operator, commandLine }, env, callerLine) {
+	if (!operator || !isAgent(env)) return;
+	throw new CliError({
+		code: NEEDS_OPERATOR,
+		message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
+		hint: `ask the operator to type: ! ${callerLine}`
+	});
+}
+//#endregion
+//#region ../agent-cli/dist/files.js
+const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
+/** Where the Runtime writes `path` before moving it into place; a dead writer's is swept. */
+function tempPathOf(path) {
+	return join(dirname(path), `.${basename(path)}.agent-cli-${process.pid}.tmp`);
+}
+function isAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return errnoOf(error) === "EPERM";
+	}
+}
+async function sweep(folder) {
+	const dead = (await readdir(folder)).filter((name) => {
+		const pid = TEMP_FILE.exec(name)?.[1];
+		return pid !== void 0 && !isAlive(Number(pid));
+	});
+	await Promise.all(dead.map((name) => rm(join(folder, name), { force: true })));
+}
+/** The file a symlink at `path` points to, so a replacing write keeps the link. */
+async function targetOf$1(path) {
+	try {
+		return await realpath(path);
+	} catch (error) {
+		if (isMissingFile(error)) return path;
+		throw error;
+	}
+}
+async function writeWithMode(path, data, mode) {
+	if (mode === void 0) {
+		await writeFile(path, data);
+		return;
+	}
+	await writeFile(path, data, { mode });
+	await chmod(path, mode);
+}
+/** What `link` answers on a file system without hard links, such as exFAT. */
+const NO_HARD_LINKS = /* @__PURE__ */ new Set([
+	"EPERM",
+	"ENOTSUP",
+	"EXDEV"
+]);
+/** A link fails atomically when `path` is taken, so no reader ever sees half a file there. */
+async function linkNew(temp, path, data, mode) {
+	try {
+		await link(temp, path);
+	} catch (error) {
+		if (!NO_HARD_LINKS.has(errnoOf(error))) throw error;
+		await createNew(path, data, mode);
+	}
+}
+/** A file this call created and could not finish is removed, so a rerun does not find half of it. */
+async function createNew(path, data, mode) {
+	const handle = await open(path, "wx", mode);
+	try {
+		await handle.writeFile(data);
+		if (mode !== void 0) await handle.chmod(mode);
+	} catch (error) {
+		await handle.close();
+		await rm(path, { force: true });
+		throw error;
+	}
+	await handle.close();
+}
+const RENAME_ATTEMPTS = 10;
+const RENAME_BACKOFF_MS = 10;
+const HELD_BY_ANOTHER_PROGRAM = /* @__PURE__ */ new Set(["EPERM", "EBUSY"]);
+async function renameRetrying(from, to) {
+	for (let attempt = 1;; attempt++) try {
+		await rename(from, to);
+		return;
+	} catch (error) {
+		if (!(process.platform === "win32" && HELD_BY_ANOTHER_PROGRAM.has(errnoOf(error))) || attempt === RENAME_ATTEMPTS) throw error;
+		await setTimeout$1(attempt * RENAME_BACKOFF_MS);
+	}
+}
+/** Real files for one run: the first write to each folder sweeps the temp files of dead writers. */
+function realFiles() {
+	const swept = /* @__PURE__ */ new Set();
+	return {
+		exists: async (path) => {
+			try {
+				await access(path);
+				return true;
+			} catch (error) {
+				if (isNothingThere(error)) return false;
+				throw error;
+			}
+		},
+		write: async (path, data, options = {}) => {
+			await mkdir(dirname(path), { recursive: true });
+			const target = options.exclusive === true ? path : await targetOf$1(path);
+			const folder = dirname(target);
+			if (!swept.has(folder)) {
+				await sweep(folder);
+				swept.add(folder);
+			}
+			const temp = tempPathOf(target);
+			try {
+				await writeWithMode(temp, data, options.mode);
+				if (options.exclusive === true) {
+					await linkNew(temp, target, data, options.mode);
+					await rm(temp);
+				} else await renameRetrying(temp, target);
+			} catch (error) {
+				await rm(temp, { force: true });
+				throw error;
+			}
+		},
+		read: (path) => readFile(path),
+		list: (folder) => readdir(folder),
+		remove: (path) => rm(path, {
+			recursive: true,
+			force: true
+		}),
+		mkdir: async (path, options) => {
+			if (options?.exclusive !== true) {
+				await mkdir(path, { recursive: true });
+				return;
+			}
+			await mkdir(dirname(path), { recursive: true });
+			await mkdir(path);
+		},
+		stat: async (path) => {
+			try {
+				const { size, dev, ino } = await stat(path, { bigint: true });
+				return {
+					size: Number(size),
+					id: `${dev}:${ino}`
+				};
+			} catch (error) {
+				if (isNothingThere(error)) return void 0;
+				throw error;
+			}
+		}
+	};
+}
+/**
+* `files` resolving paths against `cwd`, its failures classified by errno; `list` drops the
+* Runtime's temp files and sorts.
+*/
+function classifiedFiles(files, { cwd, fileError }) {
+	async function at(access, path, work) {
+		const target = resolve(cwd, path);
+		try {
+			return await work(target);
+		} catch (error) {
+			throw fileError(error, {
+				path: target,
+				access
+			});
+		}
+	}
+	return {
+		exists: (path) => at("read", path, (target) => files.exists(target)),
+		write: (path, data, options) => at("write", path, (target) => files.write(target, data, options)),
+		read: (path) => at("read", path, (target) => files.read(target)),
+		list: (folder) => at("read", folder, async (target) => (await files.list(target)).filter((name) => !TEMP_FILE.test(name)).sort()),
+		remove: (path) => at("write", path, (target) => files.remove(target)),
+		mkdir: (path, options) => at("write", path, (target) => files.mkdir(target, options)),
+		stat: (path) => at("read", path, (target) => files.stat(target))
+	};
+}
+//#endregion
 //#region ../agent-cli/dist/outputs.js
 const OUTPUT_EXISTS = "OUTPUT_EXISTS";
 /** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
@@ -6560,9 +7220,62 @@ async function checkOutputs({ invocation, commandLine, force, files }, outputs)
 	throw new CliError({
 		code: OUTPUT_EXISTS,
 		message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
-		hint: `to replace ${them}, run \`${commandLineWith(invocation, FORCE_FLAG.flag)}\``
+		hint: `to replace ${them}, run \`${commandLineOf(invocation, { add: [FORCE_FLAG.flag] })}\``
 	});
 }
+/** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
+function outputsGuard(files, cwd) {
+	const unwritten = /* @__PURE__ */ new Set();
+	let forceLine = "";
+	const exclusiveWrite = async (path, data, options) => {
+		const target = resolve(cwd, path);
+		unwritten.delete(target);
+		try {
+			await files.write(path, data, {
+				...options,
+				exclusive: true
+			});
+		} catch (error) {
+			unwritten.add(target);
+			if (!(error instanceof CliError) || error.code !== "ALREADY_EXISTS") throw error;
+			throw new CliError({
+				code: ALREADY_EXISTS,
+				message: error.message,
+				hint: `to replace it, run \`${forceLine}\``
+			}, { cause: error });
+		}
+	};
+	return {
+		files: {
+			...files,
+			write: (path, data, options) => unwritten.has(resolve(cwd, path)) ? exclusiveWrite(path, data, options) : files.write(path, data, options)
+		},
+		guard: (outputs, line) => {
+			forceLine = line;
+			for (const path of outputs) unwritten.add(resolve(cwd, path));
+		}
+	};
+}
+/**
+* Creates each output folder and a temp file in it, so a sandbox denial fails before `apply`
+* spends anything. The temp file's name is the Runtime's, so a crashed run's leftover is swept.
+*/
+async function probeOutputs({ files, cwd, fileError }, outputs) {
+	const folders = new Set(outputs.map((path) => dirname(resolve(cwd, path))));
+	await Promise.all([...folders].map(async (folder) => {
+		const probe = tempPathOf(join(folder, "outputs-probe"));
+		try {
+			await files.mkdir(folder);
+			await files.write(probe, "");
+			await files.remove(probe);
+		} catch (error) {
+			throw fileError(error, {
+				path: folder,
+				access: "write"
+			});
+		}
+	}));
+}
 //#endregion
 //#region ../agent-cli/dist/project.js
 const PROJECT_INVALID = "PROJECT_INVALID";
@@ -6610,145 +7323,6 @@ function projectOf(projectFile, cwd) {
 	return projectFrom(projectFile, resolve(cwd));
 }
 //#endregion
-//#region ../agent-cli/dist/tools.js
-const TOOL_MISSING = "TOOL_MISSING";
-const WINDOWS_EXTENSIONS = ".COM;.EXE;.BAT;.CMD";
-const NOT_EXECUTABLE = /* @__PURE__ */ new Set([
-	"ENOENT",
-	"ENOTDIR",
-	"EACCES"
-]);
-function pathOf(env) {
-	return env[Object.keys(env).find((name) => name.toUpperCase() === "PATH") ?? "PATH"] ?? "";
-}
-function extensionsOf(env) {
-	return process.platform === "win32" ? (env.PATHEXT ?? WINDOWS_EXTENSIONS).split(";") : [""];
-}
-async function isExecutable(file) {
-	try {
-		await access(file, constants$1.X_OK);
-		return true;
-	} catch (error) {
-		if (NOT_EXECUTABLE.has(errnoOf(error) ?? "")) return false;
-		throw error;
-	}
-}
-/** Where `name` is found on `PATH` from `env`, or undefined. */
-async function findTool(name, env) {
-	const candidates = pathOf(env).split(delimiter).filter((folder) => folder !== "").flatMap((folder) => extensionsOf(env).map((extension) => join(folder, `${name}${extension}`)));
-	for (const file of candidates) if (await isExecutable(file)) return file;
-}
-/** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
-async function checkTools(tools, env) {
-	const found = await Promise.all(tools.map((tool) => findTool(tool.name, env)));
-	const missing = tools.filter((_tool, index) => found[index] === void 0);
-	if (missing.length === 0) return;
-	const names = missing.map(({ name }) => name).join(", ");
-	throw new CliError({
-		code: TOOL_MISSING,
-		message: `${missing.length === 1 ? "a tool it runs is" : "tools it runs are"} not on PATH: ${names}`,
-		hint: `install ${missing.length === 1 ? "it" : "them"}, then run the same command again: ${missing.map(({ install }) => install).join("; ")}`
-	});
-}
-function toolsIn(node) {
-	return isCommand(node) ? [...node.tools ?? []] : Object.values(node).flatMap(toolsIn);
-}
-/** One `doctor` row per distinct tool the Commands declare, with its install command as the fix. */
-function toolRows(commands) {
-	return [...new Map(toolsIn(commands).map((tool) => [tool.name, tool])).values()].map(({ name, install }) => ({
-		name,
-		run: async (ctx) => {
-			const file = await findTool(name, ctx.env);
-			return file === void 0 ? {
-				state: "problem",
-				message: `${name} is not on PATH`,
-				fix: install
-			} : {
-				state: "ok",
-				message: `found at ${file}`
-			};
-		}
-	}));
-}
-//#endregion
-//#region ../agent-cli/dist/spawn.js
-const TOOL_FAILED = "TOOL_FAILED";
-const STDERR_TAIL_LINES = 20;
-const SIGNAL_EXIT_BASE = 128;
-const realSpawn = (command, args, { cwd, env, signal }) => new Promise((resolve, reject) => {
-	signal.throwIfAborted();
-	const child = spawn(command, args, {
-		cwd,
-		env,
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		]
-	});
-	const stdout = [];
-	const stderr = [];
-	child.stdout.on("data", (chunk) => stdout.push(chunk));
-	child.stderr.on("data", (chunk) => stderr.push(chunk));
-	const kill = () => {
-		child.kill();
-	};
-	signal.addEventListener("abort", kill, { once: true });
-	child.on("error", (error) => {
-		signal.removeEventListener("abort", kill);
-		reject(error);
-	});
-	child.on("close", (code, killedBy) => {
-		signal.removeEventListener("abort", kill);
-		if (signal.aborted) {
-			reject(signal.reason);
-			return;
-		}
-		resolve({
-			stdout: Buffer.concat(stdout).toString(),
-			stderr: Buffer.concat(stderr).toString(),
-			exitCode: code ?? SIGNAL_EXIT_BASE + (killedBy === null ? 0 : constants.signals[killedBy])
-		});
-	});
-});
-function failedError(command, { exitCode, stderr }) {
-	const tail = lastLines(stderr, STDERR_TAIL_LINES);
-	return new CliError({
-		code: TOOL_FAILED,
-		message: tail === "" ? `${command} exited with ${exitCode} and wrote nothing to stderr` : `${command} exited with ${exitCode}; its stderr ends:\n${tail}`,
-		hint: `the output of ${command} above says why it failed`
-	});
-}
-function missingError(command, cause) {
-	return new CliError({
-		code: TOOL_MISSING,
-		message: `${command} could not be started: it is not on PATH`,
-		hint: `install ${command}, then run the same command again`
-	}, { cause });
-}
-/** `ctx.spawn`: `spawn` bound to the run, its start failures classified by errno. */
-function contextSpawn(run, defaults, callerLine) {
-	return async (command, args = [], options = {}) => {
-		let result;
-		try {
-			result = await run(command, args, {
-				cwd: options.cwd ?? defaults.cwd,
-				env: options.env ?? defaults.env,
-				signal: defaults.signal
-			});
-		} catch (error) {
-			if (isMissingFile(error)) throw missingError(command, error);
-			throw classifyErrno(error, {
-				path: command,
-				callerLine,
-				env: defaults.env
-			});
-		}
-		if (options.check === true && result.exitCode !== 0) throw failedError(command, result);
-		return result;
-	};
-}
-//#endregion
 //#region ../agent-cli/dist/exit-classes.js
 const SIGNAL_EXIT_CODES = {
 	SIGINT: 130,
@@ -6771,6 +7345,7 @@ function runtimeCodes() {
 		[CONFIRMATION_REQUIRED]: "caller",
 		[CONFIRMATION_MISMATCH]: "caller",
 		[NOT_CONFIRMED]: "operator",
+		[NEEDS_OPERATOR]: "operator",
 		[OUTPUT_EXISTS]: "caller",
 		[INTERRUPTED]: "interrupted",
 		[DEADLINE_EXCEEDED]: "wait",
@@ -6778,6 +7353,8 @@ function runtimeCodes() {
 		[PERMISSION_DENIED]: "operator",
 		[DISK_FULL]: "operator",
 		[NOT_FOUND]: "caller",
+		[ALREADY_EXISTS]: "caller",
+		[NOT_A_FILE]: "caller",
 		[TOOL_FAILED]: "operator",
 		[TOOL_MISSING]: "operator",
 		[PROJECT_INVALID]: "operator",
@@ -6841,6 +7418,53 @@ function exitCodeOf(error, errors, stop) {
 	return exitClass === "interrupted" ? SIGNAL_EXIT_CODES[stopSignalOf(stop?.reason)] : EXIT_CODES[exitClass];
 }
 //#endregion
+//#region ../agent-cli/dist/command-spec.js
+/** The group's Commands and groups that help and suggestions may name: hidden Commands left out. */
+function visibleCommands({ commands }) {
+	return Object.fromEntries(Object.entries(commands).filter(([, node]) => node.kind === "group" || !node.hidden));
+}
+function declaredOf(command) {
+	if (!hasPlan(command)) return {
+		outputs: false,
+		force: void 0,
+		cost: false
+	};
+	return {
+		outputs: command.outputs !== void 0,
+		force: command.force,
+		cost: command.cost !== void 0
+	};
+}
+function commandSpec(commandLine, command) {
+	const list = command.rows === void 0 ? void 0 : listSpec(command.rows);
+	return {
+		kind: "command",
+		commandLine,
+		command,
+		description: command.description,
+		help: command.help,
+		hidden: command.hidden === true,
+		operator: command.operator === true,
+		effect: command.effect,
+		examples: command.examples,
+		args: argFields(command.args),
+		options: optionFields(command.options),
+		standardFlags: standardFlagsFor(command.effect, declaredOf(command), list),
+		list,
+		output: list?.output ?? command.output
+	};
+}
+function groupSpec(commandLine, commands) {
+	return {
+		kind: "group",
+		commandLine,
+		commands: Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node)]))
+	};
+}
+function specOf(commandLine, node) {
+	return isCommand(node) ? commandSpec(commandLine, node) : groupSpec(commandLine, node);
+}
+//#endregion
 //#region ../agent-cli/dist/help.js
 function table(rows) {
 	const width = Math.max(...rows.map(([left]) => left.length));
@@ -6854,10 +7478,11 @@ function section(title, rows, style) {
 	];
 }
 function summaryOf(node) {
-	return node.kind === "command" ? node.description : `group: ${Object.keys(node.commands).join(", ")}`;
+	if (node.kind === "group") return `group: ${Object.keys(visibleCommands(node)).join(", ")}`;
+	return node.operator ? `${node.description} (operator only)` : node.description;
 }
-function commandRows({ commands }) {
-	return Object.entries(commands).map(([key, node]) => [key, summaryOf(node)]);
+function commandRows(group) {
+	return Object.entries(visibleCommands(group)).map(([key, node]) => [key, summaryOf(node)]);
 }
 function lines(...parts) {
 	return `${parts.join("\n")}\n`;
@@ -6885,11 +7510,11 @@ function exitCodeRows(cli) {
 }
 function firstExample(node) {
 	if (node.kind === "command") return node.examples.slice(0, 1);
-	return Object.values(node.commands).flatMap(firstExample).slice(0, 1);
+	return Object.values(visibleCommands(node)).flatMap(firstExample).slice(0, 1);
 }
 function rootExamples(root) {
 	if (root.kind === "command") return [...root.examples];
-	const { doctor, ...others } = root.commands;
+	const { doctor, ...others } = visibleCommands(root);
 	return [...Object.values(others), ...doctor === void 0 ? [] : [doctor]].flatMap(firstExample);
 }
 function examplesSection(examples, style) {
@@ -6908,6 +7533,7 @@ const EFFECT_NOTES = {
 	destructive: "changes something hard to undo; show the Plan with --dry-run, run with --confirm",
 	serve: "changes nothing; prints its data at once, then runs until Ctrl-C, which exits 0"
 };
+const OPERATOR_NOTE = "only a person at a terminal runs it; a Coding agent asks the operator to type it after `!`";
 function choicesOf(field) {
 	return field.choices === void 0 ? [] : [`one of: ${field.choices.join(", ")}`];
 }
@@ -6937,8 +7563,10 @@ function commandLines(spec, style, { examples }) {
 		...examples ? examplesSection(spec.examples, style) : [],
 		...section("Arguments", spec.args.map(argRow), style),
 		...section("Options", spec.options.map(optionRow), style),
+		...spec.help === void 0 ? [] : ["", spec.help],
 		"",
 		`${style.bold("Effect:")} ${spec.effect} (${EFFECT_NOTES[spec.effect]})`,
+		...spec.operator ? [`${style.bold("Operator Command:")} ${OPERATOR_NOTE}`] : [],
 		...section("Standard flags", spec.standardFlags.map(flagRow), style)
 	];
 }
@@ -6960,7 +7588,9 @@ function commandData(spec) {
 	return {
 		name: spec.commandLine,
 		description: spec.description,
+		help: spec.help ?? null,
 		effect: spec.effect,
+		operator: spec.operator,
 		examples: spec.examples,
 		args: inputSchema(spec.command.args ?? object({})),
 		options: optionsSchema(spec.options),
@@ -6978,7 +7608,7 @@ function nodeData(node) {
 function groupData(group) {
 	return {
 		name: group.commandLine,
-		commands: Object.values(group.commands).map(nodeData)
+		commands: Object.values(visibleCommands(group)).map(nodeData)
 	};
 }
 function printed$1(data) {
@@ -7020,6 +7650,10 @@ function printed(value, render, { json, invocation, style, fields }) {
 		items: rows
 	})}\n` : `${renderRows(rows, fields)}${pageFooter(page)}`;
 }
+/** A progress message as stderr carries it: one JSON object per line under `--json` (ADR 0006). */
+function progressLine(message, json) {
+	return json ? `${JSON.stringify({ progress: message })}\n` : `${message}\n`;
+}
 function errorText(error, format) {
 	const text = formatRuntimeError(error, {
 		...format,
@@ -7106,12 +7740,51 @@ function versionResult(cli, packageRoot) {
 	};
 }
 //#endregion
+//#region ../agent-cli/dist/skill-source.js
+/** The branch a release moves to the released commit, which holds the skill of that version. */
+const RELEASE_BRANCH = "release";
+const GITHUB_SHORTHAND = /^[\w.-]+\/[\w.-]+$/;
+const GIT_URL_PROTOCOLS = /* @__PURE__ */ new Set([
+	"https:",
+	"http:",
+	"ssh:",
+	"git:"
+]);
+const SCP_STYLE = /^[\w.-]+@[\w.-]+:[\w./-]+$/;
+const manifestSchema = object({ repository: union([string(), object({ url: string() })]).optional() });
+function sourceFromRepository(repository) {
+	if (GITHUB_SHORTHAND.test(repository)) return repository;
+	const url = repository.replace(/^git\+/, "");
+	if (!(URL.canParse(url) && GIT_URL_PROTOCOLS.has(new URL(url).protocol)) && !SCP_STYLE.test(url)) return void 0;
+	return `${url.endsWith(".git") ? url : `${url}.git`}#${RELEASE_BRANCH}`;
+}
+async function repositoryAt(packageRoot) {
+	let manifest;
+	try {
+		manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+	} catch {
+		return;
+	}
+	const parsed = manifestSchema.safeParse(manifest);
+	const repository = parsed.success ? parsed.data.repository : void 0;
+	return typeof repository === "object" ? repository.url : repository;
+}
+/** What `npx skills add` installs the CLI's skill from: the declared source, else the package's repository. */
+async function skillSource(declared, packageRoot) {
+	if (declared !== void 0) return declared.source;
+	const repository = await repositoryAt(packageRoot);
+	return repository === void 0 ? void 0 : sourceFromRepository(repository);
+}
+//#endregion
 //#region ../agent-cli/dist/skills.js
 /** Where the skills CLI (`npx skills add`) puts a skill, under a project and under home. */
 const SKILL_DIRS = [[".claude", "skills"], [".agents", "skills"]];
 function skillUpdateCommand(cliName) {
 	return `npx -y skills update ${cliName}`;
 }
+function skillAddCommand(source, cliName) {
+	return `npx -y skills add ${source} --skill ${cliName} -g`;
+}
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
 const METADATA_VERSION = /^metadata:[ \t]*\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$/m;
 /** The version a SKILL.md's frontmatter `metadata.version` states. */
@@ -7216,14 +7889,15 @@ function projectRow(projectFile) {
 		}
 	};
 }
-function installRow(cli, bin) {
+function installRow(cli, { bin, node }) {
 	return {
 		name: "install",
+		advisory: true,
 		run: async (ctx) => {
 			const { install } = cli;
 			if (install === void 0) return ok(`${cli.name} declares no install, so it has no \`update\``);
 			try {
-				return ok(`a global npm install under ${(await globalInstallOf(bin, npmContext(cli, install, ctx))).prefix}`);
+				return ok(`a global npm install under ${(await globalInstallOf(bin, npmContext(cli, install, ctx, node))).prefix}`);
 			} catch (error) {
 				if (error instanceof CliError && error.code === "NOT_GLOBAL_INSTALL") return {
 					state: "problem",
@@ -7235,13 +7909,14 @@ function installRow(cli, bin) {
 		}
 	};
 }
-function registryRow(cli) {
+function registryRow(cli, node) {
 	return {
 		name: "registry",
+		advisory: true,
 		run: async (ctx) => {
 			const { install } = cli;
 			if (install === void 0) return ok(`${cli.name} declares no registry to compare this build with`);
-			const latest = await latestVersion(npmContext(cli, install, ctx));
+			const latest = await latestVersion(npmContext(cli, install, ctx, node));
 			const standing = standingOf(cli.version, latest);
 			const head = `${install.registry} has ${latest} as latest: this build`;
 			if (standing === "behind") return {
@@ -7272,7 +7947,15 @@ function skillRow(cli) {
 		name: "skill",
 		run: async (ctx) => {
 			const copies = await skillCopies(cli.name, cli.version, ctx.cwd, ctx.env);
-			if (copies.length === 0) return ok(`no copy of the ${cli.name} skill is installed`);
+			if (copies.length === 0) {
+				const message = `no copy of the ${cli.name} skill is installed`;
+				const source = await skillSource(cli.skill, ctx.packageRoot);
+				return source === void 0 ? ok(message) : {
+					state: "ok",
+					message,
+					fix: skillAddCommand(source, cli.name)
+				};
+			}
 			const fix = skillFix(cli, copies);
 			const message = copies.map(describeCopy).join("; ");
 			return fix === void 0 ? ok(message) : {
@@ -7284,15 +7967,15 @@ function skillRow(cli) {
 	};
 }
 /** Every row `doctor` reports, in order: the fixed rows around the CLI's own and its tools'. */
-function doctorChecks(cli, bin) {
+function doctorChecks(cli, launch) {
 	return [
 		buildRow(cli),
 		nodeRow(cli),
 		...cli.project === void 0 ? [] : [projectRow(cli.project)],
 		...cli.doctor ?? [],
-		...toolRows(cli.commands),
-		installRow(cli, bin),
-		registryRow(cli),
+		...toolRows(cli.tools ?? [], cli.commands),
+		installRow(cli, launch),
+		registryRow(cli, launch.node),
 		skillRow(cli)
 	];
 }
@@ -7305,9 +7988,14 @@ const MIN_LABEL_WIDTH = 8;
 const reportSchema = object({
 	rows: array(object({
 		check: string(),
-		state: _enum(["ok", "problem"]),
+		state: _enum([
+			"ok",
+			"problem",
+			"skipped"
+		]),
 		message: string(),
-		fix: string().optional()
+		fix: string().optional(),
+		code: string().optional()
 	})),
 	next: array(string())
 });
@@ -7318,23 +8006,25 @@ function problemOf(check, error, { signal, deadline, ms }) {
 	};
 	if (error instanceof CliError) return {
 		state: "problem",
-		message: `${error.message}; ${error.hint}`
+		message: `${error.message}; ${error.hint}`,
+		code: error.code
 	};
 	return {
 		state: "problem",
 		message: `the ${check.name} row hit a bug: ${messageOf(error)}`
 	};
 }
+function withSignal(ctx, signal) {
+	return Object.create(ctx, { signal: { value: signal } });
+}
 async function rowOf(check, ctx) {
 	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
 	const signal = ctx.deadline(ms);
 	let finding;
 	try {
-		finding = await Promise.race([Promise.resolve().then(() => check.run({
-			...ctx,
-			signal
-		})), untilAborted(signal)]);
+		finding = await Promise.race([Promise.resolve().then(() => check.run(withSignal(ctx, signal))), untilAborted(signal)]);
 	} catch (error) {
+		if (ctx.signal.aborted) return void 0;
 		finding = problemOf(check, error, {
 			signal: ctx.signal,
 			deadline: signal,
@@ -7360,15 +8050,16 @@ function render({ rows, next }, style) {
 		return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
 	}), ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
 }
-function failure(cliName, problems, report) {
-	return new CliError({
-		code: DOCTOR_PROBLEMS,
-		message: `${cliName} doctor found ${problems.length === 1 ? "a problem" : `${problems.length} problems`}: ${problems.join(", ")}`,
-		hint: report.next.length === 0 ? "each problem row says what is wrong" : "run the commands under next, then run doctor again"
-	});
+function failure(cliName, problems) {
+	const errors = problems.map(({ check, message, fix, code }) => new CliError({
+		code: code ?? "DOCTOR_PROBLEMS",
+		message: `${cliName} doctor found a problem in ${check}: ${message}`,
+		hint: fix === void 0 ? "the row says what is wrong" : `run ${fix}, then run doctor again`
+	}));
+	return new AggregateError(errors);
 }
 /** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
-function doctorCommand(cli, bin) {
+function doctorCommand(cli, launch) {
 	return defineCommand$1({
 		name: "doctor",
 		description: "check the setup and say what fixes each problem",
@@ -7382,17 +8073,20 @@ function doctorCommand(cli, bin) {
 		effect: "read",
 		output: reportSchema,
 		run: async (_input, ctx) => {
-			const checked = await Promise.all(doctorChecks(cli, bin).map((check) => rowOf(check, ctx)));
-			ctx.signal.throwIfAborted();
+			const checked = (await Promise.all(doctorChecks(cli, launch).map((check) => rowOf(check, ctx)))).filter((row) => row !== void 0);
 			const rows = checked.map(({ row }) => row);
 			const report = {
 				rows,
 				next: nextOf(rows)
 			};
-			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row.check);
+			if (ctx.signal.aborted) {
+				ctx.deliver(report);
+				ctx.signal.throwIfAborted();
+			}
+			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
 			if (problems.length > 0) {
 				ctx.deliver(report);
-				throw failure(cli.name, problems, report);
+				throw failure(cli.name, problems);
 			}
 			return report;
 		},
@@ -7471,7 +8165,7 @@ function interruptedAfterInstall(plan) {
 	});
 }
 /** The built-in `update`, for a CLI installed globally with npm. */
-function updateCommand(cli, install, bin) {
+function updateCommand(cli, install, { bin, node }) {
 	return defineCommand$1({
 		name: "update",
 		description: "install the latest version of this CLI from its registry",
@@ -7485,7 +8179,7 @@ function updateCommand(cli, install, bin) {
 		effect: "write",
 		output: updateSchema,
 		plan: async (_input, ctx) => {
-			const npm = npmContext(cli, install, ctx);
+			const npm = npmContext(cli, install, ctx, node);
 			const copy = await globalInstallOf(bin, npm);
 			return {
 				package: install.package,
@@ -7506,7 +8200,7 @@ function updateCommand(cli, install, bin) {
 			};
 			ctx.signal.throwIfAborted();
 			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
-			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, npmContext(cli, install, ctx)));
+			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, npmContext(cli, install, ctx, node)));
 			const update = {
 				from,
 				latest,
@@ -7530,10 +8224,10 @@ function updateCommand(cli, install, bin) {
 //#endregion
 //#region ../agent-cli/dist/built-ins.js
 /** The Commands the Runtime adds to a multi-Command CLI: `update` only when it declares an install. */
-function builtInCommands(cli, bin) {
+function builtInCommands(cli, launch) {
 	return {
-		doctor: doctorCommand(cli, bin),
-		...cli.install === void 0 ? {} : { update: updateCommand(cli, cli.install, bin) }
+		doctor: doctorCommand(cli, launch),
+		...cli.install === void 0 ? {} : { update: updateCommand(cli, cli.install, launch) }
 	};
 }
 //#endregion
@@ -7546,7 +8240,10 @@ function defineCli$1(cli) {
 	checkOwnCodes(cli);
 	if (cli.commands === void 0) return cli;
 	const { commands } = cli;
-	const taken = Object.keys(builtInCommands(cli, void 0)).filter((name) => commands[name] !== void 0);
+	const taken = Object.keys(builtInCommands(cli, {
+		bin: void 0,
+		node: void 0
+	})).filter((name) => commands[name] !== void 0);
 	if (taken.length > 0) throw new Error(`${cli.name} defines ${taken.join(", ")}, a built-in Command it cannot replace`);
 	return cli;
 }
@@ -7574,41 +8271,6 @@ function cliError(_table, code, init, options) {
 	}, options);
 }
 //#endregion
-//#region ../agent-cli/dist/command-spec.js
-function declaredOf(command) {
-	const planned = command.effect === "write" || command.effect === "destructive";
-	return {
-		outputs: planned && command.outputs !== void 0,
-		cost: planned && command.cost !== void 0
-	};
-}
-function commandSpec(commandLine, command) {
-	const list = command.rows === void 0 ? void 0 : listSpec(command.rows);
-	return {
-		kind: "command",
-		commandLine,
-		command,
-		description: command.description,
-		effect: command.effect,
-		examples: command.examples,
-		args: argFields(command.args),
-		options: optionFields(command.options),
-		standardFlags: standardFlagsFor(command.effect, declaredOf(command), list),
-		list,
-		output: list?.output ?? command.output
-	};
-}
-function groupSpec(commandLine, commands) {
-	return {
-		kind: "group",
-		commandLine,
-		commands: Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node)]))
-	};
-}
-function specOf(commandLine, node) {
-	return isCommand(node) ? commandSpec(commandLine, node) : groupSpec(commandLine, node);
-}
-//#endregion
 //#region ../agent-cli/dist/execute.js
 function outcomeOf(value, render) {
 	return {
@@ -7641,7 +8303,7 @@ function dryRunOutcome(command, plan) {
 		].join("\n")
 	};
 }
-async function execute(command, input, ctx, { dryRun, confirm, yes, force, page, invocation, commandLine, started }) {
+async function execute(command, input, ctx, { dryRun, confirm, yes, page, invocation, commandLine, started, files, guardOutputs }) {
 	await checkTools(command.tools ?? [], ctx.env);
 	if (command.rows !== void 0) return outcomeOf(await command.run({
 		...input,
@@ -7654,12 +8316,13 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, force, page,
 	}
 	const plan = await command.plan(input, ctx);
 	if (dryRun) return dryRunOutcome(command, plan);
+	const outputs = command.outputs?.(plan);
 	await checkOutputs({
 		invocation,
 		commandLine,
-		force,
+		force: ctx.force,
 		files: ctx.files
-	}, command.outputs?.(plan));
+	}, outputs);
 	checkCost({
 		invocation,
 		commandLine,
@@ -7670,58 +8333,15 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, force, page,
 		commandLine,
 		given: confirm
 	}, command.confirm(plan));
-	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
-}
-//#endregion
-//#region ../agent-cli/dist/files.js
-const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
-function tempPathOf(path) {
-	return join(dirname(path), `.${basename(path)}.agent-cli-${process.pid}.tmp`);
-}
-function isAlive(pid) {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return errnoOf(error) === "EPERM";
+	if (outputs !== void 0) {
+		await probeOutputs({
+			files,
+			cwd: ctx.cwd,
+			fileError: ctx.fileError
+		}, outputs);
+		if (!ctx.force) guardOutputs(outputs, ctx.commandLine({ add: [FORCE_FLAG.flag] }));
 	}
-}
-async function sweep(folder) {
-	const dead = (await readdir(folder)).filter((name) => {
-		const pid = TEMP_FILE.exec(name)?.[1];
-		return pid !== void 0 && !isAlive(Number(pid));
-	});
-	await Promise.all(dead.map((name) => rm(join(folder, name), { force: true })));
-}
-/** Real files for one run: the first write to each folder sweeps the temp files of dead writers. */
-function realFiles() {
-	const swept = /* @__PURE__ */ new Set();
-	return {
-		exists: async (path) => {
-			try {
-				await access(path);
-				return true;
-			} catch (error) {
-				if (isMissingFile(error)) return false;
-				throw error;
-			}
-		},
-		write: async (path, data) => {
-			const folder = dirname(path);
-			if (!swept.has(folder)) {
-				await sweep(folder);
-				swept.add(folder);
-			}
-			const temp = tempPathOf(path);
-			try {
-				await writeFile(temp, data);
-				await rename(temp, path);
-			} catch (error) {
-				await rm(temp, { force: true });
-				throw error;
-			}
-		}
-	};
+	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
 }
 //#endregion
 //#region ../agent-cli/dist/package-root.js
@@ -7780,88 +8400,6 @@ function closestFlag(flag, flags) {
 	return closest.length === 1 ? closest[0] : void 0;
 }
 //#endregion
-//#region ../agent-cli/dist/tokenize.js
-const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
-function isOptionLike(word) {
-	return word !== void 0 && word.length > 1 && word[0] === "-" && !NEGATIVE_NUMBER.test(word);
-}
-function parseArgsOptions(known) {
-	return Object.fromEntries(known.map(({ flag, takes }) => [flag.slice(2), { type: takes === "value" ? "string" : "boolean" }]));
-}
-function flagItem(token, { flag, takes }, words) {
-	if (takes !== "optional value" || token.inlineValue === true) return {
-		kind: "flag",
-		flag,
-		value: token.value ?? true
-	};
-	const took = token.index + 1;
-	const next = words[took];
-	return next === void 0 || isOptionLike(next) ? {
-		kind: "flag",
-		flag,
-		value: true
-	} : {
-		kind: "flag",
-		flag,
-		value: next,
-		took
-	};
-}
-function itemOf(token, words, byFlag) {
-	const word = words[token.index] ?? "";
-	if (token.kind === "option-terminator") return { kind: "end" };
-	if (token.kind === "positional" || NEGATIVE_NUMBER.test(word)) return {
-		kind: "operand",
-		value: word
-	};
-	const flag = byFlag.get(token.rawName);
-	return flag === void 0 || flag.takes === "nothing" && token.inlineValue === true ? {
-		kind: "unknown option",
-		word
-	} : flagItem(token, flag, words);
-}
-/** Splits a Command's words into operands, unknown options and the values of known flags. */
-function tokenize(words, known) {
-	const byFlag = new Map(known.map((flag) => [flag.flag, flag]));
-	const { tokens } = parseArgs({
-		args: [...words],
-		options: parseArgsOptions(known),
-		strict: false,
-		allowPositionals: true,
-		tokens: true
-	});
-	const operands = [];
-	const unknownOptions = [];
-	const values = /* @__PURE__ */ new Map();
-	const done = /* @__PURE__ */ new Set();
-	let literal = false;
-	let afterUnknownOption = false;
-	for (const token of tokens) {
-		if (done.has(token.index)) continue;
-		done.add(token.index);
-		const item = itemOf(token, words, byFlag);
-		if (item.kind === "end") literal = true;
-		else if (item.kind === "operand") {
-			operands.push({
-				value: item.value,
-				afterUnknownOption: !literal && afterUnknownOption
-			});
-			afterUnknownOption = false;
-		} else if (item.kind === "unknown option") {
-			unknownOptions.push(item.word);
-			afterUnknownOption = true;
-		} else {
-			values.set(item.flag, item.value);
-			if (item.took !== void 0) done.add(item.took);
-		}
-	}
-	return {
-		operands,
-		unknownOptions,
-		values
-	};
-}
-//#endregion
 //#region ../agent-cli/dist/parse-input.js
 const NO_INPUT = object({});
 function knownFlags(spec) {
@@ -7889,28 +8427,46 @@ function unknownOptionsOf(words, candidates) {
 		};
 	});
 }
-function optionValue(field, raw) {
+function optionValue(field, all) {
+	if (field.variadic) return variadicValue(field, (all ?? []).filter((value) => value !== true));
+	const raw = all?.[all.length - 1];
 	return field.type === "boolean" && raw === true && field.label === `--no-${field.name}` ? false : raw;
 }
 function converted(field, raw) {
+	if (Array.isArray(raw)) return raw.map((element) => converted(field, element));
 	if (field.type !== "number" || typeof raw !== "string" || raw.trim() === "") return raw;
 	const number = Number(raw);
 	return Number.isNaN(number) ? raw : number;
 }
+function variadicValue(field, values) {
+	return values.length === 0 && !field.required ? void 0 : values;
+}
 function parse(schema, values) {
 	const input = Object.fromEntries([...values].filter(([, raw]) => raw !== void 0).map(([field, raw]) => [field.key, converted(field, raw)]));
 	return schema.safeParse(input);
 }
-function issueLines(result, values, howToPass, reported) {
+function issueLines(result, values, { howToPass, arrayIssueLine, reported = [], fromStdin }) {
 	if (result.success) return [];
 	return result.error.issues.flatMap((issue) => {
 		const field = [...values.keys()].find((candidate) => candidate.key === issue.path[0]);
 		if (field === void 0) return [`  ${issue.message}`];
 		if (reported.includes(field)) return [];
 		const raw = values.get(field);
-		return raw === void 0 ? [`  ${field.label}: required, ${howToPass(field)}`] : [`  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`];
+		if (raw === void 0) return [`  ${field.label}: required, ${howToPass(field)}`];
+		if (field === fromStdin) return [`  ${field.label} from stdin: ${issue.message}`];
+		return Array.isArray(raw) ? [arrayIssueLine(field, raw, issue)] : [`  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`];
 	});
 }
+function flagValuesIssueLine(field, raw, issue) {
+	const [, element] = issue.path;
+	if (typeof element === "number") return `  ${field.label} ${JSON.stringify(raw[element])}: ${issue.message}`;
+	return raw.length === 0 ? `  ${field.label}: ${issue.message}, pass ${field.usage}` : `  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`;
+}
+function operandsIssueLine(field, raw, issue, first) {
+	const [, element] = issue.path;
+	if (typeof element === "number") return `  ${field.label} ${JSON.stringify(raw[element])} (argument ${first + element}): ${issue.message}`;
+	return raw.length === 0 ? `  ${field.label}: ${issue.message}, pass them as arguments from ${first}` : `  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`;
+}
 function unknownLine({ flag, suggestion }) {
 	return `  unknown option '${flag}'${suggestion === void 0 ? "" : ` (did you mean ${suggestion}?)`}`;
 }
@@ -7927,15 +8483,36 @@ function invalidInput(commandLine, invocation, unknown, otherLines) {
 		hint: correctable ? `did you mean \`${commandLineRenaming(invocation, renames)}\`?` : `run \`${commandLine} --help\` to see the expected input`
 	});
 }
-function parseInput(spec, words, invocation) {
+async function stdinTextOf(spec, operands, read) {
+	const index = spec.args.findIndex((field) => field.stdin);
+	const field = spec.args[index];
+	if (field === void 0 || operands[index]?.value !== "-") return void 0;
+	return {
+		field,
+		text: await read(field)
+	};
+}
+async function parseInput(spec, words, invocation, readStdin) {
 	const { command, args: argFields, options: optionFields } = spec;
 	const pageFields = spec.list?.pageFields ?? [];
 	const known = knownFlags(spec);
-	const { operands, unknownOptions, values } = tokenize(words, known);
+	const { operands, unknownOptions, values, occurrences } = tokenize(words, known);
+	const stdin = await stdinTextOf(spec, operands, readStdin);
 	if (values.get(CONFIRM_FLAG.flag) === true) throw invalidInputError(spec.commandLine, `option '${CONFIRM_FLAG.usage}' argument missing`);
-	const missing = [...optionFields, ...pageFields].filter((field) => field.type !== "boolean" && values.get(field.label) === true);
-	const argValues = new Map(argFields.map((field, index) => [field, operands[index]?.value]));
-	const valuesOf = (fields) => new Map(fields.map((field) => [field, missing.includes(field) ? void 0 : optionValue(field, values.get(field.label))]));
+	const missing = [...optionFields, ...pageFields].filter((field) => field.type !== "boolean" && (field.variadic ? occurrences.get(field.label)?.includes(true) : values.get(field.label) === true));
+	const argValue = (field, index) => {
+		if (field === stdin?.field) return stdin.text;
+		if (!field.variadic) return operands[index]?.value;
+		return variadicValue(field, operands.slice(index).filter((operand) => !operand.afterUnknownOption).map((operand) => operand.value));
+	};
+	const argValues = new Map(argFields.map((field, index) => [field, argValue(field, index)]));
+	const extraOperands = argFields.some((field) => field.variadic) ? [] : operands.slice(argFields.length);
+	const valuesOf = (fields) => new Map(fields.map((field) => [field, missing.includes(field) ? void 0 : optionValue(field, occurrences.get(field.label))]));
+	const flagWording = {
+		howToPass: (field) => `pass ${field.usage}`,
+		arrayIssueLine: flagValuesIssueLine,
+		reported: missing
+	};
 	const optionValues = valuesOf(optionFields);
 	const pageValues = valuesOf(pageFields);
 	const args = parse(command.args ?? NO_INPUT, argValues);
@@ -7944,10 +8521,14 @@ function parseInput(spec, words, invocation) {
 	const unknown = unknownOptionsOf(unknownOptions, candidateFlags(known));
 	const otherLines = [
 		...missing.map((field) => `  ${field.label}: missing value, pass ${field.usage}`),
-		...operands.slice(argFields.length).filter((operand) => !operand.afterUnknownOption).map((operand) => `  unexpected argument ${JSON.stringify(operand.value)}`),
-		...issueLines(args, argValues, (field) => `pass it as argument ${argFields.indexOf(field) + 1}`, []),
-		...issueLines(options, optionValues, (field) => `pass ${field.usage}`, missing),
-		...issueLines(page, pageValues, (field) => `pass ${field.usage}`, missing)
+		...extraOperands.filter((operand) => !operand.afterUnknownOption).map((operand) => `  unexpected argument ${JSON.stringify(operand.value)}`),
+		...issueLines(args, argValues, {
+			howToPass: (field) => `pass it as argument ${argFields.indexOf(field) + 1}`,
+			arrayIssueLine: (field, raw, issue) => operandsIssueLine(field, raw, issue, argFields.indexOf(field) + 1),
+			fromStdin: stdin?.field
+		}),
+		...issueLines(options, optionValues, flagWording),
+		...issueLines(page, pageValues, flagWording)
 	];
 	if (unknown.length === 0 && otherLines.length === 0 && args.success && options.success && page.success) return {
 		input: {
@@ -7961,9 +8542,12 @@ function parseInput(spec, words, invocation) {
 	if (only !== void 0 && unknown.length === 1 && otherLines.length === 0) throw unknownOptionError(spec.commandLine, invocation, only.flag, only.suggestion === void 0 ? [] : [only.suggestion]);
 	throw invalidInput(spec.commandLine, invocation, unknown, otherLines);
 }
-/** The validated input and Standard flag values of the routed Command, or one usage error. */
-function parseCommand({ spec, words, json }, invocation) {
-	const { input, page, values } = parseInput(spec, words, invocation);
+/**
+* The validated input and Standard flag values of the routed Command, or one usage error; the arg
+* given `-` takes its text from `readStdin`.
+*/
+async function parseCommand({ spec, words, json }, invocation, readStdin) {
+	const { input, page, values } = await parseInput(spec, words, invocation, readStdin);
 	const confirm = values.get(CONFIRM_FLAG.flag);
 	return {
 		input,
@@ -8034,7 +8618,7 @@ function walk(node, words, json, invocation) {
 	return unknownCommand(node, first, json);
 }
 function unknownCommand(group, name, json) {
-	const suggestions = closestNames(name, Object.keys(group.commands));
+	const suggestions = closestNames(name, Object.keys(visibleCommands(group)));
 	return {
 		kind: "usage error",
 		error: unknownCommandError(group.commandLine, name, suggestions),
@@ -8059,23 +8643,28 @@ function dotenvPath(cliName, env) {
 	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
 	return join(config, cliName, ".env");
 }
-function readDotenv(path) {
+function readDotenv(path, fileError) {
+	let text;
 	try {
-		return parseEnv(readFileSync(path, "utf8"));
+		text = readFileSync(path, "utf8");
 	} catch (error) {
 		if (isMissingFile(error)) return {};
-		throw error;
+		throw fileError(error, {
+			path,
+			access: "read"
+		});
 	}
+	return parseEnv(text);
 }
 /** Looks `name` up in the env, then in `$XDG_CONFIG_HOME/<cli>/.env`; an empty value counts as unset. */
-function secretOf(cliName, env, name) {
+function secretOf({ cliName, env, fileError }, name) {
 	const fromEnv = env[name];
 	if (fromEnv) return {
 		value: fromEnv,
 		origin: { kind: "env" }
 	};
 	const path = dotenvPath(cliName, env);
-	const fromFile = readDotenv(path)[name];
+	const fromFile = readDotenv(path, fileError)[name];
 	return fromFile ? {
 		value: fromFile,
 		origin: {
@@ -8109,10 +8698,9 @@ async function prepare(folder, cutoff, target) {
 		await mkdir(folder, { recursive: true });
 		await pruneOld(folder, cutoff);
 	} catch (error) {
-		throw classifyErrno(error, {
+		throw target.fileError(error, {
 			path: folder,
-			callerLine: target.callerLine,
-			env: target.env
+			access: "write"
 		});
 	}
 }
@@ -8168,51 +8756,22 @@ function styleFor(env, stdoutIsTTY) {
 }
 //#endregion
 //#region ../agent-cli/dist/run-cli.js
-/** `files` resolving paths against `cwd`, its failures classified by errno. */
-function classifiedFiles(files, base, callerLine) {
-	return {
-		exists: async (path) => {
-			const target = resolve(base.cwd, path);
-			try {
-				return await files.exists(target);
-			} catch (error) {
-				throw classifyErrno(error, {
-					path: target,
-					callerLine,
-					env: base.env
-				});
-			}
-		},
-		write: async (path, data) => {
-			const target = resolve(base.cwd, path);
-			try {
-				await files.write(target, data);
-			} catch (error) {
-				throw classifyErrno(error, {
-					path: target,
-					callerLine,
-					env: base.env
-				});
-			}
-		}
-	};
+function stdinNeverEndedHint(callerLine) {
+	return `stdin never ended: pipe the text into \`${callerLine}\`, or redirect a file into it`;
 }
-async function runCommand(routed, { base, writeStdout, signal, format: baseFormat, ports, clock, files, spawn, projectFile }) {
+async function runCommand(routed, { base, writeStdout, signal, format: baseFormat, ports, clock, files, spawn, projectFile, stdin, platform }) {
 	const { command, commandLine } = routed.spec;
+	const invocation = {
+		...baseFormat.invocation,
+		flags: knownFlags(routed.spec)
+	};
 	const format = {
 		...baseFormat,
-		json: routed.json
+		json: routed.json,
+		invocation
 	};
-	const { invocation } = format;
-	let parsed;
-	let project;
-	try {
-		parsed = parseCommand(routed, invocation);
-		project = projectFile === void 0 ? void 0 : projectOf(projectFile, base.cwd);
-	} catch (error) {
-		return errorResult(error, format);
-	}
-	const { input, flags } = parsed;
+	const typedLine = (change) => commandLineOf(invocation, change);
+	let resumeHint;
 	const control = new RunControl({
 		commandLine,
 		outer: signal,
@@ -8220,35 +8779,62 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 		progress: base.progress,
 		runDeadline: command.deadline === void 0 ? void 0 : {
 			ms: command.deadline.ms,
-			hint: command.deadline.resume(input)
+			hint: () => resumeHint ?? stdinNeverEndedHint(typedLine())
 		}
 	});
+	let parsed;
+	let project;
+	try {
+		checkOperator(routed.spec, base.env, typedLine());
+		parsed = await parseCommand(routed, invocation, (field) => {
+			if (isTerminal(stdin)) base.progress(readingLine(field.name, platform));
+			return readStdin(stdin, control.signal);
+		});
+		project = projectFile === void 0 ? void 0 : projectOf(projectFile, base.cwd);
+	} catch (error) {
+		control.close();
+		return errorResult(error, format);
+	}
+	const { input, flags } = parsed;
+	resumeHint = command.deadline?.resume(input, typedLine);
 	let delivered;
-	const callerLine = commandLineOf(invocation);
-	const classified = classifiedFiles(files, base, callerLine);
+	const { fileError } = base;
+	const outputs = outputsGuard(classifiedFiles(files, {
+		cwd: base.cwd,
+		fileError
+	}), base.cwd);
 	const spill = spillTo({
 		cliName: format.cliName,
 		commandName: command.name,
 		env: base.env,
 		clock,
-		files: classified,
-		callerLine
+		files: outputs.files,
+		fileError
 	});
-	const ctx = {
+	const portsBase = {
 		...base,
 		signal: control.signal,
-		deadline: (ms) => control.deadline(ms),
-		runToEnd: (name, work) => control.runToEnd(name, work),
-		ports: ports(),
 		clock,
-		files: classified,
+		files: outputs.files,
 		spawn: contextSpawn(spawn, {
 			cwd: base.cwd,
 			env: base.env,
-			signal: control.signal
-		}, callerLine),
+			signal: control.signal,
+			progress: base.progress
+		}, fileError)
+	};
+	const builtPorts = once(() => ports(portsBase));
+	const ctx = {
+		...portsBase,
+		deadline: (ms) => control.deadline(ms),
+		runToEnd: (name, work) => control.runToEnd(name, work),
+		get ports() {
+			return builtPorts();
+		},
 		project,
-		poll: (check, { intervalMs }) => poll(clock, check, intervalMs, control.signal),
+		force: flags.force,
+		commandLine: typedLine,
+		poll: (check, { intervalMs, signal: stop }) => poll(clock, check, intervalMs, stop === void 0 ? control.signal : AbortSignal.any([control.signal, stop])),
 		deliver: (data) => {
 			delivered = deliveredOutcome(command, data);
 		}
@@ -8262,14 +8848,15 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 				dryRun: flags.dryRun,
 				confirm: flags.confirm,
 				yes: flags.yes,
-				force: flags.force,
 				page: flags.page,
 				invocation,
 				commandLine,
 				started: async (outcome) => {
 					writeStdout(await startedOutput(outcome, format, spill));
 					served = true;
-				}
+				},
+				files,
+				guardOutputs: outputs.guard
 			}))
 		};
 	} catch (error) {
@@ -8285,29 +8872,78 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 		fields: flags.fields
 	}, spill);
 }
+/** `build` runs on the first call; later calls give its value or throw its error again. */
+function once(build) {
+	let outcome;
+	return () => {
+		if (outcome === void 0) try {
+			outcome = {
+				ok: true,
+				value: build()
+			};
+		} catch (error) {
+			outcome = {
+				ok: false,
+				error
+			};
+		}
+		if (outcome.ok) return outcome.value;
+		throw outcome.error;
+	};
+}
+function selfOf(name, bin) {
+	return bin === void 0 ? [name] : [
+		process.execPath,
+		...process.execArgv,
+		bin
+	];
+}
 function portsOf(cli, replacement) {
 	if (replacement !== void 0) return () => replacement;
 	return cli.ports ?? (() => ({}));
 }
-async function runWithProgress(cli, argv, options, write) {
+function stopLine(notice, json) {
+	return json ? progressLine(notice, true) : `\n${notice}\n`;
+}
+/** Calls `onStop` if `signal` aborts while `work` runs. */
+async function whileStopping(signal, onStop, work) {
+	if (signal === void 0 || onStop === void 0) return work();
+	signal.addEventListener("abort", onStop, { once: true });
+	try {
+		return await work();
+	} finally {
+		signal.removeEventListener("abort", onStop);
+	}
+}
+async function runWithProgress(cli, argv, options, write, stopNotice) {
 	const format = {
 		cliName: cli.name,
 		env: options.env,
 		style: styleFor(options.env, options.stdoutIsTTY === true),
 		invocation: {
 			cliName: cli.name,
-			argv
+			argv,
+			flags: []
 		},
 		json: false,
 		errors: cli.errors ?? {},
 		stop: options.signal
 	};
-	const builtIns = cli.commands === void 0 ? {} : builtInCommands(cli, options.bin);
+	const builtIns = cli.commands === void 0 ? {} : builtInCommands(cli, {
+		bin: options.bin,
+		node: options.node
+	});
 	const root = cli.commands === void 0 ? commandSpec(cli.name, cli.command) : groupSpec(cli.name, {
 		...cli.commands,
 		...builtIns
 	});
 	const routed = route(root, format.invocation);
+	const platform = options.platform ?? process.platform;
+	const fileError = fileErrorOf({
+		callerLine: commandLineOf(format.invocation),
+		env: options.env,
+		platform
+	});
 	const misused = (node) => isAgent(options.env) ? {
 		...format,
 		usageHelp: textHelp(node, root, cli, format.style)
@@ -8322,13 +8958,21 @@ async function runWithProgress(cli, argv, options, write) {
 			...misused(routed.node),
 			json: routed.json
 		});
-		case "command": return runCommand(routed, {
+		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(routed, {
 			base: {
 				cwd: options.cwd,
 				env: options.env,
 				packageRoot: packageRootOf(options.bin, options.cwd),
-				progress: (message) => write.stderr(`${message}\n`),
-				secret: (name) => secretOf(cli.name, options.env, name)
+				progress: (message) => write.stderr(progressLine(message, routed.json)),
+				secret: (name) => secretOf({
+					cliName: cli.name,
+					env: options.env,
+					fileError
+				}, name),
+				fileError,
+				version: cli.version,
+				build: cli.build,
+				self: selfOf(cli.name, options.bin)
 			},
 			writeStdout: (text) => write.stdout(text),
 			signal: options.signal,
@@ -8337,8 +8981,10 @@ async function runWithProgress(cli, argv, options, write) {
 			clock: options.clock ?? realClock,
 			files: options.files ?? realFiles(),
 			spawn: options.spawn ?? realSpawn,
-			projectFile: Object.values(builtIns).includes(routed.spec.command) ? void 0 : cli.project
-		});
+			projectFile: Object.values(builtIns).includes(routed.spec.command) ? void 0 : cli.project,
+			stdin: options.stdin ?? "",
+			platform
+		}));
 	}
 }
 //#endregion
@@ -8350,7 +8996,6 @@ async function runProcess(cli) {
 	const stop = new AbortController();
 	const onSignal = (signal) => {
 		if (stop.signal.aborted) process.exit(SIGNAL_EXIT_CODES[signal]);
-		process.stderr.write("\nstopping… (Ctrl-C again to quit now)\n");
 		stop.abort(signal);
 	};
 	process.on("SIGINT", onSignal);
@@ -8361,11 +9006,13 @@ async function runProcess(cli) {
 			cwd: process.cwd(),
 			stdoutIsTTY: process.stdout.isTTY === true,
 			signal: stop.signal,
-			bin: process.argv[1]
+			bin: process.argv[1],
+			node: process.execPath,
+			stdin: process.stdin
 		}, {
 			stdout: (text) => process.stdout.write(text),
 			stderr: (text) => process.stderr.write(text)
-		});
+		}, "stopping… (Ctrl-C again to quit now)");
 		await written(process.stdout, result.stdout);
 		await written(process.stderr, result.stderr);
 		process.exitCode = result.exitCode;
@@ -8378,9 +9025,9 @@ async function runProcess(cli) {
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "411548a",
+	"sha": "c325cae",
 	"dirty": false,
-	"builtAt": "2026-10-19T08:42:00.085Z"
+	"builtAt": "2026-10-19T14:33:32.022Z"
 };
 //#endregion
 //#region src/steps.ts
@@ -8509,7 +9156,7 @@ async function writeTemplate(root, files, values) {
 }
 //#endregion
 //#region src/version.ts
-const version = "0.3.0";
+const version = "0.5.0";
 //#endregion
 //#region src/create.ts
 const { defineCommand } = agentCli();