@duyquangnvx/create-agent-cli 0.5.0 → 0.6.0

package/dist/bin.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { parseArgs, parseEnv } from "node:util";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { access, chmod, link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { constants, existsSync, readFileSync, realpathSync } from "node:fs";
+import { access, chmod, link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { constants as constants$1, homedir, tmpdir } from "node:os";
 import { spawn } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -2425,6 +2425,138 @@ function handleIntersectionResults(result, left, right) {
 	result.value = merged.data;
 	return result;
 }
+const $ZodRecord = /*@__PURE__*/ $constructor("$ZodRecord", (inst, def) => {
+	$ZodType.init(inst, def);
+	const memo = globalConfig.memoizer;
+	memo?.attach(inst);
+	inst._zod.parse = (payload, ctx) => {
+		const input = payload.value;
+		if (!isPlainObject(input)) {
+			payload.issues.push({
+				expected: "record",
+				code: "invalid_type",
+				input,
+				inst
+			});
+			return payload;
+		}
+		const proms = [];
+		const values = def.keyType._zod.values;
+		if (values && !def.partial) {
+			payload.value = memo ? memo.alloc(inst, payload, {}, ctx) : {};
+			const recordKeys = /* @__PURE__ */ new Set();
+			for (const key of values) if (typeof key === "string" || typeof key === "number" || typeof key === "symbol") {
+				recordKeys.add(typeof key === "number" ? key.toString() : key);
+				if (key === "__proto__") continue;
+				const keyResult = def.keyType._zod.run({
+					value: key,
+					issues: []
+				}, ctx);
+				if (keyResult instanceof Promise) throw new Error("Async schemas not supported in object keys currently");
+				if (keyResult.issues.length) {
+					payload.issues.push({
+						code: "invalid_key",
+						origin: "record",
+						issues: keyResult.issues.map((iss) => finalizeIssue(iss, ctx, config())),
+						input: key,
+						path: [key],
+						inst
+					});
+					continue;
+				}
+				const outKey = keyResult.value;
+				if (outKey === "__proto__") continue;
+				const result = def.valueType._zod.run({
+					value: input[key],
+					issues: []
+				}, ctx);
+				if (result instanceof Promise) proms.push(result.then((result) => {
+					if (result.issues.length) payload.issues.push(...prefixIssues(key, result.issues));
+					payload.value[outKey] = result.value;
+				}));
+				else {
+					if (result.issues.length) payload.issues.push(...prefixIssues(key, result.issues));
+					payload.value[outKey] = result.value;
+				}
+			}
+			let unrecognized;
+			for (const key in input) if (!recordKeys.has(key)) {
+				if (def.mode === "loose") {
+					if (key === "__proto__") continue;
+					payload.value[key] = input[key];
+				} else {
+					unrecognized = unrecognized ?? [];
+					unrecognized.push(key);
+				}
+			}
+			if (unrecognized && unrecognized.length > 0) payload.issues.push({
+				code: "unrecognized_keys",
+				input,
+				inst,
+				keys: unrecognized,
+				continue: true
+			});
+		} else {
+			payload.value = memo ? memo.alloc(inst, payload, {}, ctx) : {};
+			let unrecognized;
+			for (const key of Reflect.ownKeys(input)) {
+				if (key === "__proto__") continue;
+				if (!Object.prototype.propertyIsEnumerable.call(input, key)) continue;
+				let keyResult = def.keyType._zod.run({
+					value: key,
+					issues: []
+				}, ctx);
+				if (keyResult instanceof Promise) throw new Error("Async schemas not supported in object keys currently");
+				if (typeof key === "string" && number$1.test(key) && keyResult.issues.length) {
+					const retryResult = def.keyType._zod.run({
+						value: Number(key),
+						issues: []
+					}, ctx);
+					if (retryResult instanceof Promise) throw new Error("Async schemas not supported in object keys currently");
+					if (retryResult.issues.length === 0) keyResult = retryResult;
+				}
+				if (keyResult.issues.length) {
+					if (def.mode === "loose") payload.value[key] = input[key];
+					else if (values) {
+						unrecognized = unrecognized ?? [];
+						unrecognized.push(key);
+					} else payload.issues.push({
+						code: "invalid_key",
+						origin: "record",
+						issues: keyResult.issues.map((iss) => finalizeIssue(iss, ctx, config())),
+						input: key,
+						path: [key],
+						inst
+					});
+					continue;
+				}
+				const outKey = keyResult.value;
+				if (outKey === "__proto__") continue;
+				const result = def.valueType._zod.run({
+					value: input[key],
+					issues: []
+				}, ctx);
+				if (result instanceof Promise) proms.push(result.then((result) => {
+					if (result.issues.length) payload.issues.push(...prefixIssues(key, result.issues));
+					payload.value[outKey] = result.value;
+				}));
+				else {
+					if (result.issues.length) payload.issues.push(...prefixIssues(key, result.issues));
+					payload.value[outKey] = result.value;
+				}
+			}
+			if (unrecognized && unrecognized.length > 0) payload.issues.push({
+				code: "unrecognized_keys",
+				input,
+				inst,
+				keys: unrecognized,
+				continue: true
+			});
+		}
+		if (proms.length) return Promise.all(proms).then(() => payload);
+		return payload;
+	};
+});
 const $ZodEnum = /*@__PURE__*/ $constructor("$ZodEnum", (inst, def) => {
 	$ZodType.init(inst, def);
 	const values = getEnumValues(def.entries);
@@ -5093,6 +5225,9 @@ const ZodURL = /*@__PURE__*/ $constructor("ZodURL", (inst, def) => {
 	$ZodURL.init(inst, def);
 	ZodStringFormat.init(inst, def);
 });
+function url(params) {
+	return /* @__PURE__ */ _url(ZodURL, params);
+}
 const ZodEmoji = /*@__PURE__*/ $constructor("ZodEmoji", (inst, def) => {
 	$ZodEmoji.init(inst, def);
 	ZodStringFormat.init(inst, def);
@@ -5367,6 +5502,28 @@ function intersection(left, right) {
 		right
 	});
 }
+const ZodRecord = /*@__PURE__*/ $constructor("ZodRecord", (inst, def) => {
+	_ensureDefaultMemoizer();
+	$ZodRecord.init(inst, def);
+	ZodType.init(inst, def);
+	inst._zod.processJSONSchema = (ctx, json, params) => recordProcessor(inst, ctx, json, params);
+	inst.keyType = def.keyType;
+	inst.valueType = def.valueType;
+});
+function record(keyType, valueType, params) {
+	if (!valueType || !valueType._zod) return new ZodRecord({
+		type: "record",
+		keyType: string(),
+		valueType: keyType,
+		...normalizeParams(valueType)
+	});
+	return new ZodRecord({
+		type: "record",
+		keyType,
+		valueType,
+		...normalizeParams(params)
+	});
+}
 const ZodEnum = /*@__PURE__*/ $constructor("ZodEnum", (inst, def) => {
 	$ZodEnum.init(inst, def);
 	ZodType.init(inst, def);
@@ -5582,6 +5739,146 @@ function untilAborted(signal) {
 	});
 }
 //#endregion
+//#region ../agent-cli/dist/clock.js
+const realClock = {
+	now: () => Date.now(),
+	sleep: (ms, signal) => new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	})
+};
+/** Runs `then` once `ms` have passed on `clock`; aborting `cancel` drops it. */
+function after(clock, ms, cancel, then) {
+	clock.sleep(ms, cancel).then(then, (error) => {
+		if (!cancel.aborted) throw error;
+	});
+}
+async function poll(clock, check, intervalMs, signal) {
+	for (;;) {
+		signal.throwIfAborted();
+		const value = await check();
+		if (value !== void 0) return value;
+		await clock.sleep(intervalMs, signal);
+	}
+}
+//#endregion
+//#region ../agent-cli/dist/errors.js
+var CliError = class extends Error {
+	code;
+	hint;
+	details;
+	retryAt;
+	constructor({ code, message, hint, details, retryAt }, options) {
+		super(message, options);
+		this.name = "CliError";
+		this.code = code;
+		this.hint = hint;
+		this.details = details;
+		this.retryAt = retryAt;
+	}
+};
+/** The caller called the Agent CLI wrong; the same call can't succeed. */
+var UsageError = class extends CliError {
+	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 errnoOf(error) === "ENOENT";
+}
+function isNothingThere(error) {
+	return isMissingFile(error) || errnoOf(error) === "ENOTDIR";
+}
+function debugVariable(cliName) {
+	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
+}
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isDebug({ env, cliName }) {
+	return Boolean(env[debugVariable(cliName)]);
+}
+function bugHint(format) {
+	const bugs = format.bugs?.();
+	if (isDebug(format)) {
+		const where = "the stack trace shows where it failed";
+		return bugs === void 0 ? where : `${where}; report it at ${bugs}`;
+	}
+	const rerun = `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`;
+	return bugs === void 0 ? rerun : `${rerun}, then report it at ${bugs}`;
+}
+function fieldsOf$1(error, format) {
+	if (error instanceof CliError) {
+		const { code, message, hint, details, retryAt } = error;
+		return {
+			code,
+			message,
+			hint: format.isBug(error) ? bugHint(format) : hint,
+			details,
+			retryAt
+		};
+	}
+	return {
+		code: INTERNAL_CODE,
+		message: messageOf(error),
+		hint: bugHint(format)
+	};
+}
+function causesOf(error) {
+	return error instanceof Error && error.cause !== void 0 ? [error.cause, ...causesOf(error.cause)] : [];
+}
+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: the leaves of nested `AggregateError`s, or the one it threw. An
+* empty `AggregateError` is a leaf.
+*/
+function errorsOf(error) {
+	return error instanceof AggregateError && error.errors.length > 0 ? error.errors.flatMap(errorsOf) : [error];
+}
+function errorLines(error, format) {
+	const fields = fieldsOf$1(error, format);
+	const stack = debugTrace(error, format);
+	const { style } = format;
+	const label = style.red(format.isBug(error) ? "internal error:" : "error:");
+	const trace = stack === void 0 ? "" : `${stack}\n`;
+	return `${label} ${fields.message}\n${trace}${style.cyan("hint:")} ${fields.hint}\n`;
+}
+function formatRuntimeError(error, format) {
+	const errors = errorsOf(error);
+	if (format.json) {
+		const printed = errors.map((each) => ({
+			...fieldsOf$1(each, format),
+			stack: debugTrace(each, format)
+		}));
+		return `${JSON.stringify({ errors: printed })}\n`;
+	}
+	return errors.map((each) => errorLines(each, format)).join("");
+}
+//#endregion
 //#region ../agent-cli/dist/stdin.js
 const STDIN_META = "stdin";
 function isStdinSchema(schema) {
@@ -5597,13 +5894,37 @@ function readingLine(name, platform) {
 function isTerminal(source) {
 	return typeof source !== "string" && "isTTY" in source && source.isTTY === true;
 }
-/** The whole of `source` as UTF-8; rejects with the signal's reason once it aborts. */
-function readStdin(source, signal) {
+const STDIN_STALLED = "STDIN_STALLED";
+/** How long a stdin that is not a terminal may send nothing, from the start of the read and from each chunk. */
+const STDIN_IDLE_MS = 3e4;
+function stdinStalled(callerLine) {
+	return new CliError({
+		code: STDIN_STALLED,
+		message: `stdin sent nothing for ${STDIN_IDLE_MS} ms`,
+		hint: `stdin never ended: close the pipe or heredoc that feeds \`${callerLine}\`, pass the text as an argument instead, or write a slow producer's output to a file and redirect it in`
+	});
+}
+/**
+* The whole of `source` as UTF-8; rejects with the signal's reason once it aborts, and with
+* `idle.stalled()` once a stream that is not a terminal sends nothing for `STDIN_IDLE_MS`.
+*/
+function readStdin(source, signal, idle) {
 	if (typeof source === "string") return signal.aborted ? Promise.reject(signal.reason) : Promise.resolve(source);
 	return new Promise((resolve, reject) => {
 		const chunks = [];
+		let idleWindow = new AbortController();
+		const watchIdle = () => {
+			idleWindow.abort();
+			idleWindow = new AbortController();
+			if (isTerminal(source)) return;
+			after(idle.clock, STDIN_IDLE_MS, idleWindow.signal, () => {
+				stop();
+				reject(idle.stalled());
+			});
+		};
 		const onData = (chunk) => {
 			chunks.push(chunk instanceof Uint8Array ? chunk : Buffer.from(String(chunk)));
+			watchIdle();
 		};
 		const onEnd = () => {
 			stop();
@@ -5620,12 +5941,14 @@ function readStdin(source, signal) {
 		const stop = () => {
 			source.off("data", onData).off("end", onEnd).off("error", onError).pause();
 			signal.removeEventListener("abort", onAbort);
+			idleWindow.abort();
 		};
 		if (signal.aborted) {
 			reject(signal.reason);
 			return;
 		}
 		signal.addEventListener("abort", onAbort, { once: true });
+		watchIdle();
 		source.on("data", onData).once("end", onEnd).once("error", onError);
 	});
 }
@@ -5699,11 +6022,11 @@ function optionField(key, schema) {
 		usage
 	};
 }
-function fieldsOf$1(schema, toField) {
+function fieldsOf(schema, toField) {
 	return schema === void 0 ? [] : Object.entries(schema.shape).map(([key, value]) => toField(key, value));
 }
 function argFields(schema) {
-	return fieldsOf$1(schema, argField);
+	return fieldsOf(schema, argField);
 }
 function keysOf(fields) {
 	return fields.map(({ key }) => `'${key}'`).join(", ");
@@ -5724,7 +6047,7 @@ function checkStdinFields(name, args, options) {
 	}
 }
 function optionFields(schema) {
-	return fieldsOf$1(schema, optionField);
+	return fieldsOf(schema, optionField);
 }
 /** Throws when an option is an array of booleans, which a switch cannot express. */
 function checkNoBooleanArrayOption(name, options) {
@@ -5732,116 +6055,19 @@ function checkNoBooleanArrayOption(name, options) {
 	if (booleans.length > 0) throw new Error(`Command '${name}' declares boolean array option ${keysOf(booleans)}; a switch cannot repeat, use a boolean`);
 }
 //#endregion
-//#region ../agent-cli/dist/errors.js
-var CliError = class extends Error {
-	code;
-	hint;
-	details;
-	retryAt;
-	constructor({ code, message, hint, details, retryAt }, options) {
-		super(message, options);
-		this.name = "CliError";
-		this.code = code;
-		this.hint = hint;
-		this.details = details;
-		this.retryAt = retryAt;
-	}
-};
-/** The caller called the Agent CLI wrong; the same call can't succeed. */
-var UsageError = class extends CliError {
-	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 errnoOf(error) === "ENOENT";
-}
-function isNothingThere(error) {
-	return isMissingFile(error) || errnoOf(error) === "ENOTDIR";
-}
-function debugVariable(cliName) {
-	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
-}
-function messageOf(error) {
-	return error instanceof Error ? error.message : String(error);
-}
-function isDebug({ env, cliName }) {
-	return Boolean(env[debugVariable(cliName)]);
+//#region ../agent-cli/dist/tokenize.js
+const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
+function isOptionLike(word) {
+	return word !== void 0 && word.length > 1 && word[0] === "-" && !NEGATIVE_NUMBER.test(word);
 }
-function bugHint(format) {
-	return isDebug(format) ? "the stack trace shows where it failed" : `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`;
+function parseArgsOptions(known) {
+	return Object.fromEntries(known.map(({ flag, takes }) => [flag.slice(2), { type: takes === "value" ? "string" : "boolean" }]));
 }
-function fieldsOf(error, format) {
-	if (error instanceof CliError) {
-		const { code, message, hint, details, retryAt } = error;
-		return {
-			code,
-			message,
-			hint: format.isBug(error) ? bugHint(format) : hint,
-			details,
-			retryAt
-		};
-	}
-	return {
-		code: INTERNAL_CODE,
-		message: messageOf(error),
-		hint: bugHint(format)
-	};
-}
-function causesOf(error) {
-	return error instanceof Error && error.cause !== void 0 ? [error.cause, ...causesOf(error.cause)] : [];
-}
-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(format.isBug(error) ? "internal error:" : "error:");
-	const trace = stack === void 0 ? "" : `${stack}\n`;
-	return `${label} ${fields.message}\n${trace}${style.cyan("hint:")} ${fields.hint}\n`;
-}
-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("");
-}
-//#endregion
-//#region ../agent-cli/dist/tokenize.js
-const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
-function isOptionLike(word) {
-	return word !== void 0 && word.length > 1 && word[0] === "-" && !NEGATIVE_NUMBER.test(word);
-}
-function parseArgsOptions(known) {
-	return Object.fromEntries(known.map(({ flag, takes }) => [flag.slice(2), { type: takes === "value" ? "string" : "boolean" }]));
-}
-function flagItem(token, { flag, takes }, words) {
-	if (takes !== "optional value" || token.inlineValue === true) return {
-		kind: "flag",
-		flag,
-		value: token.value ?? true
+function flagItem(token, { flag, takes }, words) {
+	if (takes !== "optional value" || token.inlineValue === true) return {
+		kind: "flag",
+		flag,
+		value: token.value ?? true
 	};
 	const took = token.index + 1;
 	const next = words[took];
@@ -5986,6 +6212,18 @@ function unknownOptionError(commandLine, invocation, flag, suggestions) {
 		listed: "options"
 	});
 }
+/** Text opening with `-` was read as an option, where the Command could have read it from stdin. */
+function stdinTextError(commandLine, invocation, word) {
+	const withStdin = commandLineOf(invocation, {
+		remove: [word],
+		add: ["-"]
+	});
+	return new UsageError({
+		code: UNKNOWN_OPTION,
+		message: `unknown option '${word}' for \`${commandLine}\``,
+		hint: `to pass text opening with \`-\`, pass \`-\` and send the text on stdin through a heredoc: \`${withStdin} <<'EOF'\`, then the text, then \`EOF\``
+	});
+}
 function unknownCommandError(commandLine, name, suggestions) {
 	return unknownError({
 		code: UNKNOWN_COMMAND,
@@ -6012,7 +6250,7 @@ const COLUMN_SEPARATOR = "	";
 const UNSAFE_IN_COLUMN = /[\t\n\r]/;
 const PAGE_INPUT = object({
 	limit: number().int().positive().default(DEFAULT_PAGE_LIMIT),
-	cursor: number().int().nonnegative().optional()
+	cursor: string().min(1).optional()
 });
 var Page = class {
 	items;
@@ -6100,12 +6338,16 @@ function cell(value) {
 function renderRows(rows, fields) {
 	return `${[fields, ...rows.map((row) => fields.map((field) => cell(row[field])))].map((line) => line.join(COLUMN_SEPARATOR)).join("\n")}\n`;
 }
+function cursorWords(cursor) {
+	const { flag } = PAGE_FLAGS.cursor;
+	return cursor.startsWith("-") ? [`${flag}=${cursor}`] : [flag, cursor];
+}
 function printedPage(page, invocation) {
 	return page.nextCursor === void 0 ? { items: page.items } : {
 		items: page.items,
 		next: commandLineOf(invocation, {
 			remove: [PAGE_FLAGS.cursor.flag],
-			add: [PAGE_FLAGS.cursor.flag, String(page.nextCursor)]
+			add: cursorWords(page.nextCursor)
 		})
 	};
 }
@@ -6234,71 +6476,50 @@ function isCommand(node) {
 	return typeof node.effect === "string";
 }
 //#endregion
-//#region ../agent-cli/dist/semver.js
-const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
-const ENGINE = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
-function isVersion(text) {
-	return VERSION.test(text);
-}
-function compareIdentifiers(x, y) {
-	const xNumeric = /^\d+$/.test(x);
-	const yNumeric = /^\d+$/.test(y);
-	if (xNumeric && yNumeric) return Number(x) - Number(y);
-	if (xNumeric !== yNumeric) return xNumeric ? -1 : 1;
-	if (x === y) return 0;
-	return x < y ? -1 : 1;
+//#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 comparePrerelease(a, b) {
-	if (a === b) return 0;
-	if (a === void 0) return 1;
-	if (b === void 0) return -1;
-	const left = a.split(".");
-	const right = b.split(".");
-	for (let i = 0; i < Math.min(left.length, right.length); i += 1) {
-		const difference = compareIdentifiers(left[i] ?? "", right[i] ?? "");
-		if (difference !== 0) return difference;
+function readText(path, fileError) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return void 0;
+		throw fileError(error, {
+			path,
+			access: "read"
+		});
 	}
-	return left.length - right.length;
 }
-/** Negative when `a` is older than `b`, positive when newer, 0 when the same release. */
-function compareVersions(a, b) {
-	const left = VERSION.exec(a);
-	const right = VERSION.exec(b);
-	if (left === null || right === null) throw new Error(`cannot compare ${a} with ${b}: both must be X.Y.Z versions`);
-	for (const part of [
-		1,
-		2,
-		3
-	]) {
-		const difference = Number(left[part]) - Number(right[part]);
-		if (difference !== 0) return difference;
+function parsed(path, text, schema) {
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch (error) {
+		throw invalid(path, messageOf(error), { cause: error });
 	}
-	return comparePrerelease(left[4], right[4]);
-}
-/** Where `version` stands against `latest`. */
-function standingOf(version, latest) {
-	const difference = compareVersions(version, latest);
-	if (difference < 0) return "behind";
-	return difference > 0 ? "ahead" : "current";
-}
-/** The minimum an `engines.node` range asks for, or undefined when it is not `>=X[.Y[.Z]]`. */
-function engineMinimum(range) {
-	const match = ENGINE.exec(range.trim());
-	return match === null ? void 0 : match.slice(1).map((part) => Number(part ?? 0));
+	const result = schema.safeParse(json);
+	if (!result.success) throw invalid(path, prettifyError(result.error));
+	return result.data;
 }
-function meetsMinimum(version, minimum) {
-	const parts = version.split(".").map(Number);
-	for (const [i, wanted] of minimum.entries()) {
-		const found = parts[i] ?? 0;
-		if (found !== wanted) return found > wanted;
-	}
-	return true;
+function projectFrom(projectFile, folder, fileError) {
+	const path = join(folder, projectFile.file);
+	const text = readText(path, fileError);
+	if (text !== void 0) return {
+		root: folder,
+		settings: parsed(path, text, projectFile.schema)
+	};
+	const parent = dirname(folder);
+	return parent === folder ? void 0 : projectFrom(projectFile, parent, fileError);
 }
-//#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");
+/** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
+function projectOf(projectFile, cwd, fileError) {
+	return projectFrom(projectFile, resolve(cwd), fileError);
 }
 //#endregion
 //#region ../agent-cli/dist/tools.js
@@ -6363,6 +6584,18 @@ function toolRows(tools, commands) {
 	}));
 }
 //#endregion
+//#region ../agent-cli/dist/version.js
+/** 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}`;
+}
+//#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/spawn.js
 const TOOL_FAILED = "TOOL_FAILED";
 const STDERR_TAIL_LINES$1 = 20;
@@ -6537,7 +6770,68 @@ function contextSpawn(run, defaults, fileError) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/npm.js
+//#region ../agent-cli/dist/built-ins/semver.js
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const ENGINE = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
+function isVersion(text) {
+	return VERSION.test(text);
+}
+function compareIdentifiers(x, y) {
+	const xNumeric = /^\d+$/.test(x);
+	const yNumeric = /^\d+$/.test(y);
+	if (xNumeric && yNumeric) return Number(x) - Number(y);
+	if (xNumeric !== yNumeric) return xNumeric ? -1 : 1;
+	if (x === y) return 0;
+	return x < y ? -1 : 1;
+}
+function comparePrerelease(a, b) {
+	if (a === b) return 0;
+	if (a === void 0) return 1;
+	if (b === void 0) return -1;
+	const left = a.split(".");
+	const right = b.split(".");
+	for (let i = 0; i < Math.min(left.length, right.length); i += 1) {
+		const difference = compareIdentifiers(left[i] ?? "", right[i] ?? "");
+		if (difference !== 0) return difference;
+	}
+	return left.length - right.length;
+}
+/** Negative when `a` is older than `b`, positive when newer, 0 when the same release. */
+function compareVersions(a, b) {
+	const left = VERSION.exec(a);
+	const right = VERSION.exec(b);
+	if (left === null || right === null) throw new Error(`cannot compare ${a} with ${b}: both must be X.Y.Z versions`);
+	for (const part of [
+		1,
+		2,
+		3
+	]) {
+		const difference = Number(left[part]) - Number(right[part]);
+		if (difference !== 0) return difference;
+	}
+	return comparePrerelease(left[4], right[4]);
+}
+/** Where `version` stands against `latest`. */
+function standingOf(version, latest) {
+	const difference = compareVersions(version, latest);
+	if (difference < 0) return "behind";
+	return difference > 0 ? "ahead" : "current";
+}
+/** The minimum an `engines.node` range asks for, or undefined when it is not `>=X[.Y[.Z]]`. */
+function engineMinimum(range) {
+	const match = ENGINE.exec(range.trim());
+	return match === null ? void 0 : match.slice(1).map((part) => Number(part ?? 0));
+}
+function meetsMinimum(version, minimum) {
+	const parts = version.split(".").map(Number);
+	for (const [i, wanted] of minimum.entries()) {
+		const found = parts[i] ?? 0;
+		if (found !== wanted) return found > wanted;
+	}
+	return true;
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/npm.js
 const REGISTRY_UNREACHABLE = "REGISTRY_UNREACHABLE";
 const REGISTRY_AUTH = "REGISTRY_AUTH";
 const INSTALL_FAILED = "INSTALL_FAILED";
@@ -6714,7 +7008,7 @@ async function latestVersion(ctx) {
 	return version;
 }
 //#endregion
-//#region ../agent-cli/dist/global-install.js
+//#region ../agent-cli/dist/built-ins/global-install.js
 const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
 /** Where npm puts global packages under its global prefix. */
 function globalModulesDir(prefix) {
@@ -6755,46 +7049,671 @@ async function globalInstallOf(bin, ctx) {
 	};
 }
 //#endregion
-//#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 \`${commandLineOf(invocation, {
-		remove: [CONFIRM_FLAG.flag],
-		add: [CONFIRM_FLAG.flag, expected]
-	})}\``;
-	if (given === void 0) throw new UsageError({
-		code: CONFIRMATION_REQUIRED,
-		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
-		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/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 \`${commandLineOf(invocation, { add: [YES_FLAG.flag] })}\``
-	});
+//#region ../agent-cli/dist/manifest.js
+const link$1 = union([string(), object({ url: string() })]).transform((value) => typeof value === "string" ? value : value.url).optional().catch(void 0);
+const manifestSchema = object({
+	repository: link$1,
+	bugs: link$1
+});
+const NO_MANIFEST = {};
+function manifestAt(packageRoot) {
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	} catch {
+		return NO_MANIFEST;
+	}
+	const parsed = manifestSchema.safeParse(manifest);
+	return parsed.success ? parsed.data : NO_MANIFEST;
 }
 //#endregion
-//#region ../agent-cli/dist/agent.js
-const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
-const isSet = (name) => (env) => (env[name] ?? "") !== "";
-const equals = (name, value) => (env) => env[name] === value;
-const MARKERS = [
-	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
-	equals("AGENT", "amp"),
+//#region ../agent-cli/dist/built-ins/skills.js
+const SKILL_DIRS = [[".claude", "skills"], [".agents", "skills"]];
+/** The branch a release moves to the released commit, which holds the skill of that version. */
+const RELEASE_BRANCH$1 = "release";
+const SHORTHAND = /^(?:(?:github:)?[\w.-]+\/[\w.-]+|gitlab:[\w.-]+(?:\/[\w.-]+)+)$/;
+const GIT_URL_PROTOCOLS = /* @__PURE__ */ new Set([
+	"https:",
+	"http:",
+	"ssh:",
+	"git:"
+]);
+const SCP_STYLE = /^[\w.-]+@[\w.-]+:[\w./-]+$/;
+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, version) {
+	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 stated = skillVersionIn(skill);
+	if (stated === void 0 || !isVersion(stated) || !isVersion(version)) return {
+		path,
+		version: stated,
+		state: "unversioned"
+	};
+	return {
+		path,
+		version: stated,
+		state: standingOf(stated, version)
+	};
+}
+async function skillCopies(cliName, version, { cwd, env }) {
+	const paths = [cwd, homeOf(env)].flatMap((root) => SKILL_DIRS.map((dir) => join(root, ...dir, cliName)));
+	const seen = /* @__PURE__ */ new Set();
+	const copies = [];
+	for (const path of paths) {
+		const copy = await copyAt(path, version);
+		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;
+}
+function sourceFromRepository(repository) {
+	if (SHORTHAND.test(repository)) return `${repository}#${RELEASE_BRANCH$1}`;
+	const url = repository.replace(/^git\+/, "");
+	if (!(URL.canParse(url) && GIT_URL_PROTOCOLS.has(new URL(url).protocol)) && !SCP_STYLE.test(url)) return void 0;
+	return `${url.endsWith(".git") ? url : `${url}.git`}#${RELEASE_BRANCH$1}`;
+}
+/** What the installer installs the CLI's skill from: the declared source, else the package's repository. */
+function skillSource({ skill }, packageRoot) {
+	if (skill !== void 0) return skill.source;
+	const { repository } = manifestAt(packageRoot);
+	return repository === void 0 ? void 0 : sourceFromRepository(repository);
+}
+function fixFor(cliName, copies, source) {
+	const has = (wanted) => copies.some(({ state }) => state === wanted);
+	const update = `npx -y skills update ${cliName}`;
+	const add = source === void 0 ? void 0 : `npx -y skills add ${source} --skill ${cliName} -g`;
+	if (copies.length === 0) return add;
+	if (has("unversioned") && add !== void 0) return has("behind") ? `${update} && ${add}` : add;
+	return has("behind") || has("unversioned") ? update : void 0;
+}
+async function skillReport(cli, version, ctx) {
+	const copies = await skillCopies(cli.name, version, ctx);
+	return {
+		copies,
+		fix: fixFor(cli.name, copies, skillSource(cli, ctx.packageRoot))
+	};
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/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, ctx.fileError);
+			} 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, node }) {
+	return {
+		name: "install",
+		advisory: true,
+		run: async (ctx) => {
+			const { install } = cli;
+			if (install === void 0) return ok(`${cli.name} declares no install, so it has no \`update\``);
+			try {
+				return ok(`a global npm install under ${(await globalInstallOf(bin, npmContext(cli, install, ctx, node))).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, node) {
+	return {
+		name: "registry",
+		advisory: true,
+		run: async (ctx) => {
+			const { install } = cli;
+			if (install === void 0) return ok(`${cli.name} declares no registry to compare this build with`);
+			const latest = await latestVersion(npmContext(cli, install, ctx, node));
+			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"
+};
+function describeCopy({ path, version, state }) {
+	return `${path}${version === void 0 ? "" : ` ${version}`} (${SKILL_STATE_NOTES[state]})`;
+}
+function skillRow(cli) {
+	return {
+		name: "skill",
+		run: async (ctx) => {
+			const { copies, fix } = await skillReport(cli, cli.version, ctx);
+			const message = copies.length === 0 ? `no copy of the ${cli.name} skill is installed` : copies.map(describeCopy).join("; ");
+			return fix === void 0 ? ok(message) : {
+				state: "ok",
+				message,
+				fix
+			};
+		}
+	};
+}
+/** Every row `doctor` reports, in order: the fixed rows around the CLI's own and its tools'. */
+function doctorChecks(cli, launch) {
+	return [
+		buildRow(cli),
+		nodeRow(cli),
+		...cli.project === void 0 ? [] : [projectRow(cli.project)],
+		...cli.doctor ?? [],
+		...toolRows(cli.tools ?? [], cli.commands),
+		installRow(cli, launch),
+		registryRow(cli, launch.node),
+		skillRow(cli)
+	];
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/doctor.js
+const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
+const DEFAULT_DEADLINE_MS = 1e4;
+const MS_PER_SECOND = 1e3;
+const MIN_LABEL_WIDTH = 8;
+const reportSchema = object({
+	rows: array(object({
+		check: string(),
+		state: _enum([
+			"ok",
+			"problem",
+			"skipped"
+		]),
+		message: string(),
+		fix: string().optional(),
+		code: string().optional()
+	})),
+	next: array(string())
+});
+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 ${ms / MS_PER_SECOND} s`
+	};
+	if (error instanceof CliError) return {
+		state: "problem",
+		message: `${error.message}; ${error.hint}`,
+		code: error.code
+	};
+	return {
+		state: "problem",
+		message: `the ${check.name} row hit a bug: ${messageOf(error)}`
+	};
+}
+function withSignal(ctx, signal) {
+	return Object.create(ctx, { signal: { value: signal } });
+}
+async function rowOf(check, ctx) {
+	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
+	const signal = ctx.deadline(ms);
+	let finding;
+	try {
+		finding = await Promise.race([Promise.resolve().then(() => check.run(withSignal(ctx, signal))), untilAborted(signal)]);
+	} catch (error) {
+		if (ctx.signal.aborted) return void 0;
+		finding = problemOf(check, error, {
+			signal: ctx.signal,
+			deadline: signal,
+			ms
+		});
+	}
+	return {
+		row: {
+			check: check.name,
+			...finding
+		},
+		advisory: check.advisory === true
+	};
+}
+function nextOf(rows) {
+	return [...new Set(rows.flatMap(({ fix }) => fix === void 0 ? [] : [fix]))];
+}
+function render({ rows, next }, style) {
+	const width = Math.max(MIN_LABEL_WIDTH, ...rows.map(({ check }) => check.length)) + 2;
+	const stateWidth = Math.max(...rows.map(({ state }) => state.length)) + 2;
+	return [...rows.map(({ check, state, message }) => {
+		const label = state === "problem" ? style.red(state) : state;
+		return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
+	}), ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
+}
+function failure(cliName, problems) {
+	const errors = problems.map(({ check, message, fix, code }) => new CliError({
+		code: code ?? "DOCTOR_PROBLEMS",
+		message: `${cliName} doctor found a problem in ${check}: ${message}`,
+		hint: fix === void 0 ? "the row says what is wrong" : `run ${fix}, then run doctor again`
+	}));
+	return new AggregateError(errors);
+}
+/** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
+function doctorCommand(cli, launch) {
+	return defineCommand$1({
+		name: "doctor",
+		description: "check the setup and say what fixes each problem",
+		examples: [{
+			command: `${cli.name} doctor`,
+			note: "check the setup and list the commands that fix it"
+		}, {
+			command: `${cli.name} doctor --json`,
+			note: "get the rows and fixes as data"
+		}],
+		effect: "read",
+		output: reportSchema,
+		run: async (_input, ctx) => {
+			const checked = (await Promise.all(doctorChecks(cli, launch).map((check) => rowOf(check, ctx)))).filter((row) => row !== void 0);
+			const rows = checked.map(({ row }) => row);
+			const report = {
+				rows,
+				next: nextOf(rows)
+			};
+			if (ctx.signal.aborted) {
+				ctx.deliver(report);
+				ctx.signal.throwIfAborted();
+			}
+			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
+			if (problems.length > 0) {
+				ctx.deliver(report);
+				throw failure(cli.name, problems);
+			}
+			return report;
+		},
+		render
+	});
+}
+//#endregion
+//#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"
+	});
+}
+const WAIT_HINT = "run it again later, when the service it waits on may answer faster";
+function deadlineError(commandLine, ms, hint, bound = "deadline") {
+	return new CliError({
+		code: DEADLINE_EXCEEDED,
+		message: `${commandLine} ran past its ${ms} ms ${bound}`,
+		hint
+	});
+}
+/** 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();
+	/** The reasons this run's deadlines and timeouts aborted with, to tell them in a Command's error. */
+	#abortReasons = /* @__PURE__ */ new WeakSet();
+	#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())));
+		}
+	}
+	deadline(ms) {
+		return AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
+	}
+	timeout(ms) {
+		return this.#abortsAfter(ms, "timeout");
+	}
+	#abortsAfter(ms, bound) {
+		const controller = new AbortController();
+		after(this.#clock, ms, this.#disposed.signal, () => {
+			const reason = deadlineError(this.#commandLine, ms, WAIT_HINT, bound);
+			this.#abortReasons.add(reason);
+			controller.abort(reason);
+		});
+		return 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.close();
+		}
+	}
+	/**
+	* The error a run ends with: an interrupt or the run deadline outranks what the Command threw,
+	* unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
+	* Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's or timeout's
+	* abort is reported as that abort, so a declared error keeps its own code.
+	*/
+	errorAfter(error) {
+		if (this.signal.aborted) return error instanceof CliError && error.code === "INTERRUPTED" ? error : this.signal.reason;
+		const leaves = errorsOf(error).map((leaf) => this.#abortIn(leaf) ?? leaf);
+		return leaves.length === 1 ? leaves[0] : new AggregateError(leaves);
+	}
+	#abortIn(error) {
+		if (error instanceof CliError) return void 0;
+		return causesOf(error).find((each) => each instanceof CliError && this.#abortReasons.has(each));
+	}
+	#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());
+	}
+	/** Stops the run's timers and its hold on the caller's signal, for a run that never settles. */
+	close() {
+		this.#graceCancel.abort();
+		this.#disposed.abort();
+		this.#outer?.removeEventListener("abort", this.#onOuterAbort);
+	}
+};
+//#endregion
+//#region ../agent-cli/dist/built-ins/upgrade-notes.js
+const RELEASE_HEADING = /^## v?(\S+)/;
+function releasesIn(changelog) {
+	const releases = [];
+	let current;
+	for (const line of changelog.split(/\r?\n/)) {
+		const heading = RELEASE_HEADING.exec(line);
+		if (heading !== null) {
+			const version = heading[1] ?? "";
+			current = isVersion(version) ? {
+				version,
+				lines: []
+			} : void 0;
+			if (current !== void 0) releases.push(current);
+		} else current?.lines.push(line);
+	}
+	return releases.map(({ version, lines }) => ({
+		version,
+		notes: lines.join("\n").trim()
+	}));
+}
+/**
+* What changed in each release after `from` up to `to`, oldest first, from the CHANGELOG.md in
+* `packageDir`; none when the package ships no CHANGELOG.
+*/
+async function upgradeNotes(packageDir, from, to) {
+	let changelog;
+	try {
+		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return [];
+		throw error;
+	}
+	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version));
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/update.js
+const updateSchema = object({
+	from: string(),
+	latest: string(),
+	installed: object({
+		version: string(),
+		prefix: string()
+	}).nullable(),
+	upgrades: array(object({
+		version: string(),
+		notes: string()
+	})),
+	next: array(string())
+});
+function nothingToInstall({ from, latest }) {
+	return standingOf(from, latest) === "current" ? `already on ${from}, the latest release: nothing to install` : `${from} is newer than the latest release ${latest}: nothing to install`;
+}
+function renderUpdate(cli, install, update) {
+	const { installed } = update;
+	const head = installed === null ? [nothingToInstall(update)] : [`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`, ...update.upgrades.map(({ version, notes }) => `\nchanges in ${version}:\n${notes}`)];
+	const next = update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${update.latest}`);
+	return (next.length === 0 ? head : [
+		...head,
+		"",
+		...next
+	]).join("\n");
+}
+async function skillNext(cli, latest, ctx) {
+	const { fix } = await skillReport(cli, latest, ctx);
+	return fix === void 0 ? [] : [fix];
+}
+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"
+	});
+}
+/** The built-in `update`, for a CLI installed globally with npm. */
+function updateCommand(cli, install, { bin, node }) {
+	return defineCommand$1({
+		name: "update",
+		description: "install the latest version of this CLI from its registry",
+		examples: [{
+			command: `${cli.name} update`,
+			note: "install the latest version and show what changed"
+		}, {
+			command: `${cli.name} update --dry-run`,
+			note: "show the version it would install"
+		}],
+		effect: "write",
+		output: updateSchema,
+		plan: async (_input, ctx) => {
+			const npm = npmContext(cli, install, ctx, node);
+			const copy = await globalInstallOf(bin, npm);
+			return {
+				package: install.package,
+				from: cli.version,
+				latest: await latestVersion(npm),
+				prefix: copy.prefix,
+				packageDir: copy.packageDir
+			};
+		},
+		apply: async (plan, ctx) => {
+			const { from, latest, prefix } = plan;
+			if (standingOf(from, latest) !== "behind") return {
+				from,
+				latest,
+				installed: null,
+				upgrades: [],
+				next: await skillNext(cli, latest, ctx)
+			};
+			ctx.signal.throwIfAborted();
+			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
+			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, npmContext(cli, install, ctx, node)));
+			const update = {
+				from,
+				latest,
+				installed: {
+					version: latest,
+					prefix
+				},
+				upgrades: await upgradeNotes(plan.packageDir, from, latest),
+				next: await skillNext(cli, latest, ctx)
+			};
+			if (ctx.signal.aborted) {
+				ctx.deliver(update);
+				throw interruptedAfterInstall(plan);
+			}
+			return update;
+		},
+		render: (update) => renderUpdate(cli, install, update),
+		renderPlan: (plan) => standingOf(plan.from, plan.latest) === "behind" ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}, replacing ${plan.from}` : nothingToInstall(plan)
+	});
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/commands.js
+/** The Commands the Runtime adds to a multi-Command CLI: `update` only when it declares an install. */
+function builtInCommands(cli, launch) {
+	return {
+		doctor: doctorCommand(cli, launch),
+		...cli.install === void 0 ? {} : { update: updateCommand(cli, cli.install, launch) }
+	};
+}
+//#endregion
+//#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 \`${commandLineOf(invocation, {
+		remove: [CONFIRM_FLAG.flag],
+		add: [CONFIRM_FLAG.flag, expected]
+	})}\``;
+	if (given === void 0) throw new UsageError({
+		code: CONFIRMATION_REQUIRED,
+		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
+		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/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 \`${commandLineOf(invocation, { add: [YES_FLAG.flag] })}\``
+	});
+}
+//#endregion
+//#region ../agent-cli/dist/agent.js
+const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
+const isSet = (name) => (env) => (env[name] ?? "") !== "";
+const equals = (name, value) => (env) => env[name] === value;
+const MARKERS = [
+	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
+	equals("AGENT", "amp"),
 	isSet("CODEX_SANDBOX"),
 	isSet("CODEX_CI"),
 	isSet("CODEX_THREAD_ID"),
@@ -6877,159 +7796,6 @@ function classifyErrno(error, context) {
 	}
 }
 //#endregion
-//#region ../agent-cli/dist/clock.js
-const realClock = {
-	now: () => Date.now(),
-	sleep: (ms, signal) => new Promise((resolve, reject) => {
-		if (signal?.aborted === true) {
-			reject(signal.reason);
-			return;
-		}
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(signal?.reason);
-		};
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		signal?.addEventListener("abort", onAbort, { once: true });
-	})
-};
-/** Runs `then` once `ms` have passed on `clock`; aborting `cancel` drops it. */
-function after(clock, ms, cancel, then) {
-	clock.sleep(ms, cancel).then(then, (error) => {
-		if (!cancel.aborted) throw error;
-	});
-}
-async function poll(clock, check, intervalMs, signal) {
-	for (;;) {
-		signal.throwIfAborted();
-		const value = await check();
-		if (value !== void 0) return value;
-		await clock.sleep(intervalMs, signal);
-	}
-}
-//#endregion
-//#region ../agent-cli/dist/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"
-	});
-}
-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
-	});
-}
-/** 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())));
-		}
-	}
-	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.close();
-		}
-	}
-	/**
-	* 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());
-	}
-	/** Stops the run's timers and its hold on the caller's signal, for a run that never settles. */
-	close() {
-		this.#graceCancel.abort();
-		this.#disposed.abort();
-		this.#outer?.removeEventListener("abort", this.#onOuterAbort);
-	}
-};
-//#endregion
 //#region ../agent-cli/dist/operator.js
 const NEEDS_OPERATOR = "NEEDS_OPERATOR";
 /** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
@@ -7160,12 +7926,19 @@ function realFiles() {
 			force: true
 		}),
 		mkdir: async (path, options) => {
+			const mode = options?.mode;
 			if (options?.exclusive !== true) {
-				await mkdir(path, { recursive: true });
+				await mkdir(path, {
+					recursive: true,
+					mode
+				});
 				return;
 			}
-			await mkdir(dirname(path), { recursive: true });
-			await mkdir(path);
+			await mkdir(dirname(path), {
+				recursive: true,
+				mode
+			});
+			await mkdir(path, { mode });
 		},
 		stat: async (path) => {
 			try {
@@ -7277,52 +8050,6 @@ async function probeOutputs({ files, cwd, fileError }, outputs) {
 	}));
 }
 //#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/exit-classes.js
 const SIGNAL_EXIT_CODES = {
 	SIGINT: 130,
@@ -7335,46 +8062,44 @@ const EXIT_CODES = {
 	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",
-		[NEEDS_OPERATOR]: "operator",
-		[OUTPUT_EXISTS]: "caller",
-		[INTERRUPTED]: "interrupted",
-		[DEADLINE_EXCEEDED]: "wait",
-		[INTERNAL_CODE]: "bug",
-		[PERMISSION_DENIED]: "operator",
-		[DISK_FULL]: "operator",
-		[NOT_FOUND]: "caller",
-		[ALREADY_EXISTS]: "caller",
-		[NOT_A_FILE]: "caller",
-		[TOOL_FAILED]: "operator",
-		[TOOL_MISSING]: "operator",
-		[PROJECT_INVALID]: "operator",
-		[DOCTOR_PROBLEMS]: "operator",
-		[NOT_GLOBAL_INSTALL]: "operator",
-		[REGISTRY_UNREACHABLE]: "operator",
-		[REGISTRY_AUTH]: "operator",
-		[INSTALL_FAILED]: "operator",
-		[NPM_FAILED]: "operator",
-		[NO_LATEST]: "source"
-	};
-}
+const RUNTIME_EXIT_CLASSES = {
+	[INVALID_INPUT]: "caller",
+	[UNKNOWN_OPTION]: "caller",
+	[UNKNOWN_COMMAND]: "caller",
+	[UNKNOWN_FIELD]: "caller",
+	[CONFIRMATION_REQUIRED]: "caller",
+	[CONFIRMATION_MISMATCH]: "caller",
+	[NOT_CONFIRMED]: "operator",
+	[NEEDS_OPERATOR]: "operator",
+	[OUTPUT_EXISTS]: "caller",
+	[STDIN_STALLED]: "caller",
+	[INTERRUPTED]: "interrupted",
+	[DEADLINE_EXCEEDED]: "wait",
+	[INTERNAL_CODE]: "bug",
+	[PERMISSION_DENIED]: "operator",
+	[DISK_FULL]: "operator",
+	[NOT_FOUND]: "caller",
+	[ALREADY_EXISTS]: "caller",
+	[NOT_A_FILE]: "caller",
+	[TOOL_FAILED]: "operator",
+	[TOOL_MISSING]: "operator",
+	[PROJECT_INVALID]: "operator",
+	[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));
+	return Object.keys(errors).filter((code) => Object.hasOwn(RUNTIME_EXIT_CLASSES, 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";
+	return RUNTIME_EXIT_CLASSES[error.code] ?? errors[error.code]?.class ?? "bug";
 }
 function isBug(error, errors) {
 	return exitClassOfOne(error, errors) === "bug";
@@ -7418,6 +8143,50 @@ function exitCodeOf(error, errors, stop) {
 	return exitClass === "interrupted" ? SIGNAL_EXIT_CODES[stopSignalOf(stop?.reason)] : EXIT_CODES[exitClass];
 }
 //#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, {
+		bin: void 0,
+		node: void 0
+	})).filter((name) => commands[name] !== void 0);
+	if (taken.length > 0) throw new Error(`${cli.name} defines ${taken.join(", ")}, a built-in Command it cannot replace`);
+	return cli;
+}
+/**
+* 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 {
+		defineCommand: defineCommandFor(),
+		defineCli: defineCli$1
+	};
+}
+//#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;
+}
+/**
+* A `CliError` for a code of `table`, whose `details` must match the code's schema. The `hint`
+* names the next command to run and says whether running it again can help; `retryAt` (ISO 8601)
+* is allowed only on a wait-class code.
+*/
+function cliError(_table, code, init, options) {
+	return new CliError({
+		...init,
+		code
+	}, options);
+}
+//#endregion
 //#region ../agent-cli/dist/command-spec.js
 /** The group's Commands and groups that help and suggestions may name: hidden Commands left out. */
 function visibleCommands({ commands }) {
@@ -7435,12 +8204,18 @@ function declaredOf(command) {
 		cost: command.cost !== void 0
 	};
 }
-function commandSpec(commandLine, command) {
+const SINGLE_COMMAND = {
+	path: [],
+	builtIn: false
+};
+function commandSpec(commandLine, command, { path, builtIn } = SINGLE_COMMAND) {
 	const list = command.rows === void 0 ? void 0 : listSpec(command.rows);
 	return {
 		kind: "command",
 		commandLine,
+		path,
 		command,
+		builtIn,
 		description: command.description,
 		help: command.help,
 		hidden: command.hidden === true,
@@ -7454,15 +8229,34 @@ function commandSpec(commandLine, command) {
 		output: list?.output ?? command.output
 	};
 }
-function groupSpec(commandLine, commands) {
+function group(commandLine, commands) {
 	return {
 		kind: "group",
 		commandLine,
-		commands: Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node)]))
+		commands
 	};
 }
-function specOf(commandLine, node) {
-	return isCommand(node) ? commandSpec(commandLine, node) : groupSpec(commandLine, node);
+/** The root group of a multi-Command CLI: the author's Commands, then the Built-in Commands. */
+function groupSpec(commandLine, commands, builtIns) {
+	return group(commandLine, {
+		...specsOf(commandLine, commands, {
+			path: [],
+			builtIn: false
+		}),
+		...specsOf(commandLine, builtIns, {
+			path: [],
+			builtIn: true
+		})
+	});
+}
+function specsOf(commandLine, commands, { path, builtIn }) {
+	return Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node, {
+		path: [...path, key],
+		builtIn
+	})]));
+}
+function specOf(commandLine, node, place) {
+	return isCommand(node) ? commandSpec(commandLine, node, place) : group(commandLine, specsOf(commandLine, node, place));
 }
 //#endregion
 //#region ../agent-cli/dist/help.js
@@ -7487,9 +8281,10 @@ function commandRows(group) {
 function lines(...parts) {
 	return `${parts.join("\n")}\n`;
 }
-function listingLines(heading, group, style) {
+function listingLines(heading, group, style, description) {
 	return [
 		style.bold(heading),
+		...description === void 0 ? [] : [description],
 		...section("Commands", commandRows(group), style),
 		"",
 		`Run \`${group.commandLine} <command> --help\` for its examples and input.`
@@ -7522,7 +8317,7 @@ function examplesSection(examples, 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));
+	return lines(...root.kind === "command" ? commandLines(root, style, { examples: false }) : listingLines(`${root.commandLine} ${cli.version}`, root, style, cli.description), ...section("Exit codes", exitCodeRows(cli), style), ...examplesSection(rootExamples(root), style));
 }
 function groupHelp(group, style) {
 	return lines(...listingLines(group.commandLine, group, style));
@@ -7620,10 +8415,11 @@ function errorsData(errors) {
 		details: declaration.details === void 0 ? null : toJSONSchema(declaration.details, { unrepresentable: "any" })
 	}]));
 }
-function cliHelpJson({ version, errors }, root) {
+function cliHelpJson({ version, description, errors }, root) {
 	return printed$1({
 		name: root.commandLine,
 		version,
+		description,
 		...nodeData(root),
 		errors: errorsData(errors ?? {})
 	});
@@ -7656,619 +8452,215 @@ function progressLine(message, json) {
 }
 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/skill-source.js
-/** The branch a release moves to the released commit, which holds the skill of that version. */
-const RELEASE_BRANCH = "release";
-const GITHUB_SHORTHAND = /^[\w.-]+\/[\w.-]+$/;
-const GIT_URL_PROTOCOLS = /* @__PURE__ */ new Set([
-	"https:",
-	"http:",
-	"ssh:",
-	"git:"
-]);
-const SCP_STYLE = /^[\w.-]+@[\w.-]+:[\w./-]+$/;
-const manifestSchema = object({ repository: union([string(), object({ url: string() })]).optional() });
-function sourceFromRepository(repository) {
-	if (GITHUB_SHORTHAND.test(repository)) return repository;
-	const url = repository.replace(/^git\+/, "");
-	if (!(URL.canParse(url) && GIT_URL_PROTOCOLS.has(new URL(url).protocol)) && !SCP_STYLE.test(url)) return void 0;
-	return `${url.endsWith(".git") ? url : `${url}.git`}#${RELEASE_BRANCH}`;
-}
-async function repositoryAt(packageRoot) {
-	let manifest;
-	try {
-		manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
-	} catch {
-		return;
-	}
-	const parsed = manifestSchema.safeParse(manifest);
-	const repository = parsed.success ? parsed.data.repository : void 0;
-	return typeof repository === "object" ? repository.url : repository;
-}
-/** What `npx skills add` installs the CLI's skill from: the declared source, else the package's repository. */
-async function skillSource(declared, packageRoot) {
-	if (declared !== void 0) return declared.source;
-	const repository = await repositoryAt(packageRoot);
-	return repository === void 0 ? void 0 : sourceFromRepository(repository);
-}
-//#endregion
-//#region ../agent-cli/dist/skills.js
-/** Where the skills CLI (`npx skills add`) puts a skill, under a project and under home. */
-const SKILL_DIRS = [[".claude", "skills"], [".agents", "skills"]];
-function skillUpdateCommand(cliName) {
-	return `npx -y skills update ${cliName}`;
-}
-function skillAddCommand(source, cliName) {
-	return `npx -y skills add ${source} --skill ${cliName} -g`;
-}
-const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
-const METADATA_VERSION = /^metadata:[ \t]*\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$/m;
-/** The version a SKILL.md's frontmatter `metadata.version` states. */
-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, node }) {
-	return {
-		name: "install",
-		advisory: true,
-		run: async (ctx) => {
-			const { install } = cli;
-			if (install === void 0) return ok(`${cli.name} declares no install, so it has no \`update\``);
-			try {
-				return ok(`a global npm install under ${(await globalInstallOf(bin, npmContext(cli, install, ctx, node))).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, node) {
-	return {
-		name: "registry",
-		advisory: true,
-		run: async (ctx) => {
-			const { install } = cli;
-			if (install === void 0) return ok(`${cli.name} declares no registry to compare this build with`);
-			const latest = await latestVersion(npmContext(cli, install, ctx, node));
-			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"
-};
-function describeCopy({ path, version, state }) {
-	return `${path}${version === void 0 ? "" : ` ${version}`} (${SKILL_STATE_NOTES[state]})`;
-}
-function skillFix(cli, copies) {
-	if (copies.some(({ state }) => state === "behind" || state === "unversioned")) return skillUpdateCommand(cli.name);
-	return copies.some(({ state }) => state === "ahead") ? `${cli.name} update` : void 0;
+		...format,
+		isBug: (each) => isBug(each, format.errors)
+	});
+	const { usageHelp, json } = format;
+	return usageHelp !== void 0 && !json && error instanceof UsageError ? `${text}\n${usageHelp}` : text;
 }
-function skillRow(cli) {
-	return {
-		name: "skill",
-		run: async (ctx) => {
-			const copies = await skillCopies(cli.name, cli.version, ctx.cwd, ctx.env);
-			if (copies.length === 0) {
-				const message = `no copy of the ${cli.name} skill is installed`;
-				const source = await skillSource(cli.skill, ctx.packageRoot);
-				return source === void 0 ? ok(message) : {
-					state: "ok",
-					message,
-					fix: skillAddCommand(source, cli.name)
-				};
-			}
-			const fix = skillFix(cli, copies);
-			const message = copies.map(describeCopy).join("; ");
-			return fix === void 0 ? ok(message) : {
-				state: "ok",
-				message,
-				fix
-			};
-		}
-	};
+function stdoutOf({ value, render }, format, spill) {
+	const text = printed(value, render, format);
+	return value instanceof Page ? text : spill(text, format.json);
 }
-/** Every row `doctor` reports, in order: the fixed rows around the CLI's own and its tools'. */
-function doctorChecks(cli, launch) {
-	return [
-		buildRow(cli),
-		nodeRow(cli),
-		...cli.project === void 0 ? [] : [projectRow(cli.project)],
-		...cli.doctor ?? [],
-		...toolRows(cli.tools ?? [], cli.commands),
-		installRow(cli, launch),
-		registryRow(cli, launch.node),
-		skillRow(cli)
-	];
+/** What a serve Command prints the moment it starts. */
+function startedOutput(outcome, format, spill) {
+	return stdoutOf(outcome, {
+		...format,
+		fields: void 0
+	}, spill);
 }
-//#endregion
-//#region ../agent-cli/dist/doctor.js
-const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
-const DEFAULT_DEADLINE_MS = 1e4;
-const MS_PER_SECOND = 1e3;
-const MIN_LABEL_WIDTH = 8;
-const reportSchema = object({
-	rows: array(object({
-		check: string(),
-		state: _enum([
-			"ok",
-			"problem",
-			"skipped"
-		]),
-		message: string(),
-		fix: string().optional(),
-		code: string().optional()
-	})),
-	next: array(string())
-});
-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 ${ms / MS_PER_SECOND} s`
-	};
-	if (error instanceof CliError) return {
-		state: "problem",
-		message: `${error.message}; ${error.hint}`,
-		code: error.code
-	};
+/** 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 {
-		state: "problem",
-		message: `the ${check.name} row hit a bug: ${messageOf(error)}`
+		stdout: "",
+		stderr: errorText(error, format),
+		exitCode: exitCodeOf(error, format.errors, format.stop)
 	};
 }
-function withSignal(ctx, signal) {
-	return Object.create(ctx, { signal: { value: signal } });
-}
-async function rowOf(check, ctx) {
-	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
-	const signal = ctx.deadline(ms);
-	let finding;
+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 {
-		finding = await Promise.race([Promise.resolve().then(() => check.run(withSignal(ctx, signal))), untilAborted(signal)]);
-	} catch (error) {
-		if (ctx.signal.aborted) return void 0;
-		finding = problemOf(check, error, {
-			signal: ctx.signal,
-			deadline: signal,
-			ms
-		});
+		return {
+			...result,
+			stdout: await stdoutOf(delivered, format, spill)
+		};
+	} catch (spillError) {
+		const both = new AggregateError([...errorsOf(error), spillError]);
+		return {
+			...result,
+			stderr: errorText(both, format)
+		};
 	}
-	return {
-		row: {
-			check: check.name,
-			...finding
-		},
-		advisory: check.advisory === true
-	};
 }
-function nextOf(rows) {
-	return [...new Set(rows.flatMap(({ fix }) => fix === void 0 ? [] : [fix]))];
+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 render({ rows, next }, style) {
-	const width = Math.max(MIN_LABEL_WIDTH, ...rows.map(({ check }) => check.length)) + 2;
-	const stateWidth = Math.max(...rows.map(({ state }) => state.length)) + 2;
-	return [...rows.map(({ check, state, message }) => {
-		const label = state === "problem" ? style.red(state) : state;
-		return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
-	}), ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
+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 failure(cliName, problems) {
-	const errors = problems.map(({ check, message, fix, code }) => new CliError({
-		code: code ?? "DOCTOR_PROBLEMS",
-		message: `${cliName} doctor found a problem in ${check}: ${message}`,
-		hint: fix === void 0 ? "the row says what is wrong" : `run ${fix}, then run doctor again`
-	}));
-	return new AggregateError(errors);
+function helpResult(node, root, cli, { style, json }) {
+	return {
+		stdout: helpOf(node, root, cli, style, json),
+		stderr: "",
+		exitCode: SUCCESS_EXIT_CODE
+	};
 }
-/** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
-function doctorCommand(cli, launch) {
-	return defineCommand$1({
-		name: "doctor",
-		description: "check the setup and say what fixes each problem",
-		examples: [{
-			command: `${cli.name} doctor`,
-			note: "check the setup and list the commands that fix it"
-		}, {
-			command: `${cli.name} doctor --json`,
-			note: "get the rows and fixes as data"
-		}],
-		effect: "read",
-		output: reportSchema,
-		run: async (_input, ctx) => {
-			const checked = (await Promise.all(doctorChecks(cli, launch).map((check) => rowOf(check, ctx)))).filter((row) => row !== void 0);
-			const rows = checked.map(({ row }) => row);
-			const report = {
-				rows,
-				next: nextOf(rows)
-			};
-			if (ctx.signal.aborted) {
-				ctx.deliver(report);
-				ctx.signal.throwIfAborted();
-			}
-			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
-			if (problems.length > 0) {
-				ctx.deliver(report);
-				throw failure(cli.name, problems);
-			}
-			return report;
-		},
-		render
-	});
+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/upgrade-notes.js
-const RELEASE_HEADING = /^## v?(\S+)/;
-function releasesIn(changelog) {
-	const releases = [];
-	let current;
-	for (const line of changelog.split(/\r?\n/)) {
-		const heading = RELEASE_HEADING.exec(line);
-		if (heading !== null) {
-			const version = heading[1] ?? "";
-			current = isVersion(version) ? {
-				version,
-				lines: []
-			} : void 0;
-			if (current !== void 0) releases.push(current);
-		} else current?.lines.push(line);
-	}
-	return releases.map(({ version, lines }) => ({
-		version,
-		notes: lines.join("\n").trim()
-	}));
-}
+//#region ../agent-cli/dist/package-root.js
 /**
-* What changed in each release after `from` up to `to`, oldest first, from the CHANGELOG.md in
-* `packageDir`; none when the package ships no CHANGELOG.
+* 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.
 */
-async function upgradeNotes(packageDir, from, to) {
-	let changelog;
-	try {
-		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return [];
-		throw error;
+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;
 	}
-	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version));
 }
 //#endregion
-//#region ../agent-cli/dist/update.js
-const updateSchema = object({
-	from: string(),
-	latest: string(),
-	installed: object({
-		version: string(),
-		prefix: string()
-	}).nullable(),
-	upgrades: array(object({
-		version: string(),
-		notes: string()
-	})),
-	next: array(string())
-});
-function nothingToInstall({ from, latest }) {
-	return standingOf(from, latest) === "current" ? `already on ${from}, the latest release: nothing to install` : `${from} is newer than the latest release ${latest}: nothing to install`;
+//#region ../agent-cli/dist/suggest.js
+const MAX_DISTANCE = 3;
+const MIN_SIMILARITY = .4;
+function distance(a, b) {
+	const width = b.length + 1;
+	const d = Array.from({ length: (a.length + 1) * width }, (_, k) => {
+		const i = Math.floor(k / width);
+		const j = k % width;
+		return i === 0 || j === 0 ? i + j : 0;
+	});
+	const at = (i, j) => d[i * width + j] ?? 0;
+	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
+		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+		const edit = Math.min(at(i - 1, j) + 1, at(i, j - 1) + 1, at(i - 1, j - 1) + cost);
+		const transposed = i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1];
+		d[i * width + j] = transposed ? Math.min(edit, at(i - 2, j - 2) + 1) : edit;
+	}
+	return at(a.length, b.length);
 }
-function renderUpdate(cli, install, update) {
-	const { installed } = update;
-	if (installed === null) return nothingToInstall(update);
-	return [
-		`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`,
-		...update.upgrades.map(({ version, notes }) => `\nchanges in ${version}:\n${notes}`),
-		"",
-		...update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${installed.version}`)
-	].join("\n");
+function isClose(word, candidate) {
+	const length = Math.max(word.length, candidate.length);
+	const edits = distance(word, candidate);
+	return candidate.length > 1 && edits < MAX_DISTANCE && (length - edits) / length > MIN_SIMILARITY;
 }
-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"
-	});
+/** The names closest to `word`, sorted, several when they tie, or none when nothing is close. */
+function closestNames(word, names) {
+	const close = [...new Set(names)].filter((candidate) => isClose(word, candidate));
+	const best = Math.min(...close.map((candidate) => distance(word, candidate)));
+	return close.filter((candidate) => distance(word, candidate) === best).sort((a, b) => a.localeCompare(b));
 }
-/** The built-in `update`, for a CLI installed globally with npm. */
-function updateCommand(cli, install, { bin, node }) {
-	return defineCommand$1({
-		name: "update",
-		description: "install the latest version of this CLI from its registry",
-		examples: [{
-			command: `${cli.name} update`,
-			note: "install the latest version and show what changed"
-		}, {
-			command: `${cli.name} update --dry-run`,
-			note: "show the version it would install"
-		}],
-		effect: "write",
-		output: updateSchema,
-		plan: async (_input, ctx) => {
-			const npm = npmContext(cli, install, ctx, node);
-			const copy = await globalInstallOf(bin, npm);
-			return {
-				package: install.package,
-				from: cli.version,
-				latest: await latestVersion(npm),
-				prefix: copy.prefix,
-				packageDir: copy.packageDir
-			};
-		},
-		apply: async (plan, ctx) => {
-			const { from, latest, prefix } = plan;
-			if (standingOf(from, latest) !== "behind") return {
-				from,
-				latest,
-				installed: null,
-				upgrades: [],
-				next: []
-			};
-			ctx.signal.throwIfAborted();
-			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
-			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, npmContext(cli, install, ctx, node)));
-			const update = {
-				from,
-				latest,
-				installed: {
-					version: latest,
-					prefix
-				},
-				upgrades: await upgradeNotes(plan.packageDir, from, latest),
-				next: [skillUpdateCommand(cli.name)]
-			};
-			if (ctx.signal.aborted) {
-				ctx.deliver(update);
-				throw interruptedAfterInstall(plan);
-			}
-			return update;
-		},
-		render: (update) => renderUpdate(cli, install, update),
-		renderPlan: (plan) => standingOf(plan.from, plan.latest) === "behind" ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}, replacing ${plan.from}` : nothingToInstall(plan)
-	});
+/** The long flags closest to `flag`, sorted, or none for a short flag or when nothing is close. */
+function closestFlags(flag, flags) {
+	if (!flag.startsWith("--")) return [];
+	const names = flags.map((candidate) => candidate.slice(2));
+	return closestNames(flag.slice(2), names).map((name) => `--${name}`);
 }
-//#endregion
-//#region ../agent-cli/dist/built-ins.js
-/** The Commands the Runtime adds to a multi-Command CLI: `update` only when it declares an install. */
-function builtInCommands(cli, launch) {
-	return {
-		doctor: doctorCommand(cli, launch),
-		...cli.install === void 0 ? {} : { update: updateCommand(cli, cli.install, launch) }
-	};
+/** The one long flag closest to `flag`, or none when nothing is close or several tie. */
+function closestFlag(flag, flags) {
+	const closest = closestFlags(flag, flags);
+	return closest.length === 1 ? closest[0] : void 0;
 }
 //#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`);
+//#region ../agent-cli/dist/route.js
+const GROUP_FLAGS = [
+	HELP_FLAG,
+	VERSION_FLAG,
+	JSON_FLAG.flag
+];
+function beforeEnd(words) {
+	const end = words.indexOf("--");
+	return end === -1 ? words : words.slice(0, end);
 }
-function defineCli$1(cli) {
-	checkOwnCodes(cli);
-	if (cli.commands === void 0) return cli;
-	const { commands } = cli;
-	const taken = Object.keys(builtInCommands(cli, {
-		bin: void 0,
-		node: void 0
-	})).filter((name) => commands[name] !== void 0);
-	if (taken.length > 0) throw new Error(`${cli.name} defines ${taken.join(", ")}, a built-in Command it cannot replace`);
-	return cli;
+function wantsHelp(words) {
+	return beforeEnd(words).some((word) => word === "--help" || word === "-h");
 }
-/**
-* 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 {
-		defineCommand: defineCommandFor(),
-		defineCli: defineCli$1
+function childOf(group, name) {
+	return Object.hasOwn(group.commands, name) ? group.commands[name] : void 0;
+}
+function isFlagLike(word) {
+	return word.length > 1 && word[0] === "-";
+}
+function walk(node, words, json, invocation) {
+	const help = {
+		kind: "help",
+		node,
+		json
+	};
+	if (node.kind === "command") return wantsHelp(words) ? help : {
+		kind: "command",
+		spec: node,
+		words,
+		json
 	};
+	const [first, ...rest] = words;
+	if (first === void 0) return help;
+	const child = childOf(node, first);
+	if (child !== void 0) return walk(child, rest, json, invocation);
+	if (first === "--") {
+		const [name, ...after] = rest;
+		if (name === void 0) return help;
+		const named = childOf(node, name);
+		if (named !== void 0) return walk(named, ["--", ...after], json, invocation);
+		return unknownCommand(node, name, json);
+	}
+	if (wantsHelp(words)) return help;
+	if (isFlagLike(first)) {
+		const suggestions = closestFlags(first, GROUP_FLAGS);
+		return {
+			kind: "usage error",
+			error: unknownOptionError(node.commandLine, invocation, first, suggestions),
+			node,
+			json
+		};
+	}
+	return unknownCommand(node, first, json);
 }
-//#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 unknownCommand(group, name, json) {
+	const suggestions = closestNames(name, Object.keys(visibleCommands(group)));
+	return {
+		kind: "usage error",
+		error: unknownCommandError(group.commandLine, name, suggestions),
+		node: group,
+		json
+	};
 }
-/** 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);
+/** Walks the caller's command line through the Commands to the one it names, or to a stop. */
+function route(root, invocation) {
+	const { argv } = invocation;
+	const options = beforeEnd(argv);
+	const json = options.includes(JSON_FLAG.flag);
+	if (options.includes("--version")) return {
+		kind: "version",
+		json
+	};
+	return walk(root, argv.filter((word, index) => !(index < options.length && word === JSON_FLAG.flag)), json, invocation);
 }
 //#endregion
 //#region ../agent-cli/dist/execute.js
@@ -8341,67 +8733,12 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, page, invoca
 		}, outputs);
 		if (!ctx.force) guardOutputs(outputs, ctx.commandLine({ add: [FORCE_FLAG.flag] }));
 	}
-	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
-}
-//#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;
-function distance(a, b) {
-	const width = b.length + 1;
-	const d = Array.from({ length: (a.length + 1) * width }, (_, k) => {
-		const i = Math.floor(k / width);
-		const j = k % width;
-		return i === 0 || j === 0 ? i + j : 0;
-	});
-	const at = (i, j) => d[i * width + j] ?? 0;
-	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
-		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-		const edit = Math.min(at(i - 1, j) + 1, at(i, j - 1) + 1, at(i - 1, j - 1) + cost);
-		const transposed = i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1];
-		d[i * width + j] = transposed ? Math.min(edit, at(i - 2, j - 2) + 1) : edit;
-	}
-	return at(a.length, b.length);
-}
-function isClose(word, candidate) {
-	const length = Math.max(word.length, candidate.length);
-	const edits = distance(word, candidate);
-	return candidate.length > 1 && edits < MAX_DISTANCE && (length - edits) / length > MIN_SIMILARITY;
-}
-/** The names closest to `word`, sorted, several when they tie, or none when nothing is close. */
-function closestNames(word, names) {
-	const close = [...new Set(names)].filter((candidate) => isClose(word, candidate));
-	const best = Math.min(...close.map((candidate) => distance(word, candidate)));
-	return close.filter((candidate) => distance(word, candidate) === best).sort((a, b) => a.localeCompare(b));
-}
-/** The long flags closest to `flag`, sorted, or none for a short flag or when nothing is close. */
-function closestFlags(flag, flags) {
-	if (!flag.startsWith("--")) return [];
-	const names = flags.map((candidate) => candidate.slice(2));
-	return closestNames(flag.slice(2), names).map((name) => `--${name}`);
-}
-/** The one long flag closest to `flag`, or none when nothing is close or several tie. */
-function closestFlag(flag, flags) {
-	const closest = closestFlags(flag, flags);
-	return closest.length === 1 ? closest[0] : void 0;
+	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
 }
 //#endregion
 //#region ../agent-cli/dist/parse-input.js
 const NO_INPUT = object({});
+const WHITESPACE = /\s/;
 function knownFlags(spec) {
 	return [...spec.options.map((field) => ({
 		flag: field.label,
@@ -8538,6 +8875,8 @@ async function parseInput(spec, words, invocation, readStdin) {
 		page: page.data,
 		values
 	};
+	const [onlyWord] = unknownOptions;
+	if (onlyWord !== void 0 && unknownOptions.length === 1 && WHITESPACE.test(onlyWord) && argFields.some((field) => field.stdin && argValues.get(field) === void 0)) throw stdinTextError(spec.commandLine, invocation, onlyWord);
 	const [only] = unknown;
 	if (only !== void 0 && unknown.length === 1 && otherLines.length === 0) throw unknownOptionError(spec.commandLine, invocation, only.flag, only.suggestion === void 0 ? [] : [only.suggestion]);
 	throw invalidInput(spec.commandLine, invocation, unknown, otherLines);
@@ -8563,83 +8902,9 @@ async function parseCommand({ spec, words, json }, invocation, readStdin) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/route.js
-const GROUP_FLAGS = [
-	HELP_FLAG,
-	VERSION_FLAG,
-	JSON_FLAG.flag
-];
-function beforeEnd(words) {
-	const end = words.indexOf("--");
-	return end === -1 ? words : words.slice(0, end);
-}
-function wantsHelp(words) {
-	return beforeEnd(words).some((word) => word === "--help" || word === "-h");
-}
-function childOf(group, name) {
-	return Object.hasOwn(group.commands, name) ? group.commands[name] : void 0;
-}
-function isFlagLike(word) {
-	return word.length > 1 && word[0] === "-";
-}
-function walk(node, words, json, invocation) {
-	const help = {
-		kind: "help",
-		node,
-		json
-	};
-	if (node.kind === "command") return wantsHelp(words) ? help : {
-		kind: "command",
-		spec: node,
-		words,
-		json
-	};
-	const [first, ...rest] = words;
-	if (first === void 0) return help;
-	const child = childOf(node, first);
-	if (child !== void 0) return walk(child, rest, json, invocation);
-	if (first === "--") {
-		const [name, ...after] = rest;
-		if (name === void 0) return help;
-		const named = childOf(node, name);
-		if (named !== void 0) return walk(named, ["--", ...after], json, invocation);
-		return unknownCommand(node, name, json);
-	}
-	if (wantsHelp(words)) return help;
-	if (isFlagLike(first)) {
-		const suggestions = closestFlags(first, GROUP_FLAGS);
-		return {
-			kind: "usage error",
-			error: unknownOptionError(node.commandLine, invocation, first, suggestions),
-			node,
-			json
-		};
-	}
-	return unknownCommand(node, first, json);
-}
-function unknownCommand(group, name, json) {
-	const suggestions = closestNames(name, Object.keys(visibleCommands(group)));
-	return {
-		kind: "usage error",
-		error: unknownCommandError(group.commandLine, name, suggestions),
-		node: group,
-		json
-	};
-}
-/** Walks the caller's command line through the Commands to the one it names, or to a stop. */
-function route(root, invocation) {
-	const { argv } = invocation;
-	const options = beforeEnd(argv);
-	const json = options.includes(JSON_FLAG.flag);
-	if (options.includes("--version")) return {
-		kind: "version",
-		json
-	};
-	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) {
+/** `$XDG_CONFIG_HOME/<cli>/.env`, with `~/.config` when the variable is unset or empty. */
+function envFileOf(cliName, env) {
 	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
 	return join(config, cliName, ".env");
 }
@@ -8656,24 +8921,50 @@ function readDotenv(path, fileError) {
 	}
 	return parseEnv(text);
 }
-/** Looks `name` up in the env, then in `$XDG_CONFIG_HOME/<cli>/.env`; an empty value counts as unset. */
-function secretOf({ cliName, env, fileError }, name) {
+/** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
+function secretOf({ envFile, env, fileError }, name) {
 	const fromEnv = env[name];
 	if (fromEnv) return {
 		value: fromEnv,
 		origin: { kind: "env" }
 	};
-	const path = dotenvPath(cliName, env);
-	const fromFile = readDotenv(path, fileError)[name];
+	const fromFile = readDotenv(envFile, fileError)[name];
 	return fromFile ? {
 		value: fromFile,
 		origin: {
 			kind: "file",
-			path
+			path: envFile
 		}
 	} : void 0;
 }
 //#endregion
+//#region ../agent-cli/dist/side-task.js
+/** How long a run waits for its Side task once its output is written. */
+const SIDE_TASK_WAIT_MS = 1e3;
+const noSideTask = async () => {};
+function waitOver() {
+	return new DOMException(`the side task ran past its ${SIDE_TASK_WAIT_MS} ms wait`, "TimeoutError");
+}
+function startSideTask(sideTask, runWith, { clock, failed }) {
+	if (sideTask === void 0) return noSideTask;
+	const controller = new AbortController();
+	const { signal } = controller;
+	const running = (async () => sideTask(runWith(signal)))().catch((error) => {
+		if (!(signal.aborted && error === signal.reason)) failed(error);
+	});
+	return async () => {
+		const waited = new AbortController();
+		const capped = new Promise((resolve) => after(clock, SIDE_TASK_WAIT_MS, waited.signal, () => {
+			const over = waitOver();
+			failed(over);
+			controller.abort(over);
+			resolve();
+		}));
+		await Promise.race([running, capped]);
+		waited.abort();
+	};
+}
+//#endregion
 //#region ../agent-cli/dist/spill.js
 const STDOUT_BUDGET_CHARS = 3e4;
 const SPILL_RETENTION_MS = 6048e5;
@@ -8726,47 +9017,91 @@ function spillTo(target) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/style.js
-function colourEnabled(env, stdoutIsTTY) {
-	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);
+//#region ../agent-cli/dist/run-command.js
+function stdinNeverEndedHint(callerLine) {
+	return `stdin never ended: pipe the text into \`${callerLine}\`, or redirect a file into it`;
 }
-function sgr(open, close) {
-	return (text) => `\u001b[${open}m${text}\u001b[${close}m`;
+function selfOf(name, bin) {
+	return bin === void 0 ? [name] : [
+		process.execPath,
+		...process.execArgv,
+		bin
+	];
 }
-const COLOURED = {
-	bold: sgr(1, 22),
-	dim: sgr(2, 22),
-	red: sgr(31, 39),
-	green: sgr(32, 39),
-	yellow: sgr(33, 39),
-	cyan: sgr(36, 39)
-};
-const plain = (text) => text;
-const PLAIN = {
-	bold: plain,
-	dim: plain,
-	red: plain,
-	green: plain,
-	yellow: plain,
-	cyan: plain
-};
-function styleFor(env, stdoutIsTTY) {
-	return colourEnabled(env, stdoutIsTTY) ? COLOURED : PLAIN;
+function portsOf(cli, replacement) {
+	if (replacement !== void 0) return () => replacement;
+	return cli.ports ?? (() => ({}));
 }
-//#endregion
-//#region ../agent-cli/dist/run-cli.js
-function stdinNeverEndedHint(callerLine) {
-	return `stdin never ended: pipe the text into \`${callerLine}\`, or redirect a file into it`;
+function portsBaseOf(scope, signal) {
+	const { cli, options, packageRoot, progress, fileError, clock, files } = scope;
+	const { cwd, env } = options;
+	const envFile = envFileOf(cli.name, env);
+	return {
+		cwd,
+		env,
+		packageRoot,
+		progress,
+		secret: (name) => secretOf({
+			envFile,
+			env,
+			fileError
+		}, name),
+		envFile,
+		fileError,
+		version: cli.version,
+		build: cli.build,
+		self: selfOf(cli.name, options.bin),
+		signal,
+		clock,
+		files,
+		spawn: contextSpawn(options.spawn ?? realSpawn, {
+			cwd,
+			env,
+			signal,
+			progress
+		}, fileError)
+	};
+}
+function contextOf(portsBase, control, parts) {
+	const { ports, project, force, commandLine, deliver } = parts;
+	return {
+		...portsBase,
+		deadline: (ms) => control.deadline(ms),
+		timeout: (ms) => control.timeout(ms),
+		runToEnd: (name, work) => control.runToEnd(name, work),
+		get ports() {
+			return ports();
+		},
+		project,
+		force,
+		commandLine,
+		poll: (check, { intervalMs, signal: stop }) => poll(portsBase.clock, check, intervalMs, stop === void 0 ? control.signal : AbortSignal.any([control.signal, stop])),
+		deliver
+	};
 }
-async function runCommand(routed, { base, writeStdout, signal, format: baseFormat, ports, clock, files, spawn, projectFile, stdin, platform }) {
-	const { command, commandLine } = routed.spec;
+/** Leaves the Side task running, so the caller writes the result before it waits for it. */
+async function runCommand(cli, routed, options, write, baseFormat) {
+	const { command, commandLine, builtIn } = routed.spec;
+	const { cwd, env } = options;
+	const clock = options.clock ?? realClock;
+	const files = options.files ?? realFiles();
+	const stdin = options.stdin ?? "";
+	const platform = options.platform ?? process.platform;
+	const ports = portsOf(cli, options.ports);
+	const packageRoot = packageRootOf(options.bin, cwd);
+	const fileError = fileErrorOf({
+		callerLine: commandLineOf(baseFormat.invocation),
+		env,
+		platform
+	});
+	const progress = (message) => write.stderr(progressLine(message, routed.json));
 	const invocation = {
 		...baseFormat.invocation,
 		flags: knownFlags(routed.spec)
 	};
 	const format = {
 		...baseFormat,
+		bugs: () => manifestAt(packageRoot).bugs,
 		json: routed.json,
 		invocation
 	};
@@ -8774,71 +9109,91 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 	let resumeHint;
 	const control = new RunControl({
 		commandLine,
-		outer: signal,
+		outer: options.signal,
 		clock,
-		progress: base.progress,
+		progress,
 		runDeadline: command.deadline === void 0 ? void 0 : {
 			ms: command.deadline.ms,
 			hint: () => resumeHint ?? stdinNeverEndedHint(typedLine())
 		}
 	});
+	const failed = (error, finishSideTask) => {
+		control.close();
+		return {
+			result: errorResult(error, format),
+			finishSideTask
+		};
+	};
 	let parsed;
-	let project;
 	try {
-		checkOperator(routed.spec, base.env, typedLine());
+		checkOperator(routed.spec, env, typedLine());
 		parsed = await parseCommand(routed, invocation, (field) => {
-			if (isTerminal(stdin)) base.progress(readingLine(field.name, platform));
-			return readStdin(stdin, control.signal);
+			if (isTerminal(stdin)) progress(readingLine(field.name, platform));
+			return readStdin(stdin, control.signal, {
+				clock,
+				stalled: () => stdinStalled(typedLine())
+			});
 		});
-		project = projectFile === void 0 ? void 0 : projectOf(projectFile, base.cwd);
 	} catch (error) {
-		control.close();
-		return errorResult(error, format);
+		return failed(error, noSideTask);
 	}
 	const { input, flags } = parsed;
 	resumeHint = command.deadline?.resume(input, typedLine);
-	let delivered;
-	const { fileError } = base;
 	const outputs = outputsGuard(classifiedFiles(files, {
-		cwd: base.cwd,
-		fileError
-	}), base.cwd);
-	const spill = spillTo({
-		cliName: format.cliName,
-		commandName: command.name,
-		env: base.env,
-		clock,
-		files: outputs.files,
+		cwd,
 		fileError
-	});
-	const portsBase = {
-		...base,
-		signal: control.signal,
+	}), cwd);
+	const scope = {
+		cli,
+		options,
+		packageRoot,
+		progress,
+		fileError,
 		clock,
-		files: outputs.files,
-		spawn: contextSpawn(spawn, {
-			cwd: base.cwd,
-			env: base.env,
-			signal: control.signal,
-			progress: base.progress
-		}, fileError)
+		files: outputs.files
 	};
-	const builtPorts = once(() => ports(portsBase));
-	const ctx = {
-		...portsBase,
-		deadline: (ms) => control.deadline(ms),
-		runToEnd: (name, work) => control.runToEnd(name, work),
-		get ports() {
-			return builtPorts();
-		},
+	const portsBase = portsBaseOf(scope, control.signal);
+	const finishSideTask = startSideTask(builtIn ? void 0 : cli.sideTask?.bind(cli), (sideSignal) => {
+		const sideBase = portsBaseOf(scope, sideSignal);
+		const sidePorts = once(() => ports(sideBase));
+		return {
+			...sideBase,
+			command: routed.spec.path,
+			dryRun: flags.dryRun,
+			get ports() {
+				return sidePorts();
+			}
+		};
+	}, {
+		clock,
+		failed: (error) => {
+			if (isDebug(baseFormat)) progress(`side task failed: ${traceOf(error)}`);
+		}
+	});
+	let project;
+	try {
+		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, fileError);
+	} catch (error) {
+		return failed(error, finishSideTask);
+	}
+	let delivered;
+	const ctx = contextOf(portsBase, control, {
+		ports: once(() => ports(portsBase)),
 		project,
 		force: flags.force,
 		commandLine: typedLine,
-		poll: (check, { intervalMs, signal: stop }) => poll(clock, check, intervalMs, stop === void 0 ? control.signal : AbortSignal.any([control.signal, stop])),
 		deliver: (data) => {
 			delivered = deliveredOutcome(command, data);
 		}
-	};
+	});
+	const spill = spillTo({
+		cliName: format.cliName,
+		commandName: command.name,
+		env,
+		clock,
+		files: outputs.files,
+		fileError
+	});
 	let served = false;
 	let settled;
 	try {
@@ -8852,7 +9207,7 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 				invocation,
 				commandLine,
 				started: async (outcome) => {
-					writeStdout(await startedOutput(outcome, format, spill));
+					write.stdout(await startedOutput(outcome, format, spill));
 					served = true;
 				},
 				files,
@@ -8860,17 +9215,23 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 			}))
 		};
 	} catch (error) {
-		if (served && control.signal.aborted) return STOPPED_RESULT;
+		if (served && control.signal.aborted) return {
+			result: STOPPED_RESULT,
+			finishSideTask
+		};
 		settled = {
 			ok: false,
 			error: control.errorAfter(error),
 			delivered
 		};
 	}
-	return commandResult(settled, {
-		...format,
-		fields: flags.fields
-	}, spill);
+	return {
+		result: await commandResult(settled, {
+			...format,
+			fields: flags.fields
+		}, spill),
+		finishSideTask
+	};
 }
 /** `build` runs on the first call; later calls give its value or throw its error again. */
 function once(build) {
@@ -8891,17 +9252,37 @@ function once(build) {
 		throw outcome.error;
 	};
 }
-function selfOf(name, bin) {
-	return bin === void 0 ? [name] : [
-		process.execPath,
-		...process.execArgv,
-		bin
-	];
+//#endregion
+//#region ../agent-cli/dist/style.js
+function colourEnabled(env, stdoutIsTTY) {
+	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 portsOf(cli, replacement) {
-	if (replacement !== void 0) return () => replacement;
-	return cli.ports ?? (() => ({}));
+function sgr(open, close) {
+	return (text) => `\u001b[${open}m${text}\u001b[${close}m`;
+}
+const COLOURED = {
+	bold: sgr(1, 22),
+	dim: sgr(2, 22),
+	red: sgr(31, 39),
+	green: sgr(32, 39),
+	yellow: sgr(33, 39),
+	cyan: sgr(36, 39)
+};
+const plain = (text) => text;
+const PLAIN = {
+	bold: plain,
+	dim: plain,
+	red: plain,
+	green: plain,
+	yellow: plain,
+	cyan: plain
+};
+function styleFor(env, stdoutIsTTY) {
+	return colourEnabled(env, stdoutIsTTY) ? COLOURED : PLAIN;
 }
+//#endregion
+//#region ../agent-cli/dist/run-cli.js
 function stopLine(notice, json) {
 	return json ? progressLine(notice, true) : `\n${notice}\n`;
 }
@@ -8915,7 +9296,14 @@ async function whileStopping(signal, onStop, work) {
 		signal.removeEventListener("abort", onStop);
 	}
 }
+/** Runs the CLI, writes its output, then waits for the Side task it started. */
 async function runWithProgress(cli, argv, options, write, stopNotice) {
+	const { result, finishSideTask } = await routeAndRun(cli, argv, options, write, stopNotice);
+	await write.result(result);
+	await finishSideTask();
+	return result;
+}
+async function routeAndRun(cli, argv, options, write, stopNotice) {
 	const format = {
 		cliName: cli.name,
 		env: options.env,
@@ -8929,64 +9317,37 @@ async function runWithProgress(cli, argv, options, write, stopNotice) {
 		errors: cli.errors ?? {},
 		stop: options.signal
 	};
-	const builtIns = cli.commands === void 0 ? {} : builtInCommands(cli, {
+	const root = cli.commands === void 0 ? {
+		...commandSpec(cli.name, cli.command),
+		description: cli.description
+	} : groupSpec(cli.name, cli.commands, builtInCommands(cli, {
 		bin: options.bin,
 		node: options.node
-	});
-	const root = cli.commands === void 0 ? commandSpec(cli.name, cli.command) : groupSpec(cli.name, {
-		...cli.commands,
-		...builtIns
-	});
+	}));
 	const routed = route(root, format.invocation);
-	const platform = options.platform ?? process.platform;
-	const fileError = fileErrorOf({
-		callerLine: commandLineOf(format.invocation),
-		env: options.env,
-		platform
-	});
 	const misused = (node) => isAgent(options.env) ? {
 		...format,
 		usageHelp: textHelp(node, root, cli, format.style)
 	} : format;
 	switch (routed.kind) {
-		case "version": return versionResult(cli, packageRootOf(options.bin, options.cwd));
-		case "help": return helpResult(routed.node, root, cli, {
+		case "version": return ranAlone(versionResult(cli, packageRootOf(options.bin, options.cwd)));
+		case "help": return ranAlone(helpResult(routed.node, root, cli, {
 			...format,
 			json: routed.json
-		});
-		case "usage error": return errorResult(routed.error, {
+		}));
+		case "usage error": return ranAlone(errorResult(routed.error, {
 			...misused(routed.node),
 			json: routed.json
-		});
-		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(routed, {
-			base: {
-				cwd: options.cwd,
-				env: options.env,
-				packageRoot: packageRootOf(options.bin, options.cwd),
-				progress: (message) => write.stderr(progressLine(message, routed.json)),
-				secret: (name) => secretOf({
-					cliName: cli.name,
-					env: options.env,
-					fileError
-				}, name),
-				fileError,
-				version: cli.version,
-				build: cli.build,
-				self: selfOf(cli.name, options.bin)
-			},
-			writeStdout: (text) => write.stdout(text),
-			signal: options.signal,
-			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,
-			stdin: options.stdin ?? "",
-			platform
 		}));
+		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(cli, routed, options, write, misused(routed.spec)));
 	}
 }
+async function ranAlone(result) {
+	return {
+		result: await result,
+		finishSideTask: noSideTask
+	};
+}
 //#endregion
 //#region ../agent-cli/dist/run-process.js
 function written(stream, text) {
@@ -9011,10 +9372,12 @@ async function runProcess(cli) {
 			stdin: process.stdin
 		}, {
 			stdout: (text) => process.stdout.write(text),
-			stderr: (text) => process.stderr.write(text)
+			stderr: (text) => process.stderr.write(text),
+			result: async ({ stdout, stderr }) => {
+				await written(process.stdout, stdout);
+				await written(process.stderr, stderr);
+			}
 		}, "stopping… (Ctrl-C again to quit now)");
-		await written(process.stdout, result.stdout);
-		await written(process.stderr, result.stderr);
 		process.exitCode = result.exitCode;
 	} finally {
 		process.off("SIGINT", onSignal);
@@ -9023,11 +9386,15 @@ async function runProcess(cli) {
 	process.exit();
 }
 //#endregion
+//#region package.json
+var version$1 = "0.6.0";
+var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
+//#endregion
 //#region src/build.ts
 const build = {
-	"sha": "c325cae",
+	"sha": "6821473",
 	"dirty": false,
-	"builtAt": "2026-10-19T14:33:32.022Z"
+	"builtAt": "2026-10-20T02:08:46.888Z"
 };
 //#endregion
 //#region src/steps.ts
@@ -9156,11 +9523,13 @@ async function writeTemplate(root, files, values) {
 }
 //#endregion
 //#region src/version.ts
-const version = "0.5.0";
+const version = version$1;
 //#endregion
 //#region src/create.ts
 const { defineCommand } = agentCli();
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?([a-z0-9][a-z0-9._-]*)$/;
+const RELEASE_BRANCH = "release";
+const NO_REPOSITORY = "<!-- Set `repository` in package.json, then put here the `! npx -y skills add` line that `node dist/bin.js doctor` gives as the `skill` row's fix. -->";
 function errorCode(error) {
 	return error instanceof Error && "code" in error ? error.code : void 0;
 }
@@ -9173,6 +9542,17 @@ async function isFree(path) {
 		throw error;
 	}
 }
+function skillInstallLine(repository, binName) {
+	if (repository === void 0) return NO_REPOSITORY;
+	return `\`! npx -y skills add ${`${repository.endsWith(".git") ? repository : `${repository}.git`}#${RELEASE_BRANCH}`} --skill ${binName} -g\``;
+}
+const MANIFEST = record(string(), unknown());
+async function setRepository(root, repository) {
+	const path = join(root, "package.json");
+	const manifest = MANIFEST.parse(JSON.parse(await readFile(path, "utf8")));
+	const entries = Object.entries(manifest).flatMap((entry) => entry[0] === "description" ? [entry, ["repository", repository]] : [entry]);
+	await writeFile(path, `${JSON.stringify(Object.fromEntries(entries), null, 2)}\n`);
+}
 async function ensureFree(path) {
 	if (!await isFree(path)) throw new UsageError({
 		code: "TARGET_NOT_EMPTY",
@@ -9192,9 +9572,10 @@ const create = defineCommand({
 	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")
+		git: boolean().default(true).describe("create a git repository with an initial commit"),
+		repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository, where its skill is installed from")
 	}),
-	plan: async ({ name, description, install, git }, ctx) => {
+	plan: async ({ name, description, install, git, repository }, ctx) => {
 		const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
 		const path = resolve(ctx.cwd, binName);
 		await ensureFree(path);
@@ -9203,7 +9584,8 @@ const create = defineCommand({
 			binName,
 			description,
 			debugVariable: debugVariable(binName),
-			runtimeVersion: version
+			runtimeVersion: version,
+			skillInstall: skillInstallLine(repository, binName)
 		};
 		return {
 			path,
@@ -9213,12 +9595,14 @@ const create = defineCommand({
 				install,
 				git
 			}),
-			install
+			install,
+			repository
 		};
 	},
 	apply: async (plan, ctx) => {
 		await mkdir(plan.path, { recursive: true });
 		await writeTemplate(plan.path, plan.files, plan.values);
+		if (plan.repository !== void 0) await setRepository(plan.path, plan.repository);
 		await runSteps(plan.steps, plan.path, ctx);
 		return {
 			path: plan.path,
@@ -9240,6 +9624,7 @@ const { defineCli } = agentCli();
 await runProcess(defineCli({
 	name: "create-agent-cli",
 	version,
+	description,
 	build,
 	errors: stepErrors,
 	command: create