@duyquangnvx/create-agent-cli 0.20.0 → 0.22.0

package/dist/bin.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { constants, homedir, tmpdir } from "node:os";
 import { parseArgs, parseEnv } from "node:util";
-import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { constants, existsSync, readFileSync, realpathSync } from "node:fs";
-import { constants as constants$1, homedir, tmpdir } from "node:os";
+import { constants as constants$1, existsSync, readFileSync, realpathSync } from "node:fs";
 import { access, chmod, link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
-import { spawn } from "node:child_process";
+import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 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
@@ -5740,40 +5740,6 @@ function untilAborted(signal) {
 	});
 }
 //#endregion
-//#region ../agent-cli/dist/clock.js
-const realClock = {
-	now: () => Date.now(),
-	sleep: (ms, signal) => new Promise((resolve, reject) => {
-		if (signal?.aborted === true) {
-			reject(signal.reason);
-			return;
-		}
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(signal?.reason);
-		};
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		signal?.addEventListener("abort", onAbort, { once: true });
-	})
-};
-/** Runs `then` once `ms` have passed on `clock`; aborting `cancel` drops it. */
-function after(clock, ms, cancel, then) {
-	clock.sleep(ms, cancel).then(then, (error) => {
-		if (!cancel.aborted) throw error;
-	});
-}
-async function poll(clock, check, intervalMs, signal) {
-	for (;;) {
-		signal.throwIfAborted();
-		const value = await check();
-		if (value !== void 0) return value;
-		await clock.sleep(intervalMs, signal);
-	}
-}
-//#endregion
 //#region ../agent-cli/dist/command-line/tokenize.js
 const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
 function isOptionLike(word) {
@@ -5926,6 +5892,9 @@ function wholeLine(line) {
 function isWords(step) {
 	return Array.isArray(step);
 }
+function isRerun(step) {
+	return !isWords(step) && step.kind === "rerun";
+}
 /** The words after the Run-as, or `undefined` for a line given whole. */
 function wordsOf(step) {
 	if (isWords(step)) return step;
@@ -6081,1006 +6050,1081 @@ function formatRuntimeError(error, format) {
 	return errors.map((each) => errorLines(each, format)).join("");
 }
 //#endregion
-//#region ../agent-cli/dist/context/stdin.js
-const STDIN_META = "stdin";
-function isStdinSchema(schema) {
-	return globalRegistry$1.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;
+//#region ../agent-cli/dist/tail.js
+/** The last `count` lines of a child's output, trimmed; empty when it wrote nothing. */
+function lastLines(output, count) {
+	return output.trim().split("\n").slice(-count).join("\n");
 }
-const STDIN_STALLED = "STDIN_STALLED";
-/** How long a stdin that is not a terminal may send nothing, from the start of the read and from each chunk. */
-const STDIN_IDLE_MS = 3e4;
-function stdinStalled(callerLine) {
-	return new CliError({
-		code: STDIN_STALLED,
-		message: `stdin sent nothing for ${STDIN_IDLE_MS} ms`,
-		hint: `stdin never ended: close the pipe or heredoc that feeds \`${callerLine}\`, pass the text as an argument instead, or write a slow producer's output to a file and redirect it in`
-	});
+//#endregion
+//#region ../agent-cli/dist/define.js
+function isCommand(node) {
+	return typeof node.effect === "string";
 }
+//#endregion
+//#region ../agent-cli/dist/context/declared.js
 /**
-* The whole of `source` as UTF-8; rejects with the signal's reason once it aborts, and with
-* `idle.stalled()` once a stream that is not a terminal sends nothing for `STDIN_IDLE_MS`.
+* What the CLI declares itself (`own`) and every Command under `commands` declares, each name once,
+* for a `doctor` row: a Command requires only its own, but `doctor` checks them all.
 */
-function readStdin(source, signal, idle) {
-	if (typeof source === "string") return signal.aborted ? Promise.reject(signal.reason) : Promise.resolve(source);
-	return new Promise((resolve, reject) => {
-		const chunks = [];
-		let idleWindow = new AbortController();
-		const watchIdle = () => {
-			idleWindow.abort();
-			idleWindow = new AbortController();
-			if (isTerminal(source)) return;
-			after(idle.clock, STDIN_IDLE_MS, idleWindow.signal, () => {
-				stop();
-				reject(idle.stalled());
-			});
-		};
-		const onData = (chunk) => {
-			chunks.push(chunk instanceof Uint8Array ? chunk : Buffer.from(String(chunk)));
-			watchIdle();
-		};
-		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);
-			idleWindow.abort();
-		};
-		if (signal.aborted) {
-			reject(signal.reason);
-			return;
-		}
-		signal.addEventListener("abort", onAbort, { once: true });
-		watchIdle();
-		source.on("data", onData).once("end", onEnd).once("error", onError);
-	});
+function declaredIn(own, commands, needsOf) {
+	const walk = (node) => isCommand(node) ? [...needsOf(node) ?? []] : Object.values(node).flatMap(walk);
+	return [...new Map([...own, ...walk(commands)].map((need) => [need.name, need])).values()];
 }
 //#endregion
-//#region ../agent-cli/dist/command-line/input.js
-function isWrapper(schema) {
-	return schema instanceof ZodOptional || schema instanceof ZodNullable || schema instanceof ZodDefault || schema instanceof ZodPrefault;
-}
-function kebab(key) {
-	return key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+//#region ../agent-cli/dist/context/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 typeOf(schema) {
-	if (schema instanceof ZodNumber) return "number";
-	return schema instanceof ZodBoolean ? "boolean" : "string";
+function extensionsOf(env) {
+	return process.platform === "win32" ? (env.PATHEXT ?? WINDOWS_EXTENSIONS).split(";") : [""];
 }
-function describe(schema) {
-	let current = 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);
+async function isExecutable(file) {
+	try {
+		await access(file, constants$1.X_OK);
+		return true;
+	} catch (error) {
+		if (isNothingThere(error) || errnoOf(error) === "EACCES") return false;
+		throw error;
 	}
-	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,
-		variadic,
-		stdin
-	};
 }
-function argLabel(key, { variadic, required, stdin }) {
-	if (stdin) return required ? `<${key}|->` : `[${key}|-]`;
-	if (!variadic) return `<${key}>`;
-	return required ? `<${key}...>` : `[${key}...]`;
+/** 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}`);
 }
-function argField(key, schema) {
-	const described = describe(schema);
-	const label = argLabel(key, described);
-	return {
-		key,
-		name: key,
-		schema,
-		...described,
-		label,
-		usage: label
-	};
+/** 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;
 }
-function optionField(key, schema) {
-	const described = describe(schema);
-	const name = kebab(key);
-	const isBoolean = described.type === "boolean";
-	const label = isBoolean && described.defaultValue === true ? `--no-${name}` : `--${name}`;
-	const value = `<${described.choices?.join("|") ?? "value"}>${described.variadic ? "..." : ""}`;
-	const usage = isBoolean ? label : `${label} ${value}`;
-	return {
-		key,
-		name,
-		schema,
-		...described,
-		label,
-		usage
-	};
+/** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
+async function checkTools(tools, env, rerun) {
+	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 runtimeError({
+		code: TOOL_MISSING,
+		message: `${missing.length === 1 ? "a tool it runs is" : "tools it runs are"} not on PATH: ${names}`,
+		hint: "run the Next steps in order: each install, then the command again",
+		next: [...missing.map(({ install }) => wholeLine(install)), rerun]
+	});
 }
-function fieldsOf(schema, toField) {
-	return schema === void 0 ? [] : Object.entries(schema.shape).map(([key, value]) => toField(key, value));
+/** One `doctor` row per distinct tool the CLI and its Commands declare, with its install command as the fix. */
+function toolRows(tools, commands) {
+	return declaredIn(tools, commands, (command) => command.tools).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}`
+			};
+		}
+	}));
 }
-function argFields(schema) {
-	return fieldsOf(schema, argField);
+//#endregion
+//#region ../agent-cli/dist/context/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$/;
+const LINE_END = /\r\n|\r(?!$)|\n/;
+function isWhole(input) {
+	return typeof input === "string" || input instanceof Uint8Array;
 }
-function keysOf(fields) {
-	return fields.map(({ key }) => `'${key}'`).join(", ");
+function escapedForCmd(text) {
+	return text.replace(CMD_META, "^$1");
 }
-/** 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`);
+function batchArgument(arg, shim) {
+	const escaped = escapedForCmd(`"${arg.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\*)$/, "$1$1")}"`);
+	return shim ? escapedForCmd(escaped) : escaped;
 }
-/** 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 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());
+	});
 }
-function optionFields(schema) {
-	return fieldsOf(schema, optionField);
+/** Calls `onLine` with each complete line pushed, and with the unterminated rest at the end. */
+function lineSplitter(onLine) {
+	let rest = "";
+	return {
+		push(text) {
+			if (onLine === void 0) return;
+			const lines = (rest + text).split(LINE_END);
+			rest = lines.pop() ?? "";
+			for (const line of lines) onLine(line);
+		},
+		end() {
+			if (rest !== "") onLine?.(rest.replace(TRAILING_CR, ""));
+			rest = "";
+		}
+	};
 }
-/** 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`);
+/** `onLine`, passing what it throws to `fail` and called no more once `failed()`. */
+function guarded(onLine, failed, fail) {
+	if (onLine === void 0) return void 0;
+	return (line) => {
+		if (failed()) return;
+		try {
+			onLine(line);
+		} catch (error) {
+			fail(error);
+		}
+	};
 }
-//#endregion
-//#region ../agent-cli/dist/command-line/usage.js
-const INVALID_INPUT = "INVALID_INPUT";
-const UNKNOWN_OPTION = "UNKNOWN_OPTION";
-const UNKNOWN_COMMAND = "UNKNOWN_COMMAND";
-function unknownError({ code, problem, commandLine, corrections, listed }) {
-	return new UsageError({
-		code,
-		message: `${problem} for \`${commandLine}\``,
-		hint: corrections.length === 0 ? `run \`${commandLine} --help\` to see the ${listed}` : `did you mean ${corrections.map((correction) => `\`${correction}\``).join(" or ")}?`
+/** Settles once the child has taken what was written, or its stdin has closed. */
+function drained(stdin) {
+	return new Promise((resolve) => {
+		const done = () => {
+			stdin.off("drain", done);
+			stdin.off("close", done);
+			resolve();
+		};
+		stdin.on("drain", done);
+		stdin.on("close", done);
 	});
 }
-function unknownOptionError(commandLine, invocation, flag, suggestions) {
-	return unknownError({
-		code: UNKNOWN_OPTION,
-		problem: `unknown option '${flag}'`,
-		commandLine,
-		corrections: suggestions.map((name) => commandLineRenaming(invocation, /* @__PURE__ */ new Map([[flag, name]]))),
-		listed: "options"
+/**
+* Writes `input` to the child's stdin and ends it, stopping once the child is gone or the run
+* aborts.
+*/
+async function feed(stdin, input, signal) {
+	stdin.on("error", () => void 0);
+	const chunks = isWhole(input) ? [input] : input;
+	for await (const chunk of chunks) {
+		if (signal.aborted || stdin.destroyed) return;
+		if (!stdin.write(chunk)) await drained(stdin);
+	}
+	stdin.end();
+}
+/**
+* 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, stdin, detached = false }) {
+	signal.throwIfAborted();
+	const launch = await launchOf(command, args, env);
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const child = spawn(launch.command, launch.args, {
+			cwd,
+			env,
+			shell: launch.shell,
+			windowsHide: true,
+			stdio: [
+				stdin === void 0 ? "ignore" : "pipe",
+				"pipe",
+				"pipe"
+			],
+			detached: detached && process.platform !== "win32"
+		});
+		let stopped = Promise.resolve();
+		const kill = () => {
+			stopped = stop(child);
+		};
+		signal.addEventListener("abort", kill, { once: true });
+		let callerFailure;
+		const fail = (error) => {
+			if (callerFailure !== void 0) return;
+			callerFailure = { error };
+			kill();
+		};
+		let stdout = "";
+		let stderr = "";
+		const lines = guarded(onLine, () => callerFailure !== void 0, fail);
+		const stdoutLines = lineSplitter(lines);
+		const stderrLines = lineSplitter(lines);
+		child.stdout?.setEncoding("utf8").on("data", (chunk) => {
+			stdout += chunk;
+			stdoutLines.push(chunk);
+		});
+		child.stderr?.setEncoding("utf8").on("data", (chunk) => {
+			stderr += chunk;
+			stderrLines.push(chunk);
+		});
+		if (stdin !== void 0 && child.stdin !== null) feed(child.stdin, stdin, signal).catch(fail);
+		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();
+			if (callerFailure !== void 0) {
+				const { error } = callerFailure;
+				stopped.then(() => reject(error));
+				return;
+			}
+			resolve({
+				stdout,
+				stderr,
+				exitCode: code ?? SIGNAL_EXIT_BASE + (killedBy === null ? 0 : constants.signals[killedBy])
+			});
+		});
 	});
 }
-/** Text opening with `-` was read as an option, where the Command could have read it from stdin. */
-function stdinTextError(commandLine, invocation, word) {
-	const withStdin = commandLineOf(invocation, {
-		remove: [word],
-		add: ["-"]
+async function launchOf(command, args, env) {
+	return process.platform === "win32" ? windowsLaunch(command, args, env) : {
+		command,
+		args,
+		shell: false
+	};
+}
+/**
+* Starts a child in its own process group (its own console on Windows) with no stdio, and settles
+* once it has started; the parent neither waits for it nor keeps it from exiting.
+*/
+const realSpawnDetached = async (command, args, { cwd, env }) => {
+	const launch = await launchOf(command, args, env);
+	return new Promise((resolve, reject) => {
+		const child = spawn(launch.command, launch.args, {
+			cwd,
+			env,
+			shell: launch.shell,
+			windowsHide: true,
+			stdio: "ignore",
+			detached: true
+		});
+		child.unref();
+		child.once("error", reject);
+		child.once("spawn", () => {
+			child.off("error", reject);
+			const { pid } = child;
+			if (pid === void 0) reject(/* @__PURE__ */ new Error(`${command} started without a pid`));
+			else resolve({ pid });
+		});
 	});
-	return new UsageError({
-		code: UNKNOWN_OPTION,
-		message: `unknown option '${word}' for \`${commandLine}\``,
-		hint: `to pass text opening with \`-\`, pass \`-\` and send the text on stdin through a heredoc: \`${withStdin} <<'EOF'\`, then the text, then \`EOF\``
+};
+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 unknownCommandError(commandLine, name, suggestions) {
-	return unknownError({
-		code: UNKNOWN_COMMAND,
-		problem: `unknown command '${name}'`,
-		commandLine,
-		corrections: suggestions.map((suggestion) => `${commandLine} ${suggestion}`),
-		listed: "commands"
+var MissingToolError = class extends CliError {
+	tool;
+	constructor(tool, rerun, cause) {
+		super({
+			code: TOOL_MISSING,
+			message: `${tool} could not be started: it is not on PATH`,
+			hint: `install ${tool}, then run the Next step`,
+			next: [rerun]
+		}, { cause });
+		this.tool = tool;
+	}
+};
+function missingToolOf(error) {
+	return error instanceof MissingToolError ? error.tool : void 0;
+}
+function startError(command, error, { fileError, rerun }) {
+	if (isMissingFile(error)) return new MissingToolError(command, rerun, error);
+	return fileError(error, {
+		path: command,
+		access: "read"
 	});
 }
-function invalidInputError(commandLine, problem) {
-	return new UsageError({
-		code: INVALID_INPUT,
-		message: problem,
-		hint: `run \`${commandLine} --help\` to see the expected input`
-	});
-}
-//#endregion
-//#region ../agent-cli/dist/list.js
-const UNKNOWN_FIELD = "UNKNOWN_FIELD";
-const DEFAULT_PAGE_LIMIT = 20;
-const FIELDS_FLAG = "--fields";
-const SEPARATOR = ",";
-const COLUMN_SEPARATOR = "	";
-const UNSAFE_IN_COLUMN = /[\t\n\r]/;
-const PAGE_INPUT = object({
-	limit: number().int().positive().default(DEFAULT_PAGE_LIMIT),
-	cursor: string().min(1).optional()
-});
-var Page = class {
-	items;
-	nextCursor;
-	constructor(items, nextCursor) {
-		this.items = items;
-		this.nextCursor = nextCursor;
+async function* reported(stream, onError) {
+	try {
+		yield* stream;
+	} catch (error) {
+		onError(error);
+		throw error;
 	}
-};
-const PAGE_FLAG_DESCRIPTIONS = {
-	limit: `how many rows to show, a positive whole number (default: ${DEFAULT_PAGE_LIMIT})`,
-	cursor: "where to start, as given by the previous page's next"
-};
-function pageFlag(key) {
-	const field = optionField(key, PAGE_INPUT.shape[key]);
-	return {
-		flag: field.label,
-		usage: field.usage,
-		description: PAGE_FLAG_DESCRIPTIONS[key],
-		takes: "optional value",
-		schema: field.schema
-	};
 }
-function fieldsFlag(rowFields) {
-	return {
-		flag: FIELDS_FLAG,
-		usage: `${FIELDS_FLAG} <a,b>`,
-		description: `print only these comma-separated fields of each row (any of: ${rowFields.join(", ")})`,
-		takes: "optional value",
-		schema: string()
+/** `input`, a stream passing each error it throws to `onError` before the reader sees it. */
+function reporting(input, onError) {
+	return input === void 0 || isWhole(input) ? input : reported(input, onError);
+}
+/** `onLine`, passing each error it throws to `onError` before its caller sees it. */
+function reportingLines(onLine, onError) {
+	if (onLine === void 0) return void 0;
+	return (line) => {
+		try {
+			onLine(line);
+		} catch (error) {
+			onError(error);
+			throw error;
+		}
 	};
 }
-const PAGE_FIELDS = optionFields(PAGE_INPUT);
-const PAGE_FLAGS = {
-	limit: pageFlag("limit"),
-	cursor: pageFlag("cursor")
-};
-/** The Standard flags every List Command gets, as the caller types them. */
-const LIST_FLAGS = [...Object.values(PAGE_FLAGS).map(({ flag }) => flag), FIELDS_FLAG];
-function listSpec(rows) {
-	const rowFields = Object.keys(rows.shape);
-	return {
-		rowFields,
-		pageFields: PAGE_FIELDS,
-		standardFlags: [...Object.values(PAGE_FLAGS), fieldsFlag(rowFields)],
-		output: object({
-			items: array(rows),
-			next: string().optional()
-		})
+function contextSpawn(run, defaults, scope) {
+	return async (command, args = [], options = {}) => {
+		let callerFailure;
+		const caller = (error) => {
+			callerFailure = { error };
+		};
+		let result;
+		try {
+			result = await run(command, args, {
+				cwd: options.cwd ?? defaults.cwd,
+				env: options.env ?? defaults.env,
+				signal: defaults.signal,
+				onLine: reportingLines(options.onLine, caller),
+				stdin: reporting(options.stdin, caller)
+			});
+		} catch (error) {
+			throw callerFailure?.error === error ? error : startError(command, error, scope);
+		}
+		if (options.check === true && result.exitCode !== 0) throw failedError(command, result);
+		return result;
 	};
 }
-function quoted(names) {
-	return names.map((name) => `'${name}'`).join(", ");
+/** `ctx.spawnDetached`: `run` bound to the run's cwd and env, its start failures classified by errno. */
+function contextSpawnDetached(run, defaults, scope) {
+	return async (command, args = [], options = {}) => {
+		defaults.signal.throwIfAborted();
+		try {
+			return await run(command, args, {
+				cwd: options.cwd ?? defaults.cwd,
+				env: options.env ?? defaults.env
+			});
+		} catch (error) {
+			throw startError(command, error, scope);
+		}
+	};
 }
-/** The fields the caller asked for, in their order, or undefined when they gave no `--fields`. */
-function selectedFields(values, rowFields, commandLine) {
-	const raw = values.get(FIELDS_FLAG);
-	if (raw === void 0) return;
-	const hint = `pass ${FIELDS_FLAG} with any of: ${rowFields.join(", ")}`;
-	const names = typeof raw === "string" ? raw.split(SEPARATOR).filter((name) => name !== "") : [];
-	if (names.length === 0) throw new UsageError({
-		code: INVALID_INPUT,
-		message: `${FIELDS_FLAG}: missing value for \`${commandLine}\``,
-		hint
-	});
-	const unknown = names.filter((name) => !rowFields.includes(name));
-	if (unknown.length > 0) throw new UsageError({
-		code: UNKNOWN_FIELD,
-		message: `unknown field ${quoted(unknown)} for \`${commandLine}\``,
-		hint
+//#endregion
+//#region ../agent-cli/dist/clock.js
+const realClock = {
+	now: () => Date.now(),
+	sleep: (ms, signal) => new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	})
+};
+/** Runs `then` once `ms` have passed on `clock`; aborting `cancel` drops it. */
+function after(clock, ms, cancel, then) {
+	clock.sleep(ms, cancel).then(then, (error) => {
+		if (!cancel.aborted) throw error;
 	});
-	return names;
-}
-function fieldOf(row, field) {
-	return typeof row === "object" && row !== null ? row[field] : void 0;
-}
-function projected(rows, fields) {
-	return rows.map((row) => Object.fromEntries(fields.map((field) => [field, fieldOf(row, field)])));
-}
-function cell(value) {
-	if (value === void 0 || value === null) return "";
-	return typeof value === "string" && !UNSAFE_IN_COLUMN.test(value) ? value : JSON.stringify(value);
-}
-/** Selected rows as text: a header line of the field names, then one tab-separated line per row. */
-function renderRows(rows, fields) {
-	return `${[fields, ...rows.map((row) => fields.map((field) => cell(row[field])))].map((line) => line.join(COLUMN_SEPARATOR)).join("\n")}\n`;
 }
-function cursorWords(cursor) {
-	const { flag } = PAGE_FLAGS.cursor;
-	return cursor.startsWith("-") ? [`${flag}=${cursor}`] : [flag, cursor];
+async function poll(clock, check, intervalMs, signal) {
+	for (;;) {
+		signal.throwIfAborted();
+		const value = await check();
+		if (value !== void 0) return value;
+		await clock.sleep(intervalMs, signal);
+	}
 }
-function printedPage(page, invocation) {
-	return page.nextCursor === void 0 ? { items: page.items } : {
-		items: page.items,
-		next: lineOf({
-			kind: "rerun",
-			words: changedArgv(invocation, {
-				remove: [PAGE_FLAGS.cursor.flag],
-				add: cursorWords(page.nextCursor)
-			}),
-			stdinArg: invocation.stdinArg
-		}, invocation.runAs)
-	};
+//#endregion
+//#region ../agent-cli/dist/context/stdin.js
+const STDIN_META = "stdin";
+function isStdinSchema(schema) {
+	return globalRegistry$1.get(schema)?.[STDIN_META] === true;
 }
-/** The lines that end a rendered page, so the caller always knows whether and how to get more. */
-function pageFooter({ items, next }, style) {
-	return next === void 0 ? `${items.length} shown; no more pages\n` : `${items.length} shown; run the Next step for the next page\n${style.cyan("run:")} ${next}\n`;
+function endOfInputKeys(platform) {
+	return platform === "win32" ? "Ctrl-Z then Enter" : "Ctrl-D";
 }
-//#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";
+/** 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)}`;
 }
-//#endregion
-//#region ../agent-cli/dist/command-line/flags.js
-const HELP_FLAG = "--help";
-const VERSION_FLAG = "--version";
-const ROUTING_FLAGS = [
-	HELP_FLAG,
-	"-h",
-	VERSION_FLAG
-];
-function nameOf$1(flag) {
-	return flag.replace(/^--?/, "");
+function isTerminal(source) {
+	return typeof source !== "string" && "isTTY" in source && source.isTTY === true;
 }
-function standardFlag(flag, { placeholder, ...rest }) {
-	return {
-		flag,
-		usage: placeholder === void 0 ? flag : `${flag} ${placeholder}`,
-		...rest
-	};
+const STDIN_STALLED = "STDIN_STALLED";
+/** How long a stdin that is not a terminal may send nothing, from the start of the read and from each chunk. */
+const STDIN_IDLE_MS = 3e4;
+function stdinStalled(callerLine) {
+	return new CliError({
+		code: STDIN_STALLED,
+		message: `stdin sent nothing for ${STDIN_IDLE_MS} ms`,
+		hint: `stdin never ended: close the pipe or heredoc that feeds \`${callerLine}\`, pass the text as an argument instead, or write a slow producer's output to a file and redirect it in`
+	});
 }
-const JSON_FLAG = standardFlag("--json", {
-	description: "print the result as JSON",
-	takes: "nothing",
-	schema: boolean()
-});
-const DRY_RUN_FLAG = standardFlag("--dry-run", {
-	description: "print the Plan without changing anything",
-	takes: "nothing",
-	schema: boolean()
-});
-const CONFIRM_FLAG = standardFlag("--confirm", {
-	placeholder: "<target>",
-	description: "name the target to confirm the change; an error hint gives the exact command",
-	takes: "value",
-	schema: string()
-});
-const YES_FLAG = standardFlag("--yes", {
-	description: "approve the cost the run states; --dry-run shows it",
-	takes: "nothing",
-	schema: boolean()
-});
-const FORCE_FLAG = standardFlag("--force", {
-	description: "replace a file the run writes that already exists; --dry-run lists every file it writes",
-	takes: "nothing",
-	schema: boolean()
-});
-const EFFECT_FLAGS = {
-	read: [JSON_FLAG],
-	act: [JSON_FLAG],
-	write: [JSON_FLAG, DRY_RUN_FLAG],
-	destructive: [
-		JSON_FLAG,
-		DRY_RUN_FLAG,
-		CONFIRM_FLAG
-	],
-	serve: [JSON_FLAG]
-};
-const RESERVED = new Map([
-	...ROUTING_FLAGS,
-	...EFFECT_FLAGS.destructive.map(({ flag }) => flag),
-	YES_FLAG.flag,
-	FORCE_FLAG.flag,
-	...LIST_FLAGS
-].map((flag) => [nameOf$1(flag), flag]));
-/** The Standard flags of a Command with this Effect and declarations, and of a List Command. */
-function standardFlagsFor(effect, { outputs, force, cost }, list) {
-	const forceFlag = force === void 0 ? FORCE_FLAG : {
-		...FORCE_FLAG,
-		description: force
-	};
-	return [
-		...EFFECT_FLAGS[effect],
-		...outputs || force !== void 0 ? [forceFlag] : [],
-		...cost ? [YES_FLAG] : [],
-		...list?.standardFlags ?? []
-	];
-}
-/** Throws when the Command declares an arg or option under a Standard flag's name. */
-function checkNoStandardFlags(command, label) {
-	const lines = [...argFields(command.args).map(({ key }) => ({
-		kind: "arg",
-		key
-	})), ...optionFields(command.options).map(({ key }) => ({
-		kind: "option",
-		key
-	}))].flatMap(({ kind, key }) => {
-		const flag = RESERVED.get(kebab(key));
-		return flag === void 0 ? [] : [`  ${kind} '${key}' is the Standard flag ${flag}`];
+/**
+* The whole of `source` as UTF-8; rejects with the signal's reason once it aborts, and with
+* `idle.stalled()` once a stream that is not a terminal sends nothing for `STDIN_IDLE_MS`.
+*/
+function readStdin(source, signal, idle) {
+	if (typeof source === "string") return signal.aborted ? Promise.reject(signal.reason) : Promise.resolve(source);
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let idleWindow = new AbortController();
+		const watchIdle = () => {
+			idleWindow.abort();
+			idleWindow = new AbortController();
+			if (isTerminal(source)) return;
+			after(idle.clock, STDIN_IDLE_MS, idleWindow.signal, () => {
+				stop();
+				reject(idle.stalled());
+			});
+		};
+		const onData = (chunk) => {
+			chunks.push(chunk instanceof Uint8Array ? chunk : Buffer.from(String(chunk)));
+			watchIdle();
+		};
+		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);
+			idleWindow.abort();
+		};
+		if (signal.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+		watchIdle();
+		source.on("data", onData).once("end", onEnd).once("error", onError);
 	});
-	if (lines.length > 0) throw new Error([`Command '${label}' 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, label) {
-	const force = "force" in command ? command.force : void 0;
-	if (force === void 0) return;
-	if (!hasPlan(command)) throw new Error(`Command '${label}' declares force, which only a write or destructive Command may`);
-	if (force.trim() === "") throw new Error(`Command '${label}' declares an empty force; say what ${FORCE_FLAG.flag} replaces`);
 }
 //#endregion
-//#region ../agent-cli/dist/define-command.js
-/** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
-function checkCommand(command, label, table) {
-	checkNoStandardFlags(command, label);
-	checkForce(command, label);
-	checkArrayArgLast(label, command.args);
-	checkStdinFields(label, command.args, command.options);
-	checkNoBooleanArrayOption(label, command.options);
-	checkErrors(command, label, table);
-}
-function checkErrors(command, label, table) {
-	const unknown = (command.errors ?? []).filter((code) => !Object.hasOwn(table, code));
-	if (unknown.length > 0) throw new Error(`${label} declares ${unknown.join(", ")} in errors, a code the Error table lacks`);
-}
-function defineCommandFor() {
-	return declared;
+//#region ../agent-cli/dist/command-line/input.js
+function isWrapper(schema) {
+	return schema instanceof ZodOptional || schema instanceof ZodNullable || schema instanceof ZodDefault || schema instanceof ZodPrefault;
 }
-function declared(command) {
-	return command;
+function kebab(key) {
+	return key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
 }
-const defineCommand$1 = defineCommandFor();
-//#endregion
-//#region ../agent-cli/dist/context/project.js
-const PROJECT_INVALID = "PROJECT_INVALID";
-function invalid(path, problem, rerun, options) {
-	return new CliError({
-		code: PROJECT_INVALID,
-		message: `the Project file ${path} is invalid: ${problem}`,
-		hint: `fix ${path}, then run the Next step`,
-		next: [rerun]
-	}, options);
+function typeOf(schema) {
+	if (schema instanceof ZodNumber) return "number";
+	return schema instanceof ZodBoolean ? "boolean" : "string";
 }
-function readText(path, fileError) {
-	try {
-		return readFileSync(path, "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return void 0;
-		throw fileError(error, {
-			path,
-			access: "read"
-		});
+function describe(schema) {
+	let current = 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,
+		variadic,
+		stdin
+	};
 }
-function parsed(path, text, schema, rerun) {
-	let json;
-	try {
-		json = JSON.parse(text);
-	} catch (error) {
-		throw invalid(path, messageOf(error), rerun, { cause: error });
-	}
-	const result = schema.safeParse(json);
-	if (!result.success) throw invalid(path, prettifyError(result.error), rerun);
-	return result.data;
+function argLabel(key, { variadic, required, stdin }) {
+	if (stdin) return required ? `<${key}|->` : `[${key}|-]`;
+	if (!variadic) return `<${key}>`;
+	return required ? `<${key}...>` : `[${key}...]`;
 }
-function projectFrom(projectFile, folder, scope) {
-	const path = join(folder, projectFile.file);
-	const text = readText(path, scope.fileError);
-	if (text !== void 0) return {
-		root: folder,
-		settings: parsed(path, text, projectFile.schema, scope.rerun)
+function argField(key, schema) {
+	const described = describe(schema);
+	const label = argLabel(key, described);
+	return {
+		key,
+		name: key,
+		schema,
+		...described,
+		label,
+		usage: label
 	};
-	const parent = dirname(folder);
-	return parent === folder ? void 0 : projectFrom(projectFile, parent, scope);
 }
-/** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
-function projectOf(projectFile, cwd, scope) {
-	return projectFrom(projectFile, resolve(cwd), scope);
+function optionField(key, schema) {
+	const described = describe(schema);
+	const name = kebab(key);
+	const isBoolean = described.type === "boolean";
+	const label = isBoolean && described.defaultValue === true ? `--no-${name}` : `--${name}`;
+	const value = `<${described.choices?.join("|") ?? "value"}>${described.variadic ? "..." : ""}`;
+	const usage = isBoolean ? label : `${label} ${value}`;
+	return {
+		key,
+		name,
+		schema,
+		...described,
+		label,
+		usage
+	};
 }
-//#endregion
-//#region ../agent-cli/dist/define.js
-function isCommand(node) {
-	return typeof node.effect === "string";
+function fieldsOf(schema, toField) {
+	return schema === void 0 ? [] : Object.entries(schema.shape).map(([key, value]) => toField(key, value));
 }
-//#endregion
-//#region ../agent-cli/dist/context/declared.js
-/**
-* What the CLI declares itself (`own`) and every Command under `commands` declares, each name once,
-* for a `doctor` row: a Command requires only its own, but `doctor` checks them all.
-*/
-function declaredIn(own, commands, needsOf) {
-	const walk = (node) => isCommand(node) ? [...needsOf(node) ?? []] : Object.values(node).flatMap(walk);
-	return [...new Map([...own, ...walk(commands)].map((need) => [need.name, need])).values()];
+function argFields(schema) {
+	return fieldsOf(schema, argField);
 }
-//#endregion
-//#region ../agent-cli/dist/context/secrets.js
-const SECRET_MISSING = "SECRET_MISSING";
-/** `$XDG_CONFIG_HOME/<cli>/.env`, with `~/.config` when the variable is unset or empty. */
-function envFileOf(cliName, env) {
-	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
-	return join(config, cliName, ".env");
+function keysOf(fields) {
+	return fields.map(({ key }) => `'${key}'`).join(", ");
 }
-function readDotenv(path, fileError) {
-	let text;
-	try {
-		text = readFileSync(path, "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return {};
-		throw fileError(error, {
-			path,
-			access: "read"
-		});
+/** 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`);
 	}
-	return parseEnv(text);
 }
-/** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
-function secretOf({ envFile, env, fileError }, name) {
-	const fromEnv = env[name];
-	if (fromEnv) return {
-		value: fromEnv,
-		origin: { kind: "env" }
-	};
-	const fromFile = readDotenv(envFile, fileError)[name];
-	return fromFile ? {
-		value: fromFile,
-		origin: {
-			kind: "file",
-			path: envFile
-		}
-	} : void 0;
+function optionFields(schema) {
+	return fieldsOf(schema, optionField);
 }
-function missingIn(scope, secrets) {
-	return secrets.filter(({ name }) => secretOf(scope, name) === void 0);
+/** 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`);
 }
-function getItFrom({ get }) {
-	return `(get it from ${get})`;
+//#endregion
+//#region ../agent-cli/dist/command-line/usage.js
+const INVALID_INPUT = "INVALID_INPUT";
+const UNKNOWN_OPTION = "UNKNOWN_OPTION";
+const UNKNOWN_COMMAND = "UNKNOWN_COMMAND";
+function unknownError({ code, problem, commandLine, corrections, listed }) {
+	return new UsageError({
+		code,
+		message: `${problem} for \`${commandLine}\``,
+		hint: corrections.length === 0 ? `run \`${commandLine} --help\` to see the ${listed}` : `did you mean ${corrections.map((correction) => `\`${correction}\``).join(" or ")}?`
+	});
 }
-function whereToGet(secrets) {
-	return secrets.map((secret) => `${secret.name} ${getItFrom(secret)}`).join(", ");
+function unknownOptionError(commandLine, invocation, flag, suggestions) {
+	return unknownError({
+		code: UNKNOWN_OPTION,
+		problem: `unknown option '${flag}'`,
+		commandLine,
+		corrections: suggestions.map((name) => commandLineRenaming(invocation, /* @__PURE__ */ new Map([[flag, name]]))),
+		listed: "options"
+	});
 }
-/** Fails with `SECRET_MISSING`, naming every missing Secret at once, unless all are set. */
-function checkSecrets(secrets, scope, rerun) {
-	const missing = missingIn(scope, secrets);
-	if (missing.length === 0) return;
-	const names = missing.map(({ name }) => name).join(", ");
-	throw new CliError({
-		code: SECRET_MISSING,
-		message: `${missing.length === 1 ? "a Secret it needs is" : "Secrets it needs are"} not set: ${names}`,
-		hint: `set ${whereToGet(missing)} in the environment or in ${scope.envFile}, then run the Next step`,
-		next: [rerun]
+/** Text opening with `-` was read as an option, where the Command could have read it from stdin. */
+function stdinTextError(commandLine, invocation, word) {
+	const withStdin = commandLineOf(invocation, {
+		remove: [word],
+		add: ["-"]
+	});
+	return new UsageError({
+		code: UNKNOWN_OPTION,
+		message: `unknown option '${word}' for \`${commandLine}\``,
+		hint: `to pass text opening with \`-\`, pass \`-\` and send the text on stdin through a heredoc: \`${withStdin} <<'EOF'\`, then the text, then \`EOF\``
 	});
 }
-function originOf({ origin }) {
-	return origin.kind === "env" ? "the environment" : origin.path;
+function unknownCommandError(commandLine, name, suggestions) {
+	return unknownError({
+		code: UNKNOWN_COMMAND,
+		problem: `unknown command '${name}'`,
+		commandLine,
+		corrections: suggestions.map((suggestion) => `${commandLine} ${suggestion}`),
+		listed: "commands"
+	});
 }
-/** The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. */
-function secretRows(secrets, commands) {
-	const declared = declaredIn(secrets, commands, (command) => command.secrets);
-	if (declared.length === 0) return [];
-	return [{
-		name: "secrets",
-		run: ({ env, envFile, fileError }) => {
-			const read = declared.map((declaration) => ({
-				declaration,
-				secret: secretOf({
-					env,
-					envFile,
-					fileError
-				}, declaration.name)
-			}));
-			const missing = read.filter(({ secret }) => secret === void 0);
-			if (missing.length > 0) return {
-				state: "problem",
-				message: `${missing.map(({ declaration }) => `${declaration.name} is not set ${getItFrom(declaration)}`).join(", ")}; add ${missing.length === 1 ? "it" : "them"} to ${envFile} or the environment`
-			};
-			return {
-				state: "ok",
-				message: read.flatMap(({ declaration, secret }) => secret === void 0 ? [] : [`${declaration.name} from ${originOf(secret)}`]).join(", ")
-			};
-		}
-	}];
+function invalidInputError(commandLine, problem) {
+	return new UsageError({
+		code: INVALID_INPUT,
+		message: problem,
+		hint: `run \`${commandLine} --help\` to see the expected input`
+	});
 }
 //#endregion
-//#region ../agent-cli/dist/context/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;
+//#region ../agent-cli/dist/list.js
+const UNKNOWN_FIELD = "UNKNOWN_FIELD";
+const DEFAULT_PAGE_LIMIT = 20;
+const FIELDS_FLAG = "--fields";
+const SEPARATOR = ",";
+const COLUMN_SEPARATOR = "	";
+const UNSAFE_IN_COLUMN = /[\t\n\r]/;
+const PAGE_INPUT = object({
+	limit: number().int().positive().default(DEFAULT_PAGE_LIMIT),
+	cursor: string().min(1).optional()
+});
+var Page = class {
+	items;
+	nextCursor;
+	constructor(items, nextCursor) {
+		this.items = items;
+		this.nextCursor = nextCursor;
 	}
+};
+const PAGE_FLAG_DESCRIPTIONS = {
+	limit: `how many rows to show, a positive whole number (default: ${DEFAULT_PAGE_LIMIT})`,
+	cursor: "where to start, as given by the previous page's next"
+};
+function pageFlag(key) {
+	const field = optionField(key, PAGE_INPUT.shape[key]);
+	return {
+		flag: field.label,
+		usage: field.usage,
+		description: PAGE_FLAG_DESCRIPTIONS[key],
+		takes: "optional value",
+		schema: field.schema
+	};
 }
-/** 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, rerun) {
-	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 runtimeError({
-		code: TOOL_MISSING,
-		message: `${missing.length === 1 ? "a tool it runs is" : "tools it runs are"} not on PATH: ${names}`,
-		hint: "run the Next steps in order: each install, then the command again",
-		next: [...missing.map(({ install }) => wholeLine(install)), rerun]
-	});
-}
-/** One `doctor` row per distinct tool the CLI and its Commands declare, with its install command as the fix. */
-function toolRows(tools, commands) {
-	return declaredIn(tools, commands, (command) => command.tools).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/version.js
-/** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
-function buildStamp() {
+function fieldsFlag(rowFields) {
 	return {
-		"sha": "330940a",
-		"dirty": false,
-		"builtAt": "2026-10-28T15:25:01.000Z"
+		flag: FIELDS_FLAG,
+		usage: `${FIELDS_FLAG} <a,b>`,
+		description: `print only these comma-separated fields of each row (any of: ${rowFields.join(", ")})`,
+		takes: "optional value",
+		schema: string()
 	};
 }
-/** The first line of `--version`: the version, and the commit and time of a stamped build. */
-function versionLine({ version }) {
-	const build = buildStamp();
-	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
+const PAGE_FIELDS = optionFields(PAGE_INPUT);
+const PAGE_FLAGS = {
+	limit: pageFlag("limit"),
+	cursor: pageFlag("cursor")
+};
+/** The Standard flags every List Command gets, as the caller types them. */
+const LIST_FLAGS = [...Object.values(PAGE_FLAGS).map(({ flag }) => flag), FIELDS_FLAG];
+function listSpec(rows) {
+	const rowFields = Object.keys(rows.shape);
+	return {
+		rowFields,
+		pageFields: PAGE_FIELDS,
+		standardFlags: [...Object.values(PAGE_FLAGS), fieldsFlag(rowFields)],
+		output: object({
+			items: array(rows),
+			next: string().optional()
+		})
+	};
 }
-//#endregion
-//#region ../agent-cli/dist/tail.js
-/** The last `count` lines of a child's output, trimmed; empty when it wrote nothing. */
-function lastLines(output, count) {
-	return output.trim().split("\n").slice(-count).join("\n");
+function quoted(names) {
+	return names.map((name) => `'${name}'`).join(", ");
 }
-//#endregion
-//#region ../agent-cli/dist/context/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$/;
-const LINE_END = /\r\n|\r(?!$)|\n/;
-function isWhole(input) {
-	return typeof input === "string" || input instanceof Uint8Array;
+/** The fields the caller asked for, in their order, or undefined when they gave no `--fields`. */
+function selectedFields(values, rowFields, commandLine) {
+	const raw = values.get(FIELDS_FLAG);
+	if (raw === void 0) return;
+	const hint = `pass ${FIELDS_FLAG} with any of: ${rowFields.join(", ")}`;
+	const names = typeof raw === "string" ? raw.split(SEPARATOR).filter((name) => name !== "") : [];
+	if (names.length === 0) throw new UsageError({
+		code: INVALID_INPUT,
+		message: `${FIELDS_FLAG}: missing value for \`${commandLine}\``,
+		hint
+	});
+	const unknown = names.filter((name) => !rowFields.includes(name));
+	if (unknown.length > 0) throw new UsageError({
+		code: UNKNOWN_FIELD,
+		message: `unknown field ${quoted(unknown)} for \`${commandLine}\``,
+		hint
+	});
+	return names;
 }
-function escapedForCmd(text) {
-	return text.replace(CMD_META, "^$1");
+function fieldOf(row, field) {
+	return typeof row === "object" && row !== null ? row[field] : void 0;
 }
-function batchArgument(arg, shim) {
-	const escaped = escapedForCmd(`"${arg.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\*)$/, "$1$1")}"`);
-	return shim ? escapedForCmd(escaped) : escaped;
+function projected(rows, fields) {
+	return rows.map((row) => Object.fromEntries(fields.map((field) => [field, fieldOf(row, field)])));
 }
-function batchCommandLine(command, file, args) {
-	const shim = CMD_SHIM.test(file);
-	return [escapedForCmd(command), ...args.map((arg) => batchArgument(arg, shim))].join(" ");
+function cell(value) {
+	if (value === void 0 || value === null) return "";
+	return typeof value === "string" && !UNSAFE_IN_COLUMN.test(value) ? value : JSON.stringify(value);
 }
-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
+/** Selected rows as text: a header line of the field names, then one tab-separated line per row. */
+function renderRows(rows, fields) {
+	return `${[fields, ...rows.map((row) => fields.map((field) => cell(row[field])))].map((line) => line.join(COLUMN_SEPARATOR)).join("\n")}\n`;
+}
+function cursorWords(cursor) {
+	const { flag } = PAGE_FLAGS.cursor;
+	return cursor.startsWith("-") ? [`${flag}=${cursor}`] : [flag, cursor];
+}
+function printedPage(page, invocation) {
+	return page.nextCursor === void 0 ? { items: page.items } : {
+		items: page.items,
+		next: lineOf({
+			kind: "rerun",
+			words: changedArgv(invocation, {
+				remove: [PAGE_FLAGS.cursor.flag],
+				add: cursorWords(page.nextCursor)
+			}),
+			stdinArg: invocation.stdinArg
+		}, invocation.runAs)
 	};
 }
-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());
-	});
+/** The lines that end a rendered page, so the caller always knows whether and how to get more. */
+function pageFooter({ items, next }, style) {
+	return next === void 0 ? `${items.length} shown; no more pages\n` : `${items.length} shown; run the Next step for the next page\n${style.cyan("run:")} ${next}\n`;
 }
-/** Calls `onLine` with each complete line pushed, and with the unterminated rest at the end. */
-function lineSplitter(onLine) {
-	let rest = "";
+//#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/command-line/flags.js
+const HELP_FLAG = "--help";
+const VERSION_FLAG = "--version";
+const ROUTING_FLAGS = [
+	HELP_FLAG,
+	"-h",
+	VERSION_FLAG
+];
+function nameOf$1(flag) {
+	return flag.replace(/^--?/, "");
+}
+function standardFlag(flag, { placeholder, ...rest }) {
 	return {
-		push(text) {
-			if (onLine === void 0) return;
-			const lines = (rest + text).split(LINE_END);
-			rest = lines.pop() ?? "";
-			for (const line of lines) onLine(line);
-		},
-		end() {
-			if (rest !== "") onLine?.(rest.replace(TRAILING_CR, ""));
-			rest = "";
-		}
+		flag,
+		usage: placeholder === void 0 ? flag : `${flag} ${placeholder}`,
+		...rest
 	};
 }
-/** `onLine`, passing what it throws to `fail` and called no more once `failed()`. */
-function guarded(onLine, failed, fail) {
-	if (onLine === void 0) return void 0;
-	return (line) => {
-		if (failed()) return;
-		try {
-			onLine(line);
-		} catch (error) {
-			fail(error);
-		}
+const JSON_FLAG = standardFlag("--json", {
+	description: "print the result as JSON",
+	takes: "nothing",
+	schema: boolean()
+});
+const DRY_RUN_FLAG = standardFlag("--dry-run", {
+	description: "print the Plan without changing anything",
+	takes: "nothing",
+	schema: boolean()
+});
+const CONFIRM_FLAG = standardFlag("--confirm", {
+	placeholder: "<target>",
+	description: "name the target to confirm the change; an error hint gives the exact command",
+	takes: "value",
+	schema: string()
+});
+const YES_FLAG = standardFlag("--yes", {
+	description: "approve the cost the run states; --dry-run shows it",
+	takes: "nothing",
+	schema: boolean()
+});
+const FORCE_FLAG = standardFlag("--force", {
+	description: "replace a file the run writes that already exists; --dry-run lists every file it writes",
+	takes: "nothing",
+	schema: boolean()
+});
+const EFFECT_FLAGS = {
+	read: [JSON_FLAG],
+	act: [JSON_FLAG],
+	write: [JSON_FLAG, DRY_RUN_FLAG],
+	destructive: [
+		JSON_FLAG,
+		DRY_RUN_FLAG,
+		CONFIRM_FLAG
+	],
+	serve: [JSON_FLAG]
+};
+const RESERVED = new Map([
+	...ROUTING_FLAGS,
+	...EFFECT_FLAGS.destructive.map(({ flag }) => flag),
+	YES_FLAG.flag,
+	FORCE_FLAG.flag,
+	...LIST_FLAGS
+].map((flag) => [nameOf$1(flag), flag]));
+/** The Standard flags of a Command with this Effect and declarations, and of a List Command. */
+function standardFlagsFor(effect, { outputs, force, cost }, list) {
+	const forceFlag = force === void 0 ? FORCE_FLAG : {
+		...FORCE_FLAG,
+		description: force
 	};
+	return [
+		...EFFECT_FLAGS[effect],
+		...outputs || force !== void 0 ? [forceFlag] : [],
+		...cost ? [YES_FLAG] : [],
+		...list?.standardFlags ?? []
+	];
 }
-/** Settles once the child has taken what was written, or its stdin has closed. */
-function drained(stdin) {
-	return new Promise((resolve) => {
-		const done = () => {
-			stdin.off("drain", done);
-			stdin.off("close", done);
-			resolve();
-		};
-		stdin.on("drain", done);
-		stdin.on("close", done);
+/** Throws when the Command declares an arg or option under a Standard flag's name. */
+function checkNoStandardFlags(command, label) {
+	const lines = [...argFields(command.args).map(({ key }) => ({
+		kind: "arg",
+		key
+	})), ...optionFields(command.options).map(({ key }) => ({
+		kind: "option",
+		key
+	}))].flatMap(({ kind, key }) => {
+		const flag = RESERVED.get(kebab(key));
+		return flag === void 0 ? [] : [`  ${kind} '${key}' is the Standard flag ${flag}`];
 	});
+	if (lines.length > 0) throw new Error([`Command '${label}' declares Standard flags the Runtime adds; rename them:`, ...lines].join("\n"));
 }
-/**
-* Writes `input` to the child's stdin and ends it, stopping once the child is gone or the run
-* aborts.
-*/
-async function feed(stdin, input, signal) {
-	stdin.on("error", () => void 0);
-	const chunks = isWhole(input) ? [input] : input;
-	for await (const chunk of chunks) {
-		if (signal.aborted || stdin.destroyed) return;
-		if (!stdin.write(chunk)) await drained(stdin);
-	}
-	stdin.end();
+/** Throws when `force` is declared on a Command with no Plan, or says nothing. */
+function checkForce(command, label) {
+	const force = "force" in command ? command.force : void 0;
+	if (force === void 0) return;
+	if (!hasPlan(command)) throw new Error(`Command '${label}' declares force, which only a write or destructive Command may`);
+	if (force.trim() === "") throw new Error(`Command '${label}' declares an empty force; say what ${FORCE_FLAG.flag} replaces`);
 }
-/**
-* 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, stdin, detached = false }) {
-	signal.throwIfAborted();
-	const launch = await launchOf(command, args, env);
-	signal.throwIfAborted();
-	return new Promise((resolve, reject) => {
-		const child = spawn(launch.command, launch.args, {
-			cwd,
-			env,
-			shell: launch.shell,
-			windowsHide: true,
-			stdio: [
-				stdin === void 0 ? "ignore" : "pipe",
-				"pipe",
-				"pipe"
-			],
-			detached: detached && process.platform !== "win32"
-		});
-		let stopped = Promise.resolve();
-		const kill = () => {
-			stopped = stop(child);
-		};
-		signal.addEventListener("abort", kill, { once: true });
-		let callerFailure;
-		const fail = (error) => {
-			if (callerFailure !== void 0) return;
-			callerFailure = { error };
-			kill();
-		};
-		let stdout = "";
-		let stderr = "";
-		const lines = guarded(onLine, () => callerFailure !== void 0, fail);
-		const stdoutLines = lineSplitter(lines);
-		const stderrLines = lineSplitter(lines);
-		child.stdout?.setEncoding("utf8").on("data", (chunk) => {
-			stdout += chunk;
-			stdoutLines.push(chunk);
-		});
-		child.stderr?.setEncoding("utf8").on("data", (chunk) => {
-			stderr += chunk;
-			stderrLines.push(chunk);
-		});
-		if (stdin !== void 0 && child.stdin !== null) feed(child.stdin, stdin, signal).catch(fail);
-		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();
-			if (callerFailure !== void 0) {
-				const { error } = callerFailure;
-				stopped.then(() => reject(error));
-				return;
-			}
-			resolve({
-				stdout,
-				stderr,
-				exitCode: code ?? SIGNAL_EXIT_BASE + (killedBy === null ? 0 : constants$1.signals[killedBy])
-			});
-		});
-	});
+//#endregion
+//#region ../agent-cli/dist/define-command.js
+/** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
+function checkCommand(command, label, table) {
+	checkNoStandardFlags(command, label);
+	checkForce(command, label);
+	checkArrayArgLast(label, command.args);
+	checkStdinFields(label, command.args, command.options);
+	checkNoBooleanArrayOption(label, command.options);
+	checkErrors(command, label, table);
 }
-async function launchOf(command, args, env) {
-	return process.platform === "win32" ? windowsLaunch(command, args, env) : {
-		command,
-		args,
-		shell: false
-	};
+function checkErrors(command, label, table) {
+	const unknown = (command.errors ?? []).filter((code) => !Object.hasOwn(table, code));
+	if (unknown.length > 0) throw new Error(`${label} declares ${unknown.join(", ")} in errors, a code the Error table lacks`);
 }
-/**
-* Starts a child in its own process group (its own console on Windows) with no stdio, and settles
-* once it has started; the parent neither waits for it nor keeps it from exiting.
-*/
-const realSpawnDetached = async (command, args, { cwd, env }) => {
-	const launch = await launchOf(command, args, env);
-	return new Promise((resolve, reject) => {
-		const child = spawn(launch.command, launch.args, {
-			cwd,
-			env,
-			shell: launch.shell,
-			windowsHide: true,
-			stdio: "ignore",
-			detached: true
-		});
-		child.unref();
-		child.once("error", reject);
-		child.once("spawn", () => {
-			child.off("error", reject);
-			const { pid } = child;
-			if (pid === void 0) reject(/* @__PURE__ */ new Error(`${command} started without a pid`));
-			else resolve({ pid });
-		});
-	});
-};
-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 defineCommandFor() {
+	return declared;
+}
+function declared(command) {
+	return command;
 }
-function missingError(command, rerun, cause) {
+const defineCommand$1 = defineCommandFor();
+//#endregion
+//#region ../agent-cli/dist/context/project.js
+const PROJECT_INVALID = "PROJECT_INVALID";
+function invalid(path, problem, rerun, options) {
 	return new CliError({
-		code: TOOL_MISSING,
-		message: `${command} could not be started: it is not on PATH`,
-		hint: `install ${command}, then run the Next step`,
+		code: PROJECT_INVALID,
+		message: `the Project file ${path} is invalid: ${problem}`,
+		hint: `fix ${path}, then run the Next step`,
 		next: [rerun]
-	}, { cause });
+	}, options);
 }
-function startError(command, error, { fileError, rerun }) {
-	if (isMissingFile(error)) return missingError(command, rerun, error);
-	return fileError(error, {
-		path: command,
-		access: "read"
-	});
+function readText(path, fileError) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return void 0;
+		throw fileError(error, {
+			path,
+			access: "read"
+		});
+	}
+}
+function parsed(path, text, schema, rerun) {
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch (error) {
+		throw invalid(path, messageOf(error), rerun, { cause: error });
+	}
+	const result = schema.safeParse(json);
+	if (!result.success) throw invalid(path, prettifyError(result.error), rerun);
+	return result.data;
+}
+function projectFrom(projectFile, folder, scope) {
+	const path = join(folder, projectFile.file);
+	const text = readText(path, scope.fileError);
+	if (text !== void 0) return {
+		root: folder,
+		settings: parsed(path, text, projectFile.schema, scope.rerun)
+	};
+	const parent = dirname(folder);
+	return parent === folder ? void 0 : projectFrom(projectFile, parent, scope);
+}
+/** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
+function projectOf(projectFile, cwd, scope) {
+	return projectFrom(projectFile, resolve(cwd), scope);
 }
-async function* reported(stream, onError) {
+//#endregion
+//#region ../agent-cli/dist/context/secrets.js
+const SECRET_MISSING = "SECRET_MISSING";
+/** `$XDG_CONFIG_HOME/<cli>/.env`, with `~/.config` when the variable is unset or empty. */
+function envFileOf(cliName, env) {
+	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+	return join(config, cliName, ".env");
+}
+function readDotenv(path, fileError) {
+	let text;
 	try {
-		yield* stream;
+		text = readFileSync(path, "utf8");
 	} catch (error) {
-		onError(error);
-		throw error;
+		if (isMissingFile(error)) return {};
+		throw fileError(error, {
+			path,
+			access: "read"
+		});
 	}
+	return parseEnv(text);
 }
-/** `input`, a stream passing each error it throws to `onError` before the reader sees it. */
-function reporting(input, onError) {
-	return input === void 0 || isWhole(input) ? input : reported(input, onError);
-}
-/** `onLine`, passing each error it throws to `onError` before its caller sees it. */
-function reportingLines(onLine, onError) {
-	if (onLine === void 0) return void 0;
-	return (line) => {
-		try {
-			onLine(line);
-		} catch (error) {
-			onError(error);
-			throw error;
-		}
+/** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
+function secretOf({ envFile, env, fileError }, name) {
+	const fromEnv = env[name];
+	if (fromEnv) return {
+		value: fromEnv,
+		origin: { kind: "env" }
 	};
-}
-function contextSpawn(run, defaults, scope) {
-	return async (command, args = [], options = {}) => {
-		let callerFailure;
-		const caller = (error) => {
-			callerFailure = { error };
-		};
-		let result;
-		try {
-			result = await run(command, args, {
-				cwd: options.cwd ?? defaults.cwd,
-				env: options.env ?? defaults.env,
-				signal: defaults.signal,
-				onLine: reportingLines(options.onLine, caller),
-				stdin: reporting(options.stdin, caller)
-			});
-		} catch (error) {
-			throw callerFailure?.error === error ? error : startError(command, error, scope);
+	const fromFile = readDotenv(envFile, fileError)[name];
+	return fromFile ? {
+		value: fromFile,
+		origin: {
+			kind: "file",
+			path: envFile
 		}
-		if (options.check === true && result.exitCode !== 0) throw failedError(command, result);
-		return result;
-	};
+	} : void 0;
 }
-/** `ctx.spawnDetached`: `run` bound to the run's cwd and env, its start failures classified by errno. */
-function contextSpawnDetached(run, defaults, scope) {
-	return async (command, args = [], options = {}) => {
-		defaults.signal.throwIfAborted();
-		try {
-			return await run(command, args, {
-				cwd: options.cwd ?? defaults.cwd,
-				env: options.env ?? defaults.env
-			});
-		} catch (error) {
-			throw startError(command, error, scope);
+function missingIn(scope, secrets) {
+	return secrets.filter(({ name }) => secretOf(scope, name) === void 0);
+}
+function getItFrom({ get }) {
+	return `(get it from ${get})`;
+}
+function whereToGet(secrets) {
+	return secrets.map((secret) => `${secret.name} ${getItFrom(secret)}`).join(", ");
+}
+/** Fails with `SECRET_MISSING`, naming every missing Secret at once, unless all are set. */
+function checkSecrets(secrets, scope, rerun) {
+	const missing = missingIn(scope, secrets);
+	if (missing.length === 0) return;
+	const names = missing.map(({ name }) => name).join(", ");
+	throw new CliError({
+		code: SECRET_MISSING,
+		message: `${missing.length === 1 ? "a Secret it needs is" : "Secrets it needs are"} not set: ${names}`,
+		hint: `set ${whereToGet(missing)} in the environment or in ${scope.envFile}, then run the Next step`,
+		next: [rerun]
+	});
+}
+function originOf({ origin }) {
+	return origin.kind === "env" ? "the environment" : origin.path;
+}
+/** The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. */
+function secretRows(secrets, commands) {
+	const declared = declaredIn(secrets, commands, (command) => command.secrets);
+	if (declared.length === 0) return [];
+	return [{
+		name: "secrets",
+		run: ({ env, envFile, fileError }) => {
+			const read = declared.map((declaration) => ({
+				declaration,
+				secret: secretOf({
+					env,
+					envFile,
+					fileError
+				}, declaration.name)
+			}));
+			const missing = read.filter(({ secret }) => secret === void 0);
+			if (missing.length > 0) return {
+				state: "problem",
+				message: `${missing.map(({ declaration }) => `${declaration.name} is not set ${getItFrom(declaration)}`).join(", ")}; add ${missing.length === 1 ? "it" : "them"} to ${envFile} or the environment`
+			};
+			return {
+				state: "ok",
+				message: read.flatMap(({ declaration, secret }) => secret === void 0 ? [] : [`${declaration.name} from ${originOf(secret)}`]).join(", ")
+			};
 		}
+	}];
+}
+//#endregion
+//#region ../agent-cli/dist/version.js
+/** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
+function buildStamp() {
+	return {
+		"sha": "4664298",
+		"dirty": false,
+		"builtAt": "2026-11-02T04:03:08.000Z"
 	};
 }
+/** The first line of `--version`: the version, and the commit and time of a stamped build. */
+function versionLine({ version }) {
+	const build = buildStamp();
+	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
+}
+//#endregion
+//#region ../agent-cli/dist/context/agent.js
+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. Some Coding agents run commands
+* in a PTY, so a TTY alone doesn't mean a person is watching.
+*/
+function isAgent(env) {
+	return MARKERS.some((marker) => marker(env));
+}
 //#endregion
 //#region ../agent-cli/dist/built-ins/semver.js
 const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
@@ -7221,8 +7265,14 @@ function tail$1(stderr) {
 	const lines = lastLines(stderr, STDERR_TAIL_LINES);
 	return lines === "" ? "" : `\n${lines}`;
 }
+function authHint(code, ctx) {
+	const { label: registry, loginHint } = ctx.registry;
+	const login = `${loginHint}, then ${RUN_AGAIN}`;
+	if (code !== "E403" || !isAgent(ctx.env)) return login;
+	return `a Coding agent's sandbox may refuse ${registry} with a 403: ask your user to type ! and ${RUN_AGAIN}, or to allow ${registry} in the sandbox's network list; if it fails outside the sandbox too, ${login}`;
+}
 function failureOf(call, answer, ctx) {
-	const { label: registry, package: name, loginHint, unreachableHint } = ctx.registry;
+	const { label: registry, package: name, unreachableHint } = ctx.registry;
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
 	const next = [ctx.rerun];
@@ -7235,7 +7285,7 @@ function failureOf(call, answer, ctx) {
 	if (code !== void 0 && AUTH_CODES.has(code)) return new CliError({
 		code: REGISTRY_AUTH,
 		message: `${registry} refused npm's credentials (${code})${output}`,
-		hint: `${loginHint}, then ${RUN_AGAIN}`,
+		hint: authHint(code, ctx),
 		next
 	});
 	if (call === "view" && code === "E404") return noLatest(ctx, `npm found no ${name}@latest on ${registry}: no version of it is published there`);
@@ -7475,7 +7525,7 @@ function packagesOf(install) {
 function isUnchecked(standing) {
 	return standing.kind === "source" || standing.kind === "linked";
 }
-function skippedFor(cli, install, standing) {
+function skippedFor$1(cli, install, standing) {
 	return {
 		state: "skipped",
 		message: standing.kind === "source" ? `not checked: ${cli.name} runs from source, not from an install` : `not checked: ${install.package} links to ${standing.copy.realDir}, so the workspace decides its version`
@@ -7500,7 +7550,7 @@ function installFinding(cli, runAs, install, { cwd, root, standing }) {
 	const lines = root === void 0 ? void 0 : LINES[root.manager];
 	switch (standing.kind) {
 		case "source":
-		case "linked": return skippedFor(cli, install, standing);
+		case "linked": return skippedFor$1(cli, install, standing);
 		case "missing": return problem(`no package ${searchedFrom(cwd, root)} depends on ${install.package}`, lines?.add(packagesOf(install)));
 		case "listed": return problem(`${standing.manifest} lists ${install.package}, but no copy of it is installed at or above ${cwd}`, lines?.install);
 		case "unreadable": return problem(`${standing.manifest} is not a package.json with a version: ${standing.reason}`, lines?.install);
@@ -7546,7 +7596,7 @@ function checkOf$1(cli, install, runAs, { bin, node }) {
 		install: async (ctx) => installFinding(cli, runAs, install, await surveyed(ctx.cwd)),
 		release: async (ctx) => {
 			const { cwd, root, standing } = await surveyed(ctx.cwd);
-			if (isUnchecked(standing)) return { skipped: skippedFor(cli, install, standing) };
+			if (isUnchecked(standing)) return { skipped: skippedFor$1(cli, install, standing) };
 			return {
 				npm: npmContext(cli, registryOf(install, root?.dir), ctx, node, root?.dir ?? cwd),
 				advise: (latest) => adviceFor(install, root, latest)
@@ -7659,6 +7709,7 @@ function hubSkill(cli, from) {
 			run: async (ctx) => findingOf(await skillCopies(cli.name, cli.version, ctx))
 		}],
 		notice: async () => {},
+		differing: async (place) => (await skillCopies(cli.name, cli.version, place)).filter(({ state }) => state !== "current" && state !== "unreadable").map(describeCopy),
 		nextAt: async (version, ctx) => {
 			const copies = await skillCopies(cli.name, version, ctx);
 			const fix = fixFor(cli.name, copies, from);
@@ -7741,40 +7792,6 @@ function agentsRow(agents, install) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/context/agent.js
-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. Some Coding agents run commands
-* in a PTY, so a TTY alone doesn't mean a person is watching.
-*/
-function isAgent(env) {
-	return MARKERS.some((marker) => marker(env));
-}
-//#endregion
 //#region ../agent-cli/dist/context/errno.js
 const PERMISSION_DENIED = "PERMISSION_DENIED";
 const DISK_FULL = "DISK_FULL";
@@ -8295,6 +8312,15 @@ function packagedSkill(cli, { packaged: folder, agents: text }, install) {
 			run: (ctx) => findingOf(cli, folder, install, ctx)
 		}, ...agents === void 0 ? [] : [agentsRow(agents, install)]],
 		notice: (launch, ctx) => notice(cli, folder, install, launch, ctx),
+		differing: async ({ cwd, packageRoot }) => {
+			const { copy } = await skillCopyOf(cli, cwd);
+			const { copyVersion, packageVersion, same } = await skillVersionsOf(join(packageRoot, folder), copy);
+			return copyVersion === void 0 || same ? [] : [compared(cli.name, {
+				copy,
+				copyVersion,
+				packageVersion
+			}, false)];
+		},
 		nextAt: async (_version, ctx) => {
 			const { fix } = await findingOf(cli, folder, install, ctx);
 			return fix === void 0 ? [] : [fix];
@@ -8759,12 +8785,21 @@ function nodeRow(cli) {
 	};
 }
 /** A row's thrown error as its problem: a `CliError` with its hint and code, anything else a bug. */
-function problemOfError(name, error) {
-	if (error instanceof CliError) return {
-		state: "problem",
-		message: `${error.message}; ${error.hint}`,
-		code: error.code
-	};
+function problemOfError(name, error, runAs) {
+	if (error instanceof CliError) {
+		const message = `${error.message}; ${error.hint}`;
+		const fix = error.next.find((step) => !isRerun(step));
+		return fix === void 0 ? {
+			state: "problem",
+			message,
+			code: error.code
+		} : {
+			state: "problem",
+			message,
+			fix: lineOf(fix, runAs),
+			code: error.code
+		};
+	}
 	return {
 		state: "problem",
 		message: `the ${name} row hit a bug: ${messageOf(error)}`
@@ -8790,11 +8825,11 @@ function readProject(projectFile, ctx) {
 		};
 	}
 }
-function projectRow({ file }, read) {
+function projectRow({ file }, { read, runAs }) {
 	return {
 		name: "project",
 		run: (ctx) => {
-			if (!read.ok) return problemOfError("project", read.error);
+			if (!read.ok) return problemOfError("project", read.error, runAs);
 			return ok(read.project === void 0 ? `none found: no ${file} at or above ${ctx.cwd}` : join(read.project.root, file));
 		}
 	};
@@ -8834,20 +8869,24 @@ function registryRow(cli, check) {
 	};
 }
 /** Every row `doctor` reports, in order: the fixed rows around the CLI's own and its tools'. */
-function doctorChecks(cli, launch, read) {
+function doctorChecks(cli, launch, scope) {
 	const install = installOf(cli);
 	const check = install.check(launch);
-	return [
-		buildRow(cli),
-		nodeRow(cli),
-		...cli.project === void 0 ? [] : [projectRow(cli.project, read)],
-		...cli.doctor ?? [],
-		...toolRows(cli.tools ?? [], cli.commands),
-		...secretRows(cli.secrets ?? [], cli.commands),
-		installRow(check),
-		registryRow(cli, check),
-		...skillOf$1(cli, install).rows
-	];
+	const tools = toolRows(cli.tools ?? [], cli.commands);
+	return {
+		checks: [
+			buildRow(cli),
+			nodeRow(cli),
+			...cli.project === void 0 ? [] : [projectRow(cli.project, scope)],
+			...cli.doctor ?? [],
+			...tools,
+			...secretRows(cli.secrets ?? [], cli.commands),
+			installRow(check),
+			registryRow(cli, check),
+			...skillOf$1(cli, install).rows
+		],
+		tools: new Set(tools.map(({ name }) => name))
+	};
 }
 const DEFAULT_DEADLINE_MS = 1e4;
 const MS_PER_SECOND = 1e3;
@@ -8867,14 +8906,14 @@ const reportSchema = object({
 	})),
 	next: array(string())
 });
-function problemOf(check, error, { signal, deadline, ms }) {
+function problemOf(check, error, { signal, deadline, ms, runAs }) {
 	if (!signal.aborted && deadline.aborted && error === deadline.reason) return {
 		state: "problem",
 		message: `${check.name} did not answer within ${ms / MS_PER_SECOND} s`
 	};
-	return problemOfError(check.name, error);
+	return problemOfError(check.name, error, runAs);
 }
-function rowContext(ctx, signal, read) {
+function rowContext(ctx, signal, { read }) {
 	return Object.create(ctx, {
 		signal: { value: signal },
 		project: { get: () => {
@@ -8883,21 +8922,36 @@ function rowContext(ctx, signal, read) {
 		} }
 	});
 }
-async function rowOf(check, ctx, read) {
+function skippedFor(error, { read, tools }) {
+	if (!read.ok && error === read.error) return {
+		state: "skipped",
+		message: "the Project file is unusable; the project row says why"
+	};
+	const tool = missingToolOf(error);
+	if (tool !== void 0 && tools.has(tool)) return {
+		state: "skipped",
+		message: `${tool} is not on PATH; the ${tool} row says why`
+	};
+}
+async function rowOf(check, ctx, { read, runAs, tools }) {
 	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
 	const signal = ctx.deadline(ms);
 	let finding;
 	try {
-		finding = await Promise.race([Promise.resolve().then(() => check.run(rowContext(ctx, signal, read))), untilAborted(signal)]);
+		finding = await Promise.race([Promise.resolve().then(() => check.run(rowContext(ctx, signal, {
+			read,
+			runAs
+		}))), untilAborted(signal)]);
 	} catch (error) {
 		if (ctx.signal.aborted) return void 0;
-		finding = !read.ok && error === read.error ? {
-			state: "skipped",
-			message: "the Project file is unusable; the project row says why"
-		} : problemOf(check, error, {
+		finding = skippedFor(error, {
+			read,
+			tools
+		}) ?? problemOf(check, error, {
 			signal: ctx.signal,
 			deadline: signal,
-			ms
+			ms,
+			runAs
 		});
 	}
 	return {
@@ -8908,8 +8962,10 @@ async function rowOf(check, ctx, read) {
 		advisory: check.advisory === true
 	};
 }
-function nextOf(rows) {
-	return [...new Set(rows.flatMap(({ fix }) => fix === void 0 ? [] : [fix]))];
+function nextOf(checked, doctorLine) {
+	const fixes = checked.flatMap(({ row }) => row.fix === void 0 ? [] : [row.fix]);
+	const unfixed = checked.some(({ row, advisory }) => advisory && row.state === "problem" && row.fix === void 0);
+	return [...new Set(unfixed ? [...fixes, doctorLine] : fixes)];
 }
 function render({ rows, next }, style) {
 	const width = Math.max(MIN_LABEL_WIDTH, ...rows.map(({ check }) => check.length)) + 2;
@@ -8927,8 +8983,8 @@ function failure(cliName, rerun, problems) {
 		};
 		return runtimeError(fix === void 0 ? {
 			...head,
-			hint: "the row says what is wrong",
-			next: []
+			hint: "fix what the row says, then run the Next step",
+			next: [rerun]
 		} : {
 			...head,
 			hint: "run the Next steps in order",
@@ -8951,12 +9007,18 @@ function doctorCommand(cli, launch) {
 		effect: "read",
 		output: reportSchema,
 		run: async (_input, ctx) => {
-			const read = readProject(cli.project, ctx);
-			const checked = (await Promise.all(doctorChecks(cli, launch, read).map((check) => rowOf(check, ctx, read)))).filter((row) => row !== void 0);
-			const rows = checked.map(({ row }) => row);
+			const rowsScope = {
+				read: readProject(cli.project, ctx),
+				runAs: runAsOf(cli)
+			};
+			const { checks, tools } = doctorChecks(cli, launch, rowsScope);
+			const checked = (await Promise.all(checks.map((check) => rowOf(check, ctx, {
+				...rowsScope,
+				tools
+			})))).filter((row) => row !== void 0);
 			const report = {
-				rows,
-				next: nextOf(rows)
+				rows: checked.map(({ row }) => row),
+				next: nextOf(checked, lineOf(ctx.rerun(), rowsScope.runAs))
 			};
 			if (ctx.signal.aborted) {
 				ctx.deliver(report);
@@ -9226,18 +9288,26 @@ function installFrom(name, manifest, install) {
 		mode: "dependency",
 		package: manifest.name
 	};
-	if (install !== "global") return {
+	if (install === "global") return {
+		mode: "global",
+		package: manifest.name,
+		registry: publishedTo(name, manifest)
+	};
+	if (install.mode === "global") return {
+		mode: "global",
+		package: manifest.name,
+		registry: install.registry
+	};
+	return {
 		mode: "dependency",
 		package: manifest.name,
 		lockstep: install.lockstep
 	};
+}
+function publishedTo(name, manifest) {
 	const registry = manifest.publishConfig?.registry;
 	if (registry === void 0) throw new Error(`${name} declares a Global install, which needs publishConfig.registry in its package.json`);
-	return {
-		mode: "global",
-		package: manifest.name,
-		registry
-	};
+	return registry;
 }
 function resolved(cli) {
 	const { manifest, ...declared } = cli;
@@ -9302,6 +9372,30 @@ function startSideTask(sideTask, runWith, { clock, failed }) {
 	};
 }
 //#endregion
+//#region ../agent-cli/dist/built-ins/skill/usage-hint.js
+const SKILL_USAGE_CODES = /* @__PURE__ */ new Set([
+	UNKNOWN_OPTION,
+	UNKNOWN_COMMAND,
+	INVALID_INPUT
+]);
+/** A usage error whose hint names each Skill copy that differs from this build, since one may have named the input. */
+async function withDifferingSkill(error, cli, place, runAs) {
+	if (!(error instanceof UsageError) || !SKILL_USAGE_CODES.has(error.code)) return error;
+	let differing;
+	try {
+		differing = await skillOf$1(cli, installOf(cli)).differing(place);
+	} catch (lookup) {
+		if (errnoOf(lookup) === void 0) throw lookup;
+		return error;
+	}
+	if (differing.length === 0) return error;
+	return new UsageError({
+		code: error.code,
+		message: error.message,
+		hint: `${error.hint}; the ${cli.name} skill may name what this build does not know: ${differing.join("; ")}; run \`${runAs} doctor\` to see how to update it`
+	});
+}
+//#endregion
 //#region ../agent-cli/dist/command-line/suggest.js
 const MAX_DISTANCE = 3;
 const MIN_SIMILARITY = .4;
@@ -11012,7 +11106,11 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			});
 		});
 	} catch (error) {
-		return failed(error, noSideTask);
+		return failed(await withDifferingSkill(error, cli, {
+			cwd,
+			env,
+			packageRoot
+		}, invocation.runAs), noSideTask);
 	}
 	const { input, flags } = parsed;
 	resumed = command.deadline?.resume(input, rerunOf);
@@ -11224,10 +11322,16 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 			...format,
 			json: routed.json
 		}));
-		case "usage error": return ranAlone(errorResult(routed.error, {
-			...misused(routed.node),
-			json: routed.json
-		}));
+		case "usage error": {
+			const place = {
+				...options,
+				packageRoot: packageRootOf(options.bin, options.cwd)
+			};
+			return ranAlone(errorResult(await withDifferingSkill(routed.error, cli, place, runAs), {
+				...misused(routed.node),
+				json: routed.json
+			}));
+		}
 		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(cli, routed, options, write, misused(routed.spec)));
 	}
 }
@@ -11290,7 +11394,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.20.0",
+	version: "0.22.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },