@duyquangnvx/create-agent-cli 0.2.1 → 0.3.0

package/dist/bin.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
-import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+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 { spawn } from "node:child_process";
-import { homedir, tmpdir } from "node:os";
-import { parseArgs } from "node:util";
+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 { fileURLToPath } from "node:url";
 //#region ../../node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/core/util.js
 function getEnumValues(entries) {
@@ -761,6 +762,59 @@ function formatError(error, mapper = (issue) => issue.message) {
 	processError(error);
 	return fieldErrors;
 }
+/** Format a ZodError as a human-readable string in the following form.
+*
+* From
+*
+* ```ts
+* ZodError {
+*   issues: [
+*     {
+*       expected: 'string',
+*       code: 'invalid_type',
+*       path: [ 'username' ],
+*       message: 'Invalid input: expected string'
+*     },
+*     {
+*       expected: 'number',
+*       code: 'invalid_type',
+*       path: [ 'favoriteNumbers', 1 ],
+*       message: 'Invalid input: expected number'
+*     }
+*   ];
+* }
+* ```
+*
+* to
+*
+* ```
+* username
+*   ✖ Expected number, received string at "username
+* favoriteNumbers[0]
+*   ✖ Invalid input: expected number
+* ```
+*/
+function toDotPath(_path) {
+	const segs = [];
+	const path = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+	for (const seg of path) if (typeof seg === "number") segs.push(`[${seg}]`);
+	else if (typeof seg === "symbol") segs.push(`[${JSON.stringify(String(seg))}]`);
+	else if (/[^\w$]/.test(seg)) segs.push(`[${JSON.stringify(seg)}]`);
+	else {
+		if (segs.length) segs.push(".");
+		segs.push(seg);
+	}
+	return segs.join("");
+}
+function prettifyError(error) {
+	const lines = [];
+	const issues = [...error.issues].sort((a, b) => (a.path ?? []).length - (b.path ?? []).length);
+	for (const issue of issues) {
+		lines.push(`✖ ${issue.message}`);
+		if (issue.path?.length) lines.push(`  → at ${toDotPath(issue.path)}`);
+	}
+	return lines.join("\n");
+}
 //#endregion
 //#region ../../node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/core/parse.js
 function finalizeParams(callee, params) {
@@ -5515,6 +5569,18 @@ function superRefine(fn, params) {
 	return /* @__PURE__ */ _superRefine(fn, params);
 }
 //#endregion
+//#region ../agent-cli/dist/abort.js
+/** Never resolves; rejects with the signal's reason once it aborts. */
+function untilAborted(signal) {
+	return new Promise((_resolve, reject) => {
+		if (signal.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+	});
+}
+//#endregion
 //#region ../agent-cli/dist/input.js
 function isWrapper(schema) {
 	return schema instanceof ZodOptional || schema instanceof ZodNullable || schema instanceof ZodDefault || schema instanceof ZodPrefault;
@@ -5571,42 +5637,44 @@ function optionField(key, schema) {
 		usage
 	};
 }
-function fieldsOf(schema, toField) {
+function fieldsOf$1(schema, toField) {
 	return schema === void 0 ? [] : Object.entries(schema.shape).map(([key, value]) => toField(key, value));
 }
 function argFields(schema) {
-	return fieldsOf(schema, argField);
+	return fieldsOf$1(schema, argField);
 }
 function optionFields(schema) {
-	return fieldsOf(schema, optionField);
+	return fieldsOf$1(schema, optionField);
 }
 //#endregion
 //#region ../agent-cli/dist/errors.js
 var CliError = class extends Error {
 	code;
 	hint;
-	retryable;
-	constructor({ code, message, hint, retryable }, options) {
+	details;
+	retryAt;
+	constructor({ code, message, hint, details, retryAt }, options) {
 		super(message, options);
 		this.name = "CliError";
 		this.code = code;
 		this.hint = hint;
-		this.retryable = retryable;
+		this.details = details;
+		this.retryAt = retryAt;
 	}
 };
-/** The caller called the Agent CLI wrong; retrying the same call can't succeed. */
+/** The caller called the Agent CLI wrong; the same call can't succeed. */
 var UsageError = class extends CliError {
-	constructor(details) {
-		super({
-			...details,
-			retryable: false
-		});
+	constructor(fields) {
+		super(fields);
 		this.name = "UsageError";
 	}
 };
 const INTERNAL_CODE = "INTERNAL";
+function errnoOf(error) {
+	return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
+}
 function isMissingFile(error) {
-	return error instanceof Error && "code" in error && error.code === "ENOENT";
+	return errnoOf(error) === "ENOENT";
 }
 function debugVariable(cliName) {
 	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
@@ -5617,47 +5685,61 @@ function messageOf(error) {
 function isDebug({ env, cliName }) {
 	return Boolean(env[debugVariable(cliName)]);
 }
-function detailsOf(error, format) {
+function bugHint(format) {
+	return isDebug(format) ? "the stack trace shows where it failed" : `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`;
+}
+function fieldsOf(error, format) {
 	if (error instanceof CliError) {
-		const { code, message, hint, retryable } = error;
+		const { code, message, hint, details, retryAt } = error;
 		return {
 			code,
 			message,
-			hint,
-			retryable
+			hint: format.isBug(error) ? bugHint(format) : hint,
+			details,
+			retryAt
 		};
 	}
 	return {
 		code: INTERNAL_CODE,
 		message: messageOf(error),
-		hint: isDebug(format) ? "the stack trace shows where it failed" : `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`,
-		retryable: false
+		hint: bugHint(format)
 	};
 }
-function stackOf(error, format) {
-	return isDebug(format) && !(error instanceof CliError) && error instanceof Error ? error.stack : void 0;
+function causesOf(error) {
+	return error instanceof Error && error.cause !== void 0 ? [error.cause, ...causesOf(error.cause)] : [];
 }
-function formatRuntimeError(error, format) {
-	const details = detailsOf(error, format);
-	const stack = stackOf(error, format);
-	if (format.json) return `${JSON.stringify({
-		...details,
-		stack
-	})}\n`;
+function traceOf(error) {
+	return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+/** Under debug: a bug's stack trace, then every error's cause chain. */
+function debugTrace(error, format) {
+	if (!isDebug(format)) return void 0;
+	const lines = [...format.isBug(error) ? [traceOf(error)] : [], ...causesOf(error).map((cause) => `caused by: ${traceOf(cause)}`)];
+	return lines.length === 0 ? void 0 : lines.join("\n");
+}
+/** The errors a run failed with: each one an `AggregateError` holds, or the one it threw. */
+function errorsOf(error) {
+	return error instanceof AggregateError && error.errors.length > 0 ? error.errors : [error];
+}
+function errorLines(error, format) {
+	const fields = fieldsOf(error, format);
+	const stack = debugTrace(error, format);
 	const { style } = format;
-	const label = style.red(error instanceof CliError ? "error:" : "internal error:");
+	const label = style.red(format.isBug(error) ? "internal error:" : "error:");
 	const trace = stack === void 0 ? "" : `${stack}\n`;
-	return `${label} ${details.message}\n${trace}${style.cyan("hint:")} ${details.hint}\n`;
+	return `${label} ${fields.message}\n${trace}${style.cyan("hint:")} ${fields.hint}\n`;
 }
-/** A failure that still prints the Command's data on stdout, as `doctor` does with its rows. */
-var FailureWithData = class extends CliError {
-	data;
-	constructor(details, data) {
-		super(details);
-		this.name = "FailureWithData";
-		this.data = data;
+function formatRuntimeError(error, format) {
+	const errors = errorsOf(error);
+	if (format.json) {
+		const printed = errors.map((each) => ({
+			...fieldsOf(each, format),
+			stack: debugTrace(each, format)
+		}));
+		return `${JSON.stringify({ errors: printed })}\n`;
 	}
-};
+	return errors.map((each) => errorLines(each, format)).join("");
+}
 const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
 function quoted$1(token) {
 	return SHELL_SAFE.test(token) ? token : `'${token.replaceAll("'", `'\\''`)}'`;
@@ -5665,6 +5747,10 @@ 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 ? {
@@ -5678,13 +5764,16 @@ function split(argv) {
 function without(flag, tokens) {
 	return tokens.filter((token, index) => token !== flag && !token.startsWith(`${flag}=`) && tokens[index - 1] !== flag);
 }
-/** The caller's command line, ready to paste, with `flag value` replacing any value they gave. */
+/**
+* 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.
+*/
 function commandLineWith({ cliName, argv }, flag, value) {
 	const { options, operands } = split(argv);
+	const added = value === void 0 ? [flag] : [flag, value];
 	return pasteable(cliName, [
 		...without(flag, options),
-		flag,
-		value,
+		...added,
 		...operands
 	]);
 }
@@ -5700,7 +5789,45 @@ function commandLineRenaming({ cliName, argv }, renames) {
 	return pasteable(cliName, [...options.map((token) => renamed(token, renames)), ...operands]);
 }
 //#endregion
+//#region ../agent-cli/dist/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 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"
+	});
+}
+function unknownCommandError(commandLine, name, suggestions) {
+	return unknownError({
+		code: UNKNOWN_COMMAND,
+		problem: `unknown command '${name}'`,
+		commandLine,
+		corrections: suggestions.map((suggestion) => `${commandLine} ${suggestion}`),
+		listed: "commands"
+	});
+}
+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 = ",";
@@ -5770,13 +5897,13 @@ function selectedFields(values, rowFields, commandLine) {
 	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",
+		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",
+		code: UNKNOWN_FIELD,
 		message: `unknown field ${quoted(unknown)} for \`${commandLine}\``,
 		hint
 	});
@@ -5842,6 +5969,16 @@ const CONFIRM_FLAG = standardFlag("--confirm", {
 	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 the files the run writes when they exist; --dry-run lists them",
+	takes: "nothing",
+	schema: boolean()
+});
 const EFFECT_FLAGS = {
 	read: [JSON_FLAG],
 	write: [JSON_FLAG, DRY_RUN_FLAG],
@@ -5849,16 +5986,24 @@ const EFFECT_FLAGS = {
 		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(flag), flag]));
-/** The Standard flags of a Command with this Effect, and of a List Command. */
-function standardFlagsFor(effect, list) {
-	return [...EFFECT_FLAGS[effect], ...list?.standardFlags ?? []];
+/** The Standard flags of a Command with this Effect and declarations, and of a List Command. */
+function standardFlagsFor(effect, { outputs, cost }, list) {
+	return [
+		...EFFECT_FLAGS[effect],
+		...outputs ? [FORCE_FLAG] : [],
+		...cost ? [YES_FLAG] : [],
+		...list?.standardFlags ?? []
+	];
 }
 /** Throws when the Command declares an arg or option under a Standard flag's name. */
 function checkNoStandardFlags(command) {
@@ -5876,10 +6021,14 @@ function checkNoStandardFlags(command) {
 }
 //#endregion
 //#region ../agent-cli/dist/define.js
-function defineCommand(command) {
+function checkedCommand(command) {
 	checkNoStandardFlags(command);
 	return command;
 }
+function defineCommandFor() {
+	return checkedCommand;
+}
+const defineCommand$1 = defineCommandFor();
 function isCommand(node) {
 	return typeof node.effect === "string";
 }
@@ -5945,7 +6094,18 @@ function meetsMinimum(version, minimum) {
 	return true;
 }
 //#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");
+}
+//#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) {
 	return {
 		cliName: cli.name,
@@ -5955,6 +6115,7 @@ function npmContext(cli, install, ctx) {
 	};
 }
 const NPMJS = "https://registry.npmjs.org/";
+const STDERR_TAIL_LINES$1 = 10;
 const RM_RETRIES = 3;
 const NETWORK_CODES = /* @__PURE__ */ new Set([
 	"ENOTFOUND",
@@ -5986,7 +6147,7 @@ function installCommandLine(install, version = "latest") {
 }
 function spawnNpm(args, ctx, signal) {
 	const windows = process.platform === "win32";
-	const command = windows ? ["npm", ...args].map((arg) => `"${arg.replaceAll("\"", "\"\"")}"`).join(" ") : "npm";
+	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,
@@ -6017,45 +6178,40 @@ function spawnNpm(args, ctx, signal) {
 	});
 }
 function tail$1(stderr) {
-	const lines = stderr.trim().split("\n").slice(-10);
-	return lines.length === 0 || lines[0] === "" ? "" : `\n${lines.join("\n")}`;
+	const lines = lastLines(stderr, STDERR_TAIL_LINES$1);
+	return lines === "" ? "" : `\n${lines}`;
 }
 function failureOf(call, answer, ctx) {
 	const { registry, package: name } = ctx.install;
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
 	if (code !== void 0 && NETWORK_CODES.has(code)) return new CliError({
-		code: "REGISTRY_UNREACHABLE",
+		code: REGISTRY_UNREACHABLE,
 		message: `npm could not reach ${registry} (${code})${output}`,
-		hint: "check the network or VPN, then run it again",
-		retryable: true
+		hint: "check the network or VPN, then run it again"
 	});
 	if (code !== void 0 && AUTH_CODES.has(code)) return new CliError({
-		code: "REGISTRY_AUTH",
+		code: REGISTRY_AUTH,
 		message: `${registry} refused npm's credentials (${code})${output}`,
-		hint: `log in to ${registry} (npm login --registry=${registry}) or set its token in ~/.npmrc, then run it again`,
-		retryable: false
+		hint: `log in to ${registry} (npm login --registry=${registry}) or set its token in ~/.npmrc, then run it again`
 	});
 	if (call === "view" && code === "E404") return noLatest(ctx, `npm found no ${name}@latest on ${registry}: no version of it is published there`);
 	if (call === "install") return new CliError({
-		code: "INSTALL_FAILED",
+		code: INSTALL_FAILED,
 		message: `npm could not install ${name}${code === void 0 ? "" : ` (${code})`}${output}`,
-		hint: `fix what npm reports, then run it again, or install it yourself: ${installCommandLine(ctx.install)}`,
-		retryable: false
+		hint: `fix what npm reports, then run it again, or install it yourself: ${installCommandLine(ctx.install)}`
 	});
 	return new CliError({
-		code: "NPM_FAILED",
+		code: NPM_FAILED,
 		message: `npm ${call} failed with exit code ${answer.exitCode}${output}`,
-		hint: "fix what npm reports, then run it again",
-		retryable: false
+		hint: "fix what npm reports, then run it again"
 	});
 }
 function noLatest(ctx, message) {
 	return new CliError({
-		code: "NO_LATEST",
+		code: NO_LATEST,
 		message,
-		hint: `check that ${ctx.install.package} is published on ${ctx.install.registry}`,
-		retryable: false
+		hint: `check that ${ctx.install.package} is published on ${ctx.install.registry}`
 	});
 }
 /**
@@ -6072,10 +6228,9 @@ async function runNpm(call, args, ctx, signal = ctx.signal) {
 		], ctx, signal).catch((error) => {
 			if (signal?.aborted === true) throw signal.reason;
 			throw new CliError({
-				code: "NPM_FAILED",
+				code: NPM_FAILED,
 				message: `npm could not be started: ${messageOf(error)}`,
-				hint: "install Node with npm, or put npm on PATH",
-				retryable: false
+				hint: "install Node with npm, or put npm on PATH"
 			}, { cause: error });
 		});
 		if (answer.exitCode !== 0) throw failureOf(call, answer, ctx);
@@ -6126,16 +6281,16 @@ async function latestVersion(ctx) {
 }
 //#endregion
 //#region ../agent-cli/dist/global-install.js
+const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
 /** Where npm puts global packages under its global prefix. */
 function globalModulesDir(prefix) {
 	return process.platform === "win32" ? join(prefix, "node_modules") : join(prefix, "lib", "node_modules");
 }
 function notGlobal(ctx, message) {
 	return new CliError({
-		code: "NOT_GLOBAL_INSTALL",
+		code: NOT_GLOBAL_INSTALL,
 		message,
-		hint: `install it with npm, so \`${ctx.cliName} update\` can replace it: ${installCommandLine(ctx.install)}`,
-		retryable: false
+		hint: `install it with npm, so \`${ctx.cliName} update\` can replace it: ${installCommandLine(ctx.install)}`
 	});
 }
 async function realpathOrUndefined(path) {
@@ -6166,131 +6321,941 @@ async function globalInstallOf(bin, ctx) {
 	};
 }
 //#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}`;
+//#region ../agent-cli/dist/confirm.js
+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)}\``;
+	if (given === void 0) throw new UsageError({
+		code: CONFIRMATION_REQUIRED,
+		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
+		hint
+	});
+	throw new UsageError({
+		code: CONFIRMATION_MISMATCH,
+		message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
+		hint
+	});
 }
-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. */
-function skillVersionIn(skill) {
-	const frontmatter = FRONTMATTER.exec(skill)?.[1];
-	return frontmatter === void 0 ? void 0 : METADATA_VERSION.exec(`${frontmatter}\n`)?.[1];
+//#endregion
+//#region ../agent-cli/dist/cost.js
+const NOT_CONFIRMED = "NOT_CONFIRMED";
+/** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
+function checkCost({ invocation, commandLine, yes }, cost) {
+	if (cost === void 0 || yes) return;
+	throw new CliError({
+		code: NOT_CONFIRMED,
+		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
+		hint: `to approve the cost, run \`${commandLineWith(invocation, YES_FLAG.flag)}\``
+	});
 }
-function homeOf(env) {
-	return env.HOME ?? env.USERPROFILE ?? homedir();
+//#endregion
+//#region ../agent-cli/dist/agent.js
+const AGENT_VARIABLES = [
+	"CLAUDECODE",
+	"CODEX_CI",
+	"CODEX_SANDBOX",
+	"GEMINI_CLI",
+	"CURSOR_AGENT",
+	"CI"
+];
+/** Whether a Coding agent, not a person, is running the Agent CLI. */
+function isAgent(env) {
+	return AGENT_VARIABLES.some((name) => env[name] !== void 0);
 }
-async function copyAt(path, cliVersion) {
-	let skill;
-	try {
-		skill = await readFile(join(path, "SKILL.md"), "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return;
-		return {
-			path,
-			version: void 0,
-			state: "unreadable"
-		};
+//#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`;
+}
+/** 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({
+			code: PERMISSION_DENIED,
+			message: `permission denied: ${path}`,
+			hint: permissionHint(context)
+		}, { cause: error });
+		case "ENOSPC": 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({
+			code: NOT_FOUND,
+			message: `not found: ${path}`,
+			hint: `check that ${path} and its folder exist`
+		}, { cause: error });
+		default: return error;
 	}
-	const version = skillVersionIn(skill);
-	if (version === void 0 || !isVersion(version) || !isVersion(cliVersion)) return {
-		path,
-		version,
-		state: "unversioned"
-	};
-	return {
-		path,
-		version,
-		state: standingOf(version, cliVersion)
-	};
 }
-/** Every installed copy of the skill named after the CLI, in the project first, then under home. */
-async function skillCopies(skillName, cliVersion, cwd, env) {
-	const paths = [cwd, homeOf(env)].flatMap((root) => SKILL_DIRS.map((dir) => join(root, ...dir, skillName)));
-	const seen = /* @__PURE__ */ new Set();
-	const copies = [];
-	for (const path of paths) {
-		const copy = await copyAt(path, cliVersion);
-		const real = copy === void 0 ? void 0 : await realpath(path);
-		if (copy !== void 0 && real !== void 0 && !seen.has(real)) {
-			seen.add(real);
-			copies.push(copy);
+//#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);
 	}
-	return copies;
 }
 //#endregion
-//#region ../agent-cli/dist/doctor-rows.js
-function ok(message) {
-	return {
-		state: "ok",
-		message
-	};
-}
-function nodeRow(cli) {
-	return {
-		name: "node",
-		run: () => {
-			const found = process.versions.node;
-			const range = cli.engines?.node;
-			if (range === void 0) return ok(`Node ${found}; ${cli.name} declares no engines.node to check it against`);
-			const minimum = engineMinimum(range);
-			if (minimum === void 0) return {
-				state: "problem",
-				message: `${cli.name} declares engines.node "${range}", which doctor cannot read: only >=X.Y.Z is supported`
-			};
-			if (meetsMinimum(found, minimum)) return ok(`Node ${found} meets ${range}`);
-			const major = minimum[0];
-			return {
-				state: "problem",
-				message: `${cli.name} runs on Node ${found}, older than the ${range} it needs; install Node ${minimum.join(".")} or newer and make it the default`,
-				fix: `nvm install ${major} && nvm alias default ${major}`
-			};
-		}
-	};
+//#region ../agent-cli/dist/interrupts.js
+const INTERRUPTED = "INTERRUPTED";
+const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
+/** How long an interrupted Command may take to settle before the run ends without it. */
+const GRACE_MS = 3e3;
+const GRACE_OVER = Symbol("grace over");
+function interruptedError() {
+	return new CliError({
+		code: INTERRUPTED,
+		message: "interrupted before it finished",
+		hint: "run the command again"
+	});
 }
-function installRow(cli, bin) {
-	return {
-		name: "install",
-		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}`);
-			} catch (error) {
-				if (error instanceof CliError && error.code === "NOT_GLOBAL_INSTALL") return {
-					state: "problem",
-					message: error.message,
-					fix: installCommandLine(install)
-				};
-				throw error;
-			}
-		}
-	};
+const WAIT_HINT = "run it again later, when the service it waits on may answer faster";
+function deadlineError(commandLine, ms, hint) {
+	return new CliError({
+		code: DEADLINE_EXCEEDED,
+		message: `${commandLine} ran past its ${ms} ms deadline`,
+		hint
+	});
 }
-function registryRow(cli) {
-	return {
-		name: "registry",
-		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 standing = standingOf(cli.version, latest);
-			const head = `${install.registry} has ${latest} as latest: this build`;
-			if (standing === "behind") return {
-				state: "problem",
-				message: `${head} (${cli.version}) is older`,
-				fix: `${cli.name} update`
-			};
-			return ok(`${head} is ${standing === "current" ? "current" : `newer (${cli.version})`}`);
+/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
+var RunControl = class {
+	signal;
+	#controller = new AbortController();
+	#commandLine;
+	#outer;
+	#onOuterAbort = () => this.#controller.abort(interruptedError());
+	/** Each running must-finish step, tracked until it settles, with its name. */
+	#steps = /* @__PURE__ */ new Map();
+	#progress;
+	#clock;
+	#disposed = new AbortController();
+	#deadlineHit;
+	#graceCancel = new AbortController();
+	#endGrace = () => {};
+	#graceOver = new Promise((resolve) => {
+		this.#endGrace = resolve;
+	});
+	constructor({ commandLine, outer, clock, progress, runDeadline }) {
+		this.#commandLine = commandLine;
+		this.#outer = outer;
+		this.#clock = clock;
+		this.#progress = progress;
+		this.signal = this.#controller.signal;
+		this.signal.addEventListener("abort", () => this.#onStop(), { once: true });
+		if (outer?.aborted === true) this.#onOuterAbort();
+		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)));
 		}
-	};
-}
-const SKILL_STATE_NOTES = {
-	current: "the same as this build",
-	behind: "older than this build",
+	}
+	deadline(ms) {
+		const controller = new AbortController();
+		after(this.#clock, ms, this.#disposed.signal, () => {
+			this.#deadlineHit ??= deadlineError(this.#commandLine, ms, WAIT_HINT);
+			controller.abort(this.#deadlineHit);
+		});
+		return AbortSignal.any([this.signal, controller.signal]);
+	}
+	async runToEnd(name, work) {
+		this.#graceCancel.abort();
+		if (this.signal.aborted) this.#finishing(name);
+		const step = work();
+		const settled = step.then(() => {}, () => {});
+		this.#steps.set(settled, name);
+		try {
+			return await step;
+		} finally {
+			this.#steps.delete(settled);
+			this.#startGrace();
+		}
+	}
+	/** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
+	async settle(work) {
+		try {
+			const value = await Promise.race([work, this.#graceOver]);
+			if (this.signal.aborted || value === GRACE_OVER) throw this.signal.reason;
+			return value;
+		} finally {
+			await this.#stepsDone();
+			this.#dispose();
+		}
+	}
+	/**
+	* The error a run ends with: an interrupt or a missed deadline outranks what the Command threw,
+	* unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
+	*/
+	errorAfter(error) {
+		if (this.signal.aborted) return error instanceof CliError && error.code === "INTERRUPTED" ? error : this.signal.reason;
+		if (this.#deadlineHit !== void 0 && !(error instanceof CliError)) return this.#deadlineHit;
+		return error;
+	}
+	#onStop() {
+		for (const name of this.#steps.values()) this.#finishing(name);
+		this.#startGrace();
+	}
+	#finishing(name) {
+		this.#progress(`finishing ${name}`);
+	}
+	#startGrace() {
+		if (this.signal.aborted && this.#steps.size === 0) {
+			this.#graceCancel.abort();
+			this.#graceCancel = new AbortController();
+			after(this.#clock, GRACE_MS, this.#graceCancel.signal, () => this.#endGrace(GRACE_OVER));
+		}
+	}
+	async #stepsDone() {
+		while (this.#steps.size > 0) await Promise.all(this.#steps.keys());
+	}
+	#dispose() {
+		this.#graceCancel.abort();
+		this.#disposed.abort();
+		this.#outer?.removeEventListener("abort", this.#onOuterAbort);
+	}
+};
+//#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`. */
+async function checkOutputs({ invocation, commandLine, force, files }, outputs) {
+	if (outputs === void 0 || force) return;
+	const found = await Promise.all(outputs.map((path) => files.exists(path)));
+	const existing = outputs.filter((_path, index) => found[index]);
+	if (existing.length === 0) return;
+	const them = existing.length === 1 ? "it" : "them";
+	throw new CliError({
+		code: OUTPUT_EXISTS,
+		message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
+		hint: `to replace ${them}, run \`${commandLineWith(invocation, FORCE_FLAG.flag)}\``
+	});
+}
+//#endregion
+//#region ../agent-cli/dist/project.js
+const PROJECT_INVALID = "PROJECT_INVALID";
+function invalid(path, problem, options) {
+	return new CliError({
+		code: PROJECT_INVALID,
+		message: `the Project file ${path} is invalid: ${problem}`,
+		hint: `fix ${path}, then run the command again`
+	}, options);
+}
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return void 0;
+		throw error;
+	}
+}
+function parsed(path, text, schema) {
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch (error) {
+		throw invalid(path, messageOf(error), { cause: error });
+	}
+	const result = schema.safeParse(json);
+	if (!result.success) throw invalid(path, prettifyError(result.error));
+	return result.data;
+}
+function projectFrom({ file, schema }, folder) {
+	const path = join(folder, file);
+	const text = readText(path);
+	if (text !== void 0) return {
+		root: folder,
+		settings: parsed(path, text, schema)
+	};
+	const parent = dirname(folder);
+	return parent === folder ? void 0 : projectFrom({
+		file,
+		schema
+	}, parent);
+}
+/** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
+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,
+	SIGTERM: 143
+};
+const EXIT_CODES = {
+	caller: 1,
+	operator: 2,
+	source: 3,
+	wait: 75,
+	bug: 70
+};
+/** The codes the Runtime and its built-in Commands raise, each with the class that must act on it. */
+function runtimeCodes() {
+	return {
+		[INVALID_INPUT]: "caller",
+		[UNKNOWN_OPTION]: "caller",
+		[UNKNOWN_COMMAND]: "caller",
+		[UNKNOWN_FIELD]: "caller",
+		[CONFIRMATION_REQUIRED]: "caller",
+		[CONFIRMATION_MISMATCH]: "caller",
+		[NOT_CONFIRMED]: "operator",
+		[OUTPUT_EXISTS]: "caller",
+		[INTERRUPTED]: "interrupted",
+		[DEADLINE_EXCEEDED]: "wait",
+		[INTERNAL_CODE]: "bug",
+		[PERMISSION_DENIED]: "operator",
+		[DISK_FULL]: "operator",
+		[NOT_FOUND]: "caller",
+		[TOOL_FAILED]: "operator",
+		[TOOL_MISSING]: "operator",
+		[PROJECT_INVALID]: "operator",
+		[DOCTOR_PROBLEMS]: "operator",
+		[NOT_GLOBAL_INSTALL]: "operator",
+		[REGISTRY_UNREACHABLE]: "operator",
+		[REGISTRY_AUTH]: "operator",
+		[INSTALL_FAILED]: "operator",
+		[NPM_FAILED]: "operator",
+		[NO_LATEST]: "source"
+	};
+}
+/** The codes of `errors` that the Runtime already declares, which a CLI cannot redeclare. */
+function runtimeCodesIn(errors) {
+	return Object.keys(errors).filter((code) => Object.hasOwn(runtimeCodes(), code));
+}
+function exitClassOfOne(error, errors) {
+	if (!(error instanceof CliError)) return "bug";
+	if (error instanceof UsageError) return "caller";
+	return runtimeCodes()[error.code] ?? errors[error.code]?.class ?? "bug";
+}
+function isBug(error, errors) {
+	return exitClassOfOne(error, errors) === "bug";
+}
+const ACT_FIRST = [
+	"caller",
+	"operator",
+	"source",
+	"wait",
+	"interrupted"
+];
+function exitClassOf(error, errors) {
+	const classes = errorsOf(error).map((each) => exitClassOfOne(each, errors));
+	if (classes.includes("bug")) return "bug";
+	return ACT_FIRST.find((exitClass) => classes.includes(exitClass)) ?? "bug";
+}
+/**
+* The classes other than bug and interrupt that a run of `cli` can end in: those of the Runtime's
+* codes it can reach, and those of its own table.
+*/
+function reachableExitClasses(cli) {
+	const runtime = [
+		"caller",
+		"operator",
+		"wait",
+		...cli.commands !== void 0 && cli.install !== void 0 ? ["source"] : []
+	];
+	const own = Object.values(cli.errors ?? {}).map((declaration) => declaration.class);
+	return /* @__PURE__ */ new Set([...runtime, ...own]);
+}
+/** The signal named by an interrupt's abort reason; any other reason counts as Ctrl-C. */
+function stopSignalOf(reason) {
+	return reason === "SIGTERM" ? "SIGTERM" : "SIGINT";
+}
+/**
+* The exit code of a run that failed with `error`, given the CLI's error table; `stop` is the
+* signal that interrupted it, if any.
+*/
+function exitCodeOf(error, errors, stop) {
+	const exitClass = exitClassOf(error, errors);
+	return exitClass === "interrupted" ? SIGNAL_EXIT_CODES[stopSignalOf(stop?.reason)] : EXIT_CODES[exitClass];
+}
+//#endregion
+//#region ../agent-cli/dist/help.js
+function table(rows) {
+	const width = Math.max(...rows.map(([left]) => left.length));
+	return rows.map(([left, right]) => right === "" ? `  ${left}` : `  ${left.padEnd(width)}  ${right}`);
+}
+function section(title, rows, style) {
+	return rows.length === 0 ? [] : [
+		"",
+		style.bold(`${title}:`),
+		...table(rows)
+	];
+}
+function summaryOf(node) {
+	return node.kind === "command" ? node.description : `group: ${Object.keys(node.commands).join(", ")}`;
+}
+function commandRows({ commands }) {
+	return Object.entries(commands).map(([key, node]) => [key, summaryOf(node)]);
+}
+function lines(...parts) {
+	return `${parts.join("\n")}\n`;
+}
+function listingLines(heading, group, style) {
+	return [
+		style.bold(heading),
+		...section("Commands", commandRows(group), style),
+		"",
+		`Run \`${group.commandLine} <command> --help\` for its examples and input.`
+	];
+}
+const EXIT_MEANINGS = {
+	caller: "the caller fixes its command",
+	operator: "the operator acts on their machine",
+	source: "someone at the source acts",
+	wait: "nobody acts: wait, then run it again"
+};
+function exitCodeRows(cli) {
+	return [
+		["0", "done"],
+		...[...[...reachableExitClasses(cli)].map((exitClass) => [EXIT_CODES[exitClass], EXIT_MEANINGS[exitClass]]), [EXIT_CODES.bug, `a bug in ${cli.name}`]].sort(([a], [b]) => a - b).map(([code, meaning]) => [String(code), meaning]),
+		[Object.values(SIGNAL_EXIT_CODES).join(", "), "interrupted"]
+	];
+}
+function firstExample(node) {
+	if (node.kind === "command") return node.examples.slice(0, 1);
+	return Object.values(node.commands).flatMap(firstExample).slice(0, 1);
+}
+function rootExamples(root) {
+	if (root.kind === "command") return [...root.examples];
+	const { doctor, ...others } = root.commands;
+	return [...Object.values(others), ...doctor === void 0 ? [] : [doctor]].flatMap(firstExample);
+}
+function examplesSection(examples, style) {
+	return section("Examples", examples.map(({ command, note }) => [command, note]), style);
+}
+/** The CLI's own help: a listing or its single Command's help, ending with exit codes and examples. */
+function cliHelp(cli, root, style) {
+	return lines(...root.kind === "command" ? commandLines(root, style, { examples: false }) : listingLines(`${root.commandLine} ${cli.version}`, root, style), ...section("Exit codes", exitCodeRows(cli), style), ...examplesSection(rootExamples(root), style));
+}
+function groupHelp(group, style) {
+	return lines(...listingLines(group.commandLine, group, style));
+}
+const EFFECT_NOTES = {
+	read: "changes nothing",
+	write: "changes something; show the Plan with --dry-run",
+	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"
+};
+function choicesOf(field) {
+	return field.choices === void 0 ? [] : [`one of: ${field.choices.join(", ")}`];
+}
+function defaultsOf(field) {
+	if (field.defaultValue === void 0) return [];
+	if (field.type !== "boolean") return [`default: ${JSON.stringify(field.defaultValue)}`];
+	return field.defaultValue === true ? ["on by default; this flag turns it off"] : [];
+}
+function fieldRow(field, notes) {
+	const all = [...field.required ? ["required"] : [], ...notes];
+	const suffix = all.length === 0 ? "" : `(${all.join("; ")})`;
+	return [field.usage, [field.description ?? "", suffix].filter((part) => part !== "").join(" ")];
+}
+function argRow(field) {
+	return fieldRow(field, [...choicesOf(field), ...defaultsOf(field)]);
+}
+function optionRow(field) {
+	return fieldRow(field, defaultsOf(field));
+}
+function flagRow({ usage, description }) {
+	return [usage, description];
+}
+function commandLines(spec, style, { examples }) {
+	return [
+		style.bold(spec.commandLine),
+		spec.description,
+		...examples ? examplesSection(spec.examples, style) : [],
+		...section("Arguments", spec.args.map(argRow), style),
+		...section("Options", spec.options.map(optionRow), style),
+		"",
+		`${style.bold("Effect:")} ${spec.effect} (${EFFECT_NOTES[spec.effect]})`,
+		...section("Standard flags", spec.standardFlags.map(flagRow), style)
+	];
+}
+function commandHelp(spec, style) {
+	return lines(...commandLines(spec, style, { examples: true }));
+}
+//#endregion
+//#region ../agent-cli/dist/help-json.js
+function inputSchema(schema) {
+	return toJSONSchema(schema, {
+		io: "input",
+		unrepresentable: "any"
+	});
+}
+function optionsSchema(options) {
+	return inputSchema(object(Object.fromEntries(options.map(({ name, schema }) => [name, schema]))));
+}
+function commandData(spec) {
+	return {
+		name: spec.commandLine,
+		description: spec.description,
+		effect: spec.effect,
+		examples: spec.examples,
+		args: inputSchema(spec.command.args ?? object({})),
+		options: optionsSchema(spec.options),
+		standardFlags: spec.standardFlags.map(({ usage, description, schema }) => ({
+			usage,
+			description,
+			schema: inputSchema(schema)
+		})),
+		output: spec.output === void 0 ? null : toJSONSchema(spec.output, { unrepresentable: "any" })
+	};
+}
+function nodeData(node) {
+	return node.kind === "command" ? commandData(node) : groupData(node);
+}
+function groupData(group) {
+	return {
+		name: group.commandLine,
+		commands: Object.values(group.commands).map(nodeData)
+	};
+}
+function printed$1(data) {
+	return `${JSON.stringify(data)}\n`;
+}
+function errorsData(errors) {
+	return Object.fromEntries(Object.entries(errors).map(([code, declaration]) => [code, {
+		class: declaration.class,
+		details: declaration.details === void 0 ? null : toJSONSchema(declaration.details, { unrepresentable: "any" })
+	}]));
+}
+function cliHelpJson({ version, errors }, root) {
+	return printed$1({
+		name: root.commandLine,
+		version,
+		...nodeData(root),
+		errors: errorsData(errors ?? {})
+	});
+}
+function groupHelpJson(group) {
+	return printed$1(groupData(group));
+}
+function commandHelpJson(spec) {
+	return printed$1(commandData(spec));
+}
+//#endregion
+//#region ../agent-cli/dist/output.js
+const SUCCESS_EXIT_CODE = 0;
+function withTrailingNewline(text) {
+	return text === "" || text.endsWith("\n") ? text : `${text}\n`;
+}
+function printed(value, render, { json, invocation, style, fields }) {
+	if (!(value instanceof Page)) return json ? `${JSON.stringify(value)}\n` : withTrailingNewline(render(style));
+	const page = printedPage(value, invocation);
+	if (fields === void 0) return json ? `${JSON.stringify(page)}\n` : `${withTrailingNewline(render(style))}${pageFooter(page)}`;
+	const rows = projected(page.items, fields);
+	return json ? `${JSON.stringify({
+		...page,
+		items: rows
+	})}\n` : `${renderRows(rows, fields)}${pageFooter(page)}`;
+}
+function errorText(error, format) {
+	const text = formatRuntimeError(error, {
+		...format,
+		isBug: (each) => isBug(each, format.errors)
+	});
+	const { usageHelp, json } = format;
+	return usageHelp !== void 0 && !json && error instanceof UsageError ? `${text}\n${usageHelp}` : text;
+}
+function stdoutOf({ value, render }, format, spill) {
+	const text = printed(value, render, format);
+	return value instanceof Page ? text : spill(text, format.json);
+}
+/** What a serve Command prints the moment it starts. */
+function startedOutput(outcome, format, spill) {
+	return stdoutOf(outcome, {
+		...format,
+		fields: void 0
+	}, spill);
+}
+/** A serve Command stopped after it started: stopping it is how it is meant to end. */
+const STOPPED_RESULT = {
+	stdout: "",
+	stderr: "",
+	exitCode: SUCCESS_EXIT_CODE
+};
+function errorResult(error, format) {
+	return {
+		stdout: "",
+		stderr: errorText(error, format),
+		exitCode: exitCodeOf(error, format.errors, format.stop)
+	};
+}
+async function commandResult(settled, format, spill) {
+	if (settled.ok) try {
+		return {
+			stdout: await stdoutOf(settled.outcome, format, spill),
+			stderr: "",
+			exitCode: SUCCESS_EXIT_CODE
+		};
+	} catch (spillError) {
+		return errorResult(spillError, format);
+	}
+	const { error, delivered } = settled;
+	const result = errorResult(error, format);
+	if (delivered === void 0) return result;
+	try {
+		return {
+			...result,
+			stdout: await stdoutOf(delivered, format, spill)
+		};
+	} catch (spillError) {
+		const both = new AggregateError([...errorsOf(error), spillError]);
+		return {
+			...result,
+			stderr: errorText(both, format)
+		};
+	}
+}
+function textHelp(node, root, cli, style) {
+	if (node === root) return cliHelp(cli, node, style);
+	return node.kind === "command" ? commandHelp(node, style) : groupHelp(node, style);
+}
+function helpOf(node, root, cli, style, json) {
+	if (!json) return textHelp(node, root, cli, style);
+	if (node === root) return cliHelpJson(cli, node);
+	return node.kind === "command" ? commandHelpJson(node) : groupHelpJson(node);
+}
+function helpResult(node, root, cli, { style, json }) {
+	return {
+		stdout: helpOf(node, root, cli, style, json),
+		stderr: "",
+		exitCode: SUCCESS_EXIT_CODE
+	};
+}
+/** The first line of `--version`: the version, and the commit and time of a stamped build. */
+function versionLine({ version, build }) {
+	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
+}
+function versionResult(cli, packageRoot) {
+	return {
+		stdout: `${(cli.build === void 0 ? [versionLine(cli)] : [versionLine(cli), `changelog ${join(packageRoot, "CHANGELOG.md")}`]).join("\n")}\n`,
+		stderr: "",
+		exitCode: SUCCESS_EXIT_CODE
+	};
+}
+//#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}`;
+}
+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. */
+function skillVersionIn(skill) {
+	const frontmatter = FRONTMATTER.exec(skill)?.[1];
+	return frontmatter === void 0 ? void 0 : METADATA_VERSION.exec(`${frontmatter}\n`)?.[1];
+}
+function homeOf(env) {
+	return env.HOME ?? env.USERPROFILE ?? homedir();
+}
+async function copyAt(path, cliVersion) {
+	let skill;
+	try {
+		skill = await readFile(join(path, "SKILL.md"), "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return;
+		return {
+			path,
+			version: void 0,
+			state: "unreadable"
+		};
+	}
+	const version = skillVersionIn(skill);
+	if (version === void 0 || !isVersion(version) || !isVersion(cliVersion)) return {
+		path,
+		version,
+		state: "unversioned"
+	};
+	return {
+		path,
+		version,
+		state: standingOf(version, cliVersion)
+	};
+}
+/** Every installed copy of the skill named after the CLI, in the project first, then under home. */
+async function skillCopies(skillName, cliVersion, cwd, env) {
+	const paths = [cwd, homeOf(env)].flatMap((root) => SKILL_DIRS.map((dir) => join(root, ...dir, skillName)));
+	const seen = /* @__PURE__ */ new Set();
+	const copies = [];
+	for (const path of paths) {
+		const copy = await copyAt(path, cliVersion);
+		const real = copy === void 0 ? void 0 : await realpath(path);
+		if (copy !== void 0 && real !== void 0 && !seen.has(real)) {
+			seen.add(real);
+			copies.push(copy);
+		}
+	}
+	return copies;
+}
+//#endregion
+//#region ../agent-cli/dist/doctor-rows.js
+function ok(message) {
+	return {
+		state: "ok",
+		message
+	};
+}
+function buildRow(cli) {
+	return {
+		name: "build",
+		run: () => ok(versionLine(cli))
+	};
+}
+function nodeRow(cli) {
+	return {
+		name: "node",
+		run: () => {
+			const found = process.versions.node;
+			const range = cli.engines?.node;
+			if (range === void 0) return ok(`Node ${found}; ${cli.name} declares no engines.node to check it against`);
+			const minimum = engineMinimum(range);
+			if (minimum === void 0) return {
+				state: "problem",
+				message: `${cli.name} declares engines.node "${range}", which doctor cannot read: only >=X.Y.Z is supported`
+			};
+			if (meetsMinimum(found, minimum)) return ok(`Node ${found} meets ${range}`);
+			const major = minimum[0];
+			return {
+				state: "problem",
+				message: `${cli.name} runs on Node ${found}, older than the ${range} it needs; install Node ${minimum.join(".")} or newer and make it the default`,
+				fix: `nvm install ${major} && nvm alias default ${major}`
+			};
+		}
+	};
+}
+function projectRow(projectFile) {
+	const { file } = projectFile;
+	return {
+		name: "project",
+		run: (ctx) => {
+			let project;
+			try {
+				project = projectOf(projectFile, ctx.cwd);
+			} catch (error) {
+				if (error instanceof CliError && error.code === "PROJECT_INVALID") return {
+					state: "problem",
+					message: error.message
+				};
+				throw error;
+			}
+			return ok(project === void 0 ? `none found: no ${file} at or above ${ctx.cwd}` : join(project.root, file));
+		}
+	};
+}
+function installRow(cli, bin) {
+	return {
+		name: "install",
+		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}`);
+			} catch (error) {
+				if (error instanceof CliError && error.code === "NOT_GLOBAL_INSTALL") return {
+					state: "problem",
+					message: error.message,
+					fix: installCommandLine(install)
+				};
+				throw error;
+			}
+		}
+	};
+}
+function registryRow(cli) {
+	return {
+		name: "registry",
+		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 standing = standingOf(cli.version, latest);
+			const head = `${install.registry} has ${latest} as latest: this build`;
+			if (standing === "behind") return {
+				state: "problem",
+				message: `${head} (${cli.version}) is older`,
+				fix: `${cli.name} update`
+			};
+			return ok(`${head} is ${standing === "current" ? "current" : `newer (${cli.version})`}`);
+		}
+	};
+}
+const SKILL_STATE_NOTES = {
+	current: "the same as this build",
+	behind: "older than this build",
 	ahead: "newer than this build",
 	unversioned: "states no metadata.version",
 	unreadable: "could not be read"
@@ -6318,10 +7283,14 @@ function skillRow(cli) {
 		}
 	};
 }
-/** The rows every `doctor` reports first, in this order. */
-function fixedRows(cli, bin) {
+/** Every row `doctor` reports, in order: the fixed rows around the CLI's own and its tools'. */
+function doctorChecks(cli, bin) {
 	return [
+		buildRow(cli),
 		nodeRow(cli),
+		...cli.project === void 0 ? [] : [projectRow(cli.project)],
+		...cli.doctor ?? [],
+		...toolRows(cli.commands),
 		installRow(cli, bin),
 		registryRow(cli),
 		skillRow(cli)
@@ -6329,7 +7298,8 @@ function fixedRows(cli, bin) {
 }
 //#endregion
 //#region ../agent-cli/dist/doctor.js
-const PROBE_DEADLINE_MS = 1e4;
+const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
+const DEFAULT_DEADLINE_MS = 1e4;
 const MS_PER_SECOND = 1e3;
 const MIN_LABEL_WIDTH = 8;
 const reportSchema = object({
@@ -6341,19 +7311,10 @@ const reportSchema = object({
 	})),
 	next: array(string())
 });
-function untilAborted(signal) {
-	return new Promise((_resolve, reject) => {
-		if (signal.aborted) {
-			reject(signal.reason);
-			return;
-		}
-		signal.addEventListener("abort", () => reject(signal.reason), { once: true });
-	});
-}
-function problemOf(check, error, { signal, deadline }) {
+function problemOf(check, error, { signal, deadline, ms }) {
 	if (!signal.aborted && deadline.aborted && error === deadline.reason) return {
 		state: "problem",
-		message: `${check.name} did not answer within ${PROBE_DEADLINE_MS / MS_PER_SECOND} s`
+		message: `${check.name} did not answer within ${ms / MS_PER_SECOND} s`
 	};
 	if (error instanceof CliError) return {
 		state: "problem",
@@ -6365,7 +7326,8 @@ function problemOf(check, error, { signal, deadline }) {
 	};
 }
 async function rowOf(check, ctx) {
-	const signal = ctx.deadline(PROBE_DEADLINE_MS);
+	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
+	const signal = ctx.deadline(ms);
 	let finding;
 	try {
 		finding = await Promise.race([Promise.resolve().then(() => check.run({
@@ -6375,12 +7337,16 @@ async function rowOf(check, ctx) {
 	} catch (error) {
 		finding = problemOf(check, error, {
 			signal: ctx.signal,
-			deadline: signal
+			deadline: signal,
+			ms
 		});
 	}
 	return {
-		check: check.name,
-		...finding
+		row: {
+			check: check.name,
+			...finding
+		},
+		advisory: check.advisory === true
 	};
 }
 function nextOf(rows) {
@@ -6394,18 +7360,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, report) {
-	const problems = report.rows.filter(({ state }) => state === "problem").map(({ check }) => check);
-	return new FailureWithData({
-		code: "DOCTOR_PROBLEMS",
+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",
-		retryable: false
-	}, report);
+		hint: report.next.length === 0 ? "each problem row says what is wrong" : "run the commands under next, then run doctor again"
+	});
 }
-/** The built-in `doctor`: the fixed rows, then the CLI's own, each under its own deadline. */
+/** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
 function doctorCommand(cli, bin) {
-	return defineCommand({
+	return defineCommand$1({
 		name: "doctor",
 		description: "check the setup and say what fixes each problem",
 		examples: [{
@@ -6418,120 +7382,24 @@ function doctorCommand(cli, bin) {
 		effect: "read",
 		output: reportSchema,
 		run: async (_input, ctx) => {
-			const checks = [...fixedRows(cli, bin), ...cli.doctor ?? []];
-			const rows = await Promise.all(checks.map((check) => rowOf(check, ctx)));
+			const checked = await Promise.all(doctorChecks(cli, bin).map((check) => rowOf(check, ctx)));
+			ctx.signal.throwIfAborted();
+			const rows = checked.map(({ row }) => row);
 			const report = {
 				rows,
 				next: nextOf(rows)
 			};
-			if (rows.some(({ state }) => state === "problem")) throw failure(cli.name, report);
+			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row.check);
+			if (problems.length > 0) {
+				ctx.deliver(report);
+				throw failure(cli.name, problems, report);
+			}
 			return report;
 		},
 		render
 	});
 }
 //#endregion
-//#region ../agent-cli/dist/interrupts.js
-/** How long an interrupted Command may take to settle before the run ends without it. */
-const GRACE_MS = 3e3;
-const GRACE_OVER = Symbol("grace over");
-const INTERRUPTED = "INTERRUPTED";
-function interruptedError() {
-	return new CliError({
-		code: INTERRUPTED,
-		message: "interrupted before it finished",
-		hint: "run the command again",
-		retryable: true
-	});
-}
-function deadlineError(commandLine, ms) {
-	return new CliError({
-		code: "DEADLINE_EXCEEDED",
-		message: `${commandLine} ran past its ${ms} ms deadline`,
-		hint: "run it again later, when the service it waits on may answer faster",
-		retryable: true
-	});
-}
-/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
-var RunControl = class {
-	signal;
-	#controller = new AbortController();
-	#commandLine;
-	#outer;
-	#onOuterAbort = () => this.#controller.abort(interruptedError());
-	#steps = /* @__PURE__ */ new Set();
-	#deadlineTimers = /* @__PURE__ */ new Set();
-	#deadlineHit;
-	#graceTimer;
-	#endGrace = () => {};
-	#graceOver = new Promise((resolve) => {
-		this.#endGrace = resolve;
-	});
-	constructor(commandLine, outer) {
-		this.#commandLine = commandLine;
-		this.#outer = outer;
-		this.signal = this.#controller.signal;
-		this.signal.addEventListener("abort", () => this.#startGrace(), { once: true });
-		if (outer?.aborted === true) this.#onOuterAbort();
-		else outer?.addEventListener("abort", this.#onOuterAbort, { once: true });
-	}
-	deadline(ms) {
-		const controller = new AbortController();
-		const timer = setTimeout(() => {
-			this.#deadlineHit ??= deadlineError(this.#commandLine, ms);
-			controller.abort(this.#deadlineHit);
-		}, ms);
-		this.#deadlineTimers.add(timer);
-		return AbortSignal.any([this.signal, controller.signal]);
-	}
-	async runToEnd(work) {
-		clearTimeout(this.#graceTimer);
-		const step = work();
-		const settled = step.then(() => {}, () => {});
-		this.#steps.add(settled);
-		try {
-			return await step;
-		} finally {
-			this.#steps.delete(settled);
-			this.#startGrace();
-		}
-	}
-	/** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
-	async settle(work) {
-		try {
-			const value = await Promise.race([work, this.#graceOver]);
-			if (this.signal.aborted || value === GRACE_OVER) throw this.signal.reason;
-			return value;
-		} finally {
-			await this.#stepsDone();
-			this.#dispose();
-		}
-	}
-	/**
-	* The error a run ends with: an interrupt or a missed deadline outranks what the Command threw,
-	* unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
-	*/
-	errorAfter(error) {
-		if (this.signal.aborted) return error instanceof CliError && error.code === "INTERRUPTED" ? error : this.signal.reason;
-		if (this.#deadlineHit !== void 0 && !(error instanceof CliError)) return this.#deadlineHit;
-		return error;
-	}
-	#startGrace() {
-		if (this.signal.aborted && this.#steps.size === 0) {
-			clearTimeout(this.#graceTimer);
-			this.#graceTimer = setTimeout(() => this.#endGrace(GRACE_OVER), GRACE_MS);
-		}
-	}
-	async #stepsDone() {
-		while (this.#steps.size > 0) await Promise.all(this.#steps);
-	}
-	#dispose() {
-		clearTimeout(this.#graceTimer);
-		for (const timer of this.#deadlineTimers) clearTimeout(timer);
-		this.#outer?.removeEventListener("abort", this.#onOuterAbort);
-	}
-};
-//#endregion
 //#region ../agent-cli/dist/upgrade-notes.js
 const RELEASE_HEADING = /^## v?(\S+)/;
 function releasesIn(changelog) {
@@ -6595,17 +7463,16 @@ function renderUpdate(cli, install, update) {
 		...update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${installed.version}`)
 	].join("\n");
 }
-function interruptedAfterInstall(plan, update) {
-	return new FailureWithData({
+function interruptedAfterInstall(plan) {
+	return new CliError({
 		code: INTERRUPTED,
 		message: `interrupted, but ${plan.package}@${plan.latest} had already been installed with the npm under ${plan.prefix}, replacing ${plan.from}`,
-		hint: "nothing to run again: run the commands under next",
-		retryable: false
-	}, update);
+		hint: "nothing to run again: run the commands under next"
+	});
 }
 /** The built-in `update`, for a CLI installed globally with npm. */
 function updateCommand(cli, install, bin) {
-	return defineCommand({
+	return defineCommand$1({
 		name: "update",
 		description: "install the latest version of this CLI from its registry",
 		examples: [{
@@ -6639,7 +7506,7 @@ function updateCommand(cli, install, bin) {
 			};
 			ctx.signal.throwIfAborted();
 			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
-			await ctx.runToEnd(() => installGlobally(latest, npmContext(cli, install, ctx)));
+			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, npmContext(cli, install, ctx)));
 			const update = {
 				from,
 				latest,
@@ -6650,7 +7517,10 @@ function updateCommand(cli, install, bin) {
 				upgrades: await upgradeNotes(plan.packageDir, from, latest),
 				next: [skillUpdateCommand(cli.name)]
 			};
-			if (ctx.signal.aborted) throw interruptedAfterInstall(plan, update);
+			if (ctx.signal.aborted) {
+				ctx.deliver(update);
+				throw interruptedAfterInstall(plan);
+			}
 			return update;
 		},
 		render: (update) => renderUpdate(cli, install, update),
@@ -6666,263 +7536,208 @@ function builtInCommands(cli, bin) {
 		...cli.install === void 0 ? {} : { update: updateCommand(cli, cli.install, bin) }
 	};
 }
-function defineCli(cli) {
+//#endregion
+//#region ../agent-cli/dist/agent-cli.js
+function checkOwnCodes(cli) {
+	const redeclared = runtimeCodesIn(cli.errors ?? {});
+	if (redeclared.length > 0) throw new Error(`${cli.name} declares ${redeclared.join(", ")}, an error code the Runtime already declares`);
+}
+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);
 	if (taken.length > 0) throw new Error(`${cli.name} defines ${taken.join(", ")}, a built-in Command it cannot replace`);
-	return cli;
-}
-//#endregion
-//#region ../agent-cli/dist/command-spec.js
-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, 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/confirm.js
-function checkConfirmation({ invocation, commandLine, given }, expected) {
-	if (given === expected) return;
-	const hint = `to confirm, run \`${commandLineWith(invocation, CONFIRM_FLAG.flag, expected)}\``;
-	if (given === void 0) throw new UsageError({
-		code: "CONFIRMATION_REQUIRED",
-		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
-		hint
-	});
-	throw new UsageError({
-		code: "CONFIRMATION_MISMATCH",
-		message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
-		hint
-	});
-}
-//#endregion
-//#region ../agent-cli/dist/execute.js
-function outcomeOf(value, render) {
-	return {
-		value,
-		render: (style) => render(value, style)
-	};
-}
-/** How the Command prints data it fails with, which is the data its `run` or `apply` returns. */
-function renderOf(command) {
-	return (data, style) => command.render(data, style);
-}
-async function execute(command, input, ctx, { dryRun, confirm, page, invocation, commandLine }) {
-	if (command.rows !== void 0) return outcomeOf(await command.run({
-		...input,
-		...page
-	}, ctx), (data, style) => command.render(data, style));
-	if (command.effect === "read") return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
-	const plan = await command.plan(input, ctx);
-	if (dryRun) return outcomeOf(plan, (value, style) => command.renderPlan(value, style));
-	if (command.effect === "destructive") checkConfirmation({
-		invocation,
-		commandLine,
-		given: confirm
-	}, command.confirm(plan));
-	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
-}
-//#endregion
-//#region ../agent-cli/dist/help.js
-function table(rows) {
-	const width = Math.max(...rows.map(([left]) => left.length));
-	return rows.map(([left, right]) => right === "" ? `  ${left}` : `  ${left.padEnd(width)}  ${right}`);
-}
-function section(title, rows, style) {
-	return rows.length === 0 ? [] : [
-		"",
-		style.bold(`${title}:`),
-		...table(rows)
-	];
-}
-function summaryOf(node) {
-	return node.kind === "command" ? node.description : `group: ${Object.keys(node.commands).join(", ")}`;
-}
-function commandRows({ commands }) {
-	return Object.entries(commands).map(([key, node]) => [key, summaryOf(node)]);
-}
-function lines(...parts) {
-	return `${parts.join("\n")}\n`;
-}
-function listing(heading, group, style) {
-	return lines(style.bold(heading), ...section("Commands", commandRows(group), style), "", `Run \`${group.commandLine} <command> --help\` for its examples and input.`);
-}
-function cliHelp(version, root, style) {
-	return listing(`${root.commandLine} ${version}`, root, style);
-}
-function groupHelp(group, style) {
-	return listing(group.commandLine, group, style);
-}
-const EFFECT_NOTES = {
-	read: "changes nothing",
-	write: "changes something; show the Plan with --dry-run",
-	destructive: "changes something hard to undo; show the Plan with --dry-run, run with --confirm"
-};
-function choicesOf(field) {
-	return field.choices === void 0 ? [] : [`one of: ${field.choices.join(", ")}`];
-}
-function defaultsOf(field) {
-	if (field.defaultValue === void 0) return [];
-	if (field.type !== "boolean") return [`default: ${JSON.stringify(field.defaultValue)}`];
-	return field.defaultValue === true ? ["on by default; this flag turns it off"] : [];
-}
-function fieldRow(field, notes) {
-	const all = [...field.required ? ["required"] : [], ...notes];
-	const suffix = all.length === 0 ? "" : `(${all.join("; ")})`;
-	return [field.usage, [field.description ?? "", suffix].filter((part) => part !== "").join(" ")];
-}
-function argRow(field) {
-	return fieldRow(field, [...choicesOf(field), ...defaultsOf(field)]);
-}
-function optionRow(field) {
-	return fieldRow(field, defaultsOf(field));
-}
-function flagRow({ usage, description }) {
-	return [usage, description];
-}
-function commandHelp(spec, style) {
-	return lines(style.bold(spec.commandLine), spec.description, ...section("Examples", spec.examples.map(({ command, note }) => [command, note]), style), ...section("Arguments", spec.args.map(argRow), style), ...section("Options", spec.options.map(optionRow), style), "", `${style.bold("Effect:")} ${spec.effect} (${EFFECT_NOTES[spec.effect]})`, ...section("Standard flags", spec.standardFlags.map(flagRow), style));
-}
-//#endregion
-//#region ../agent-cli/dist/help-json.js
-function inputSchema(schema) {
-	return toJSONSchema(schema, {
-		io: "input",
-		unrepresentable: "any"
-	});
-}
-function optionsSchema(options) {
-	return inputSchema(object(Object.fromEntries(options.map(({ name, schema }) => [name, schema]))));
+	return cli;
 }
-function commandData(spec) {
+/**
+* Declares the CLI's ports and its Project file's settings once; the `defineCommand` and
+* `defineCli` it returns type `ctx.ports` and `ctx.project`.
+*/
+function agentCli() {
 	return {
-		name: spec.commandLine,
-		description: spec.description,
-		effect: spec.effect,
-		examples: spec.examples,
-		args: inputSchema(spec.command.args ?? object({})),
-		options: optionsSchema(spec.options),
-		standardFlags: spec.standardFlags.map(({ usage, description, schema }) => ({
-			usage,
-			description,
-			schema: inputSchema(schema)
-		})),
-		output: spec.output === void 0 ? null : toJSONSchema(spec.output, { unrepresentable: "any" })
+		defineCommand: defineCommandFor(),
+		defineCli: defineCli$1
 	};
 }
-function nodeData(node) {
-	return node.kind === "command" ? commandData(node) : groupData(node);
+//#endregion
+//#region ../agent-cli/dist/error-table.js
+/** Keeps each code's literal class and `details` schema, so `cliError` can type its throw sites. */
+function defineErrors(table) {
+	return table;
 }
-function groupData(group) {
+/** A `CliError` for a code of `table`, whose `details` must match the code's schema. */
+function cliError(_table, code, init, options) {
+	return new CliError({
+		...init,
+		code
+	}, options);
+}
+//#endregion
+//#region ../agent-cli/dist/command-spec.js
+function declaredOf(command) {
+	const planned = command.effect === "write" || command.effect === "destructive";
 	return {
-		name: group.commandLine,
-		commands: Object.values(group.commands).map(nodeData)
+		outputs: planned && command.outputs !== void 0,
+		cost: planned && command.cost !== void 0
 	};
 }
-function printed$1(data) {
-	return `${JSON.stringify(data)}\n`;
-}
-function cliHelpJson(version, root) {
-	return printed$1({
-		name: root.commandLine,
-		version,
-		...nodeData(root)
-	});
+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 groupHelpJson(group) {
-	return printed$1(groupData(group));
+function groupSpec(commandLine, commands) {
+	return {
+		kind: "group",
+		commandLine,
+		commands: Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node)]))
+	};
 }
-function commandHelpJson(spec) {
-	return printed$1(commandData(spec));
+function specOf(commandLine, node) {
+	return isCommand(node) ? commandSpec(commandLine, node) : groupSpec(commandLine, node);
 }
 //#endregion
-//#region ../agent-cli/dist/output.js
-const SUCCESS_EXIT_CODE = 0;
-const FAILURE_EXIT_CODE = 1;
-const USAGE_EXIT_CODE = 2;
-function withTrailingNewline(text) {
-	return text === "" || text.endsWith("\n") ? text : `${text}\n`;
+//#region ../agent-cli/dist/execute.js
+function outcomeOf(value, render) {
+	return {
+		value,
+		render: (style) => render(value, style)
+	};
 }
-function printed(value, render, { json, invocation, style, fields }) {
-	if (!(value instanceof Page)) return json ? `${JSON.stringify(value)}\n` : withTrailingNewline(render(style));
-	const page = printedPage(value, invocation);
-	if (fields === void 0) return json ? `${JSON.stringify(page)}\n` : `${withTrailingNewline(render(style))}${pageFooter(page)}`;
-	const rows = projected(page.items, fields);
-	return json ? `${JSON.stringify({
-		...page,
-		items: rows
-	})}\n` : `${renderRows(rows, fields)}${pageFooter(page)}`;
+/** Delivered data as the Command prints it, which is the data its `run` or `apply` returns. */
+function deliveredOutcome(command, data) {
+	return outcomeOf(data, command.render);
 }
-function errorResult(error, format) {
+function dryRunOutcome(command, plan) {
+	const renderPlan = (style) => command.renderPlan(plan, style);
+	if (command.outputs === void 0 && command.cost === void 0) return {
+		value: plan,
+		render: renderPlan
+	};
+	const outputs = command.outputs?.(plan);
+	const cost = command.cost?.(plan);
 	return {
-		stdout: "",
-		stderr: formatRuntimeError(error, format),
-		exitCode: error instanceof UsageError ? USAGE_EXIT_CODE : FAILURE_EXIT_CODE
+		value: {
+			plan,
+			...outputs === void 0 ? {} : { outputs },
+			...command.cost === void 0 ? {} : { cost: cost ?? null }
+		},
+		render: (style) => [
+			renderPlan(style),
+			...outputs === void 0 ? [] : ["outputs:", ...outputs.map((path) => `  ${path}`)],
+			...cost === void 0 ? [] : [`cost: ${cost}`]
+		].join("\n")
 	};
 }
-function commandResult(settled, format) {
-	if (settled.ok) {
-		const { value, render } = settled.outcome;
-		return {
-			stdout: printed(value, render, format),
-			stderr: "",
-			exitCode: SUCCESS_EXIT_CODE
-		};
+async function execute(command, input, ctx, { dryRun, confirm, yes, force, page, invocation, commandLine, started }) {
+	await checkTools(command.tools ?? [], ctx.env);
+	if (command.rows !== void 0) return outcomeOf(await command.run({
+		...input,
+		...page
+	}, ctx), (data, style) => command.render(data, style));
+	if (command.effect === "read") return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
+	if (command.effect === "serve") {
+		await started(outcomeOf(await command.start(input, ctx), (value, style) => command.render(value, style)));
+		return untilAborted(ctx.signal);
 	}
-	const { error, render } = settled;
-	const result = errorResult(error, format);
-	if (!(error instanceof FailureWithData)) return result;
-	const stdout = printed(error.data, (style) => render(error.data, style), format);
-	return {
-		...result,
-		stdout
-	};
+	const plan = await command.plan(input, ctx);
+	if (dryRun) return dryRunOutcome(command, plan);
+	await checkOutputs({
+		invocation,
+		commandLine,
+		force,
+		files: ctx.files
+	}, command.outputs?.(plan));
+	checkCost({
+		invocation,
+		commandLine,
+		yes
+	}, command.cost?.(plan));
+	if (command.effect === "destructive") checkConfirmation({
+		invocation,
+		commandLine,
+		given: confirm
+	}, command.confirm(plan));
+	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
 }
-function helpOf(node, root, cli, style, json) {
-	if (json) {
-		if (node === root) return cliHelpJson(cli.version, node);
-		return node.kind === "command" ? commandHelpJson(node) : groupHelpJson(node);
+//#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 (node.kind === "command") return commandHelp(node, style);
-	return node === root ? cliHelp(cli.version, node, style) : groupHelp(node, style);
 }
-function helpResult(node, root, cli, { style, json }) {
-	return {
-		stdout: helpOf(node, root, cli, style, json),
-		stderr: "",
-		exitCode: SUCCESS_EXIT_CODE
-	};
+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 })));
 }
-function versionResult({ version, build }) {
+/** 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 {
-		stdout: `${build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""})`}\n`,
-		stderr: "",
-		exitCode: SUCCESS_EXIT_CODE
+		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;
+			}
+		}
 	};
 }
 //#endregion
+//#region ../agent-cli/dist/package-root.js
+/**
+* The nearest folder holding a `package.json`, searched upward from the bin or, run without one,
+* from `cwd`; the search's start when none holds one. The bin is resolved through links first,
+* since npm's global bin is a link to it.
+*/
+function packageRootOf(bin, cwd) {
+	const start = bin === void 0 ? resolve(cwd) : dirname(realpathSync(bin));
+	for (let dir = start;; dir = dirname(dir)) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		if (dirname(dir) === dir) return start;
+	}
+}
+//#endregion
 //#region ../agent-cli/dist/suggest.js
 const MAX_DISTANCE = 3;
 const MIN_SIMILARITY = .4;
@@ -7047,40 +7862,6 @@ function tokenize(words, known) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/usage.js
-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 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"
-	});
-}
-function unknownCommandError(commandLine, name, suggestions) {
-	return unknownError({
-		code: "UNKNOWN_COMMAND",
-		problem: `unknown command '${name}'`,
-		commandLine,
-		corrections: suggestions.map((suggestion) => `${commandLine} ${suggestion}`),
-		listed: "commands"
-	});
-}
-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/parse-input.js
 const NO_INPUT = object({});
 function knownFlags(spec) {
@@ -7137,7 +7918,7 @@ function invalidInput(commandLine, invocation, unknown, otherLines) {
 	const renames = new Map(unknown.flatMap(({ flag, suggestion }) => suggestion === void 0 ? [] : [[flag, suggestion]]));
 	const correctable = otherLines.length === 0 && renames.size === unknown.length;
 	return new UsageError({
-		code: "INVALID_INPUT",
+		code: INVALID_INPUT,
 		message: [
 			`invalid input for \`${commandLine}\``,
 			...unknown.map(unknownLine),
@@ -7190,6 +7971,8 @@ function parseCommand({ spec, words, json }, invocation) {
 			json,
 			dryRun: values.get(DRY_RUN_FLAG.flag) === true,
 			confirm: typeof confirm === "string" ? confirm : void 0,
+			yes: values.get(YES_FLAG.flag) === true,
+			force: values.get(FORCE_FLAG.flag) === true,
 			page,
 			fields: spec.list === void 0 ? void 0 : selectedFields(values, spec.list.rowFields, spec.commandLine)
 		}
@@ -7244,6 +8027,7 @@ function walk(node, words, json, invocation) {
 		return {
 			kind: "usage error",
 			error: unknownOptionError(node.commandLine, invocation, first, suggestions),
+			node,
 			json
 		};
 	}
@@ -7254,6 +8038,7 @@ function unknownCommand(group, name, json) {
 	return {
 		kind: "usage error",
 		error: unknownCommandError(group.commandLine, name, suggestions),
+		node: group,
 		json
 	};
 }
@@ -7269,19 +8054,94 @@ function route(root, invocation) {
 	return walk(root, argv.filter((word, index) => !(index < options.length && word === JSON_FLAG.flag)), json, invocation);
 }
 //#endregion
+//#region ../agent-cli/dist/secrets.js
+function dotenvPath(cliName, env) {
+	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+	return join(config, cliName, ".env");
+}
+function readDotenv(path) {
+	try {
+		return parseEnv(readFileSync(path, "utf8"));
+	} catch (error) {
+		if (isMissingFile(error)) return {};
+		throw error;
+	}
+}
+/** Looks `name` up in the env, then in `$XDG_CONFIG_HOME/<cli>/.env`; an empty value counts as unset. */
+function secretOf(cliName, env, name) {
+	const fromEnv = env[name];
+	if (fromEnv) return {
+		value: fromEnv,
+		origin: { kind: "env" }
+	};
+	const path = dotenvPath(cliName, env);
+	const fromFile = readDotenv(path)[name];
+	return fromFile ? {
+		value: fromFile,
+		origin: {
+			kind: "file",
+			path
+		}
+	} : void 0;
+}
+//#endregion
+//#region ../agent-cli/dist/spill.js
+const STDOUT_BUDGET_CHARS = 3e4;
+const SPILL_RETENTION_MS = 6048e5;
+const PREVIEW_CHARS = 2e3;
+const SPILL_FILE = /^\d{4}-\d\d-\d\dT\d\d-\d\d-\d\d\.\d{3}Z-.+\.(json|txt)$/;
+function spillName(now, commandName, json) {
+	return `${new Date(now).toISOString().replaceAll(":", "-")}-${commandName}.${json ? "json" : "txt"}`;
+}
+async function pruneOne(path, cutoff) {
+	try {
+		if ((await stat(path)).mtimeMs < cutoff) await rm(path, { force: true });
+	} catch (error) {
+		if (!isMissingFile(error)) throw error;
+	}
+}
+async function pruneOld(folder, cutoff) {
+	const names = (await readdir(folder)).filter((name) => SPILL_FILE.test(name));
+	await Promise.all(names.map((name) => pruneOne(join(folder, name), cutoff)));
+}
+async function prepare(folder, cutoff, target) {
+	try {
+		await mkdir(folder, { recursive: true });
+		await pruneOld(folder, cutoff);
+	} catch (error) {
+		throw classifyErrno(error, {
+			path: folder,
+			callerLine: target.callerLine,
+			env: target.env
+		});
+	}
+}
+function tempRoot(env) {
+	const { TMPDIR } = env;
+	return TMPDIR === void 0 || TMPDIR === "" ? tmpdir() : TMPDIR;
+}
+function spillTo(target) {
+	return async (printed, json) => {
+		if (printed.length <= STDOUT_BUDGET_CHARS) return printed;
+		const now = target.clock.now();
+		const folder = join(tempRoot(target.env), target.cliName);
+		await prepare(folder, now - SPILL_RETENTION_MS, target);
+		const file = join(folder, spillName(now, target.commandName, json));
+		await target.files.write(file, printed);
+		const bytes = Buffer.byteLength(printed);
+		const preview = printed.slice(0, PREVIEW_CHARS);
+		return json ? `${JSON.stringify({
+			file,
+			bytes,
+			preview
+		})}\n` : `file: ${file}\nbytes: ${bytes}\npreview:\n${preview}\n`;
+	};
+}
+//#endregion
 //#region ../agent-cli/dist/style.js
-const AGENT_VARIABLES = [
-	"CLAUDECODE",
-	"CODEX_CI",
-	"CODEX_SANDBOX",
-	"GEMINI_CLI",
-	"CURSOR_AGENT",
-	"CI"
-];
 function colourEnabled(env, stdoutIsTTY) {
-	const noColor = env.NO_COLOR !== void 0 && env.NO_COLOR !== "";
-	const agent = AGENT_VARIABLES.some((name) => env[name] !== void 0);
-	return stdoutIsTTY && !noColor && !agent;
+	if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+	return env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0" || stdoutIsTTY && !isAgent(env);
 }
 function sgr(open, close) {
 	return (text) => `\u001b[${open}m${text}\u001b[${close}m`;
@@ -7308,7 +8168,36 @@ function styleFor(env, stdoutIsTTY) {
 }
 //#endregion
 //#region ../agent-cli/dist/run-cli.js
-async function runCommand(routed, { base, signal, format: baseFormat }) {
+/** `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
+				});
+			}
+		}
+	};
+}
+async function runCommand(routed, { base, writeStdout, signal, format: baseFormat, ports, clock, files, spawn, projectFile }) {
 	const { command, commandLine } = routed.spec;
 	const format = {
 		...baseFormat,
@@ -7316,19 +8205,55 @@ async function runCommand(routed, { base, signal, format: baseFormat }) {
 	};
 	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 control = new RunControl(commandLine, signal);
+	const control = new RunControl({
+		commandLine,
+		outer: signal,
+		clock,
+		progress: base.progress,
+		runDeadline: command.deadline === void 0 ? void 0 : {
+			ms: command.deadline.ms,
+			hint: command.deadline.resume(input)
+		}
+	});
+	let delivered;
+	const callerLine = commandLineOf(invocation);
+	const classified = classifiedFiles(files, base, callerLine);
+	const spill = spillTo({
+		cliName: format.cliName,
+		commandName: command.name,
+		env: base.env,
+		clock,
+		files: classified,
+		callerLine
+	});
 	const ctx = {
 		...base,
 		signal: control.signal,
 		deadline: (ms) => control.deadline(ms),
-		runToEnd: (work) => control.runToEnd(work)
+		runToEnd: (name, work) => control.runToEnd(name, work),
+		ports: ports(),
+		clock,
+		files: classified,
+		spawn: contextSpawn(spawn, {
+			cwd: base.cwd,
+			env: base.env,
+			signal: control.signal
+		}, callerLine),
+		project,
+		poll: (check, { intervalMs }) => poll(clock, check, intervalMs, control.signal),
+		deliver: (data) => {
+			delivered = deliveredOutcome(command, data);
+		}
 	};
+	let served = false;
 	let settled;
 	try {
 		settled = {
@@ -7336,24 +8261,35 @@ async function runCommand(routed, { base, signal, format: baseFormat }) {
 			outcome: await control.settle(execute(command, input, ctx, {
 				dryRun: flags.dryRun,
 				confirm: flags.confirm,
+				yes: flags.yes,
+				force: flags.force,
 				page: flags.page,
 				invocation,
-				commandLine
+				commandLine,
+				started: async (outcome) => {
+					writeStdout(await startedOutput(outcome, format, spill));
+					served = true;
+				}
 			}))
 		};
 	} catch (error) {
+		if (served && control.signal.aborted) return STOPPED_RESULT;
 		settled = {
 			ok: false,
 			error: control.errorAfter(error),
-			render: renderOf(command)
+			delivered
 		};
 	}
 	return commandResult(settled, {
 		...format,
 		fields: flags.fields
-	});
+	}, spill);
+}
+function portsOf(cli, replacement) {
+	if (replacement !== void 0) return () => replacement;
+	return cli.ports ?? (() => ({}));
 }
-async function runWithProgress(cli, argv, options, writeProgress) {
+async function runWithProgress(cli, argv, options, write) {
 	const format = {
 		cliName: cli.name,
 		env: options.env,
@@ -7362,40 +8298,51 @@ async function runWithProgress(cli, argv, options, writeProgress) {
 			cliName: cli.name,
 			argv
 		},
-		json: false
+		json: false,
+		errors: cli.errors ?? {},
+		stop: options.signal
 	};
+	const builtIns = cli.commands === void 0 ? {} : builtInCommands(cli, options.bin);
 	const root = cli.commands === void 0 ? commandSpec(cli.name, cli.command) : groupSpec(cli.name, {
 		...cli.commands,
-		...builtInCommands(cli, options.bin)
+		...builtIns
 	});
 	const routed = route(root, format.invocation);
+	const misused = (node) => isAgent(options.env) ? {
+		...format,
+		usageHelp: textHelp(node, root, cli, format.style)
+	} : format;
 	switch (routed.kind) {
-		case "version": return versionResult(cli);
+		case "version": return versionResult(cli, packageRootOf(options.bin, options.cwd));
 		case "help": return helpResult(routed.node, root, cli, {
 			...format,
 			json: routed.json
 		});
 		case "usage error": return errorResult(routed.error, {
-			...format,
+			...misused(routed.node),
 			json: routed.json
 		});
 		case "command": return runCommand(routed, {
 			base: {
 				cwd: options.cwd,
 				env: options.env,
-				progress: (message) => writeProgress(`${message}\n`)
+				packageRoot: packageRootOf(options.bin, options.cwd),
+				progress: (message) => write.stderr(`${message}\n`),
+				secret: (name) => secretOf(cli.name, options.env, name)
 			},
+			writeStdout: (text) => write.stdout(text),
 			signal: options.signal,
-			format
+			format: misused(routed.spec),
+			ports: portsOf(cli, options.ports),
+			clock: options.clock ?? realClock,
+			files: options.files ?? realFiles(),
+			spawn: options.spawn ?? realSpawn,
+			projectFile: Object.values(builtIns).includes(routed.spec.command) ? void 0 : cli.project
 		});
 	}
 }
 //#endregion
 //#region ../agent-cli/dist/run-process.js
-const SIGNAL_EXIT_CODES = {
-	SIGINT: 130,
-	SIGTERM: 143
-};
 function written(stream, text) {
 	return new Promise((resolve) => stream.write(text, () => resolve()));
 }
@@ -7404,7 +8351,7 @@ async function runProcess(cli) {
 	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();
+		stop.abort(signal);
 	};
 	process.on("SIGINT", onSignal);
 	process.on("SIGTERM", onSignal);
@@ -7415,7 +8362,10 @@ async function runProcess(cli) {
 			stdoutIsTTY: process.stdout.isTTY === true,
 			signal: stop.signal,
 			bin: process.argv[1]
-		}, (line) => process.stderr.write(line));
+		}, {
+			stdout: (text) => process.stdout.write(text),
+			stderr: (text) => process.stderr.write(text)
+		});
 		await written(process.stdout, result.stdout);
 		await written(process.stderr, result.stderr);
 		process.exitCode = result.exitCode;
@@ -7428,11 +8378,13 @@ async function runProcess(cli) {
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "f35d0e3",
-	"dirty": false
+	"sha": "411548a",
+	"dirty": false,
+	"builtAt": "2026-10-19T08:42:00.085Z"
 };
 //#endregion
 //#region src/steps.ts
+const stepErrors = defineErrors({ STEP_FAILED: { class: "operator" } });
 const INSTALL = [{
 	command: "pnpm",
 	args: ["install"]
@@ -7501,11 +8453,9 @@ function tail(output) {
 	return output.trimEnd().split(/\r?\n/).slice(-20).join("\n");
 }
 function stepFailed(problem, left, cwd, cause) {
-	return new CliError({
-		code: "STEP_FAILED",
+	return cliError(stepErrors, "STEP_FAILED", {
 		message: problem,
-		hint: `fix the problem, then run in ${cwd}: ${left.map(stepLine).join(" && ")}`,
-		retryable: false
+		hint: `fix the problem, then run in ${cwd}: ${left.map(stepLine).join(" && ")}`
 	}, { cause });
 }
 /** Runs each step in `cwd` in order, capturing its output so only the Runtime writes to stdout. */
@@ -7559,9 +8509,10 @@ async function writeTemplate(root, files, values) {
 }
 //#endregion
 //#region src/version.ts
-const version = "0.2.1";
+const version = "0.3.0";
 //#endregion
 //#region src/create.ts
+const { defineCommand } = agentCli();
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?([a-z0-9][a-z0-9._-]*)$/;
 function errorCode(error) {
 	return error instanceof Error && "code" in error ? error.code : void 0;
@@ -7582,64 +8533,69 @@ async function ensureFree(path) {
 		hint: "run `create-agent-cli <name>` with a name whose directory is free, or empty it first"
 	});
 }
+const create = defineCommand({
+	name: "create",
+	description: "Create a new Agent CLI project in ./<name>",
+	examples: [{
+		command: "create-agent-cli weather --description \"Weather forecasts\"",
+		note: "create ./weather, install dependencies and make the first commit"
+	}],
+	effect: "write",
+	args: object({ name: string().regex(PACKAGE_NAME, "must be a lowercase npm package name, such as weather or @me/weather").describe("package name; its unscoped part names the bin and the directory") }),
+	options: object({
+		description: string().default("An Agent CLI.").describe("one line saying what the CLI does"),
+		install: boolean().default(true).describe("run pnpm install"),
+		git: boolean().default(true).describe("create a git repository with an initial commit")
+	}),
+	plan: async ({ name, description, install, git }, ctx) => {
+		const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
+		const path = resolve(ctx.cwd, binName);
+		await ensureFree(path);
+		const values = {
+			packageName: name,
+			binName,
+			description,
+			debugVariable: debugVariable(binName),
+			runtimeVersion: version
+		};
+		return {
+			path,
+			values,
+			files: await templateFiles(values),
+			steps: stepsFor({
+				install,
+				git
+			}),
+			install
+		};
+	},
+	apply: async (plan, ctx) => {
+		await mkdir(plan.path, { recursive: true });
+		await writeTemplate(plan.path, plan.files, plan.values);
+		await runSteps(plan.steps, plan.path, ctx);
+		return {
+			path: plan.path,
+			next: `cd ${plan.values.binName} && pnpm ${plan.install ? "test" : "install"}`
+		};
+	},
+	render: ({ path, next }) => `Created ${path}\nnext: ${next}`,
+	renderPlan: (plan) => [
+		`Would create ${plan.path}:`,
+		...plan.files.map((file) => `  create ${file.target}`),
+		...plan.steps.map((step) => `  run ${stepLine(step)}`)
+	].join("\n")
+});
+//#endregion
+//#region src/cli.ts
+const { defineCli } = agentCli();
 //#endregion
 //#region src/bin.ts
 await runProcess(defineCli({
 	name: "create-agent-cli",
 	version,
 	build,
-	command: defineCommand({
-		name: "create",
-		description: "Create a new Agent CLI project in ./<name>",
-		examples: [{
-			command: "create-agent-cli weather --description \"Weather forecasts\"",
-			note: "create ./weather, install dependencies and make the first commit"
-		}],
-		effect: "write",
-		args: object({ name: string().regex(PACKAGE_NAME, "must be a lowercase npm package name, such as weather or @me/weather").describe("package name; its unscoped part names the bin and the directory") }),
-		options: object({
-			description: string().default("An Agent CLI.").describe("one line saying what the CLI does"),
-			install: boolean().default(true).describe("run pnpm install"),
-			git: boolean().default(true).describe("create a git repository with an initial commit")
-		}),
-		plan: async ({ name, description, install, git }, ctx) => {
-			const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
-			const path = resolve(ctx.cwd, binName);
-			await ensureFree(path);
-			const values = {
-				packageName: name,
-				binName,
-				description,
-				debugVariable: debugVariable(binName),
-				runtimeVersion: version
-			};
-			return {
-				path,
-				values,
-				files: await templateFiles(values),
-				steps: stepsFor({
-					install,
-					git
-				}),
-				install
-			};
-		},
-		apply: async (plan, ctx) => {
-			await mkdir(plan.path, { recursive: true });
-			await writeTemplate(plan.path, plan.files, plan.values);
-			await runSteps(plan.steps, plan.path, ctx);
-			return {
-				path: plan.path,
-				next: `cd ${plan.values.binName} && pnpm ${plan.install ? "test" : "install"}`
-			};
-		},
-		render: ({ path, next }) => `Created ${path}\nnext: ${next}`,
-		renderPlan: (plan) => [
-			`Would create ${plan.path}:`,
-			...plan.files.map((file) => `  create ${file.target}`),
-			...plan.steps.map((step) => `  run ${stepLine(step)}`)
-		].join("\n")
-	})
+	errors: stepErrors,
+	command: create
 }));
 //#endregion
 export {};