@duyquangnvx/create-agent-cli 0.27.0 → 0.29.0

package/dist/bin.js

@@ -4,7 +4,7 @@ import { spawn } from "node:child_process";
 import { constants, homedir, tmpdir } from "node:os";
 import { parseArgs, parseEnv } from "node:util";
 import { constants as constants$1, existsSync, readFileSync, realpathSync } from "node:fs";
-import { access, chmod, link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { access, chmod, link, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 //#region ../../node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/core/util.js
@@ -5947,15 +5947,6 @@ function errnoOf(error) {
 function isMissingFile(error) {
 	return errnoOf(error) === "ENOENT";
 }
-/** What `pending` resolves with, or undefined when it fails because a file is missing. */
-async function orMissing(pending) {
-	try {
-		return await pending;
-	} catch (error) {
-		if (isMissingFile(error)) return void 0;
-		throw error;
-	}
-}
 function isNothingThere(error) {
 	return isMissingFile(error) || errnoOf(error) === "ENOTDIR";
 }
@@ -5981,14 +5972,14 @@ function bugHint(format) {
 	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) {
+function fieldsOf$1({ error, exitClass }, format) {
 	if (!(error instanceof CliError)) return {
 		code: INTERNAL,
 		message: messageOf(error),
 		hint: bugHint(format)
 	};
 	const { code, message, hint, details, retryAt, next } = error;
-	if (format.isBug(error)) return {
+	if (exitClass === "bug") return {
 		code,
 		message,
 		hint: bugHint(format),
@@ -6012,9 +6003,9 @@ 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) {
+function debugTrace({ error, exitClass }, format) {
 	if (!isDebug(format)) return void 0;
-	const lines = [...format.isBug(error) ? [traceOf(error)] : [], ...causesOf(error).map((cause) => `caused by: ${traceOf(cause)}`)];
+	const lines = [...exitClass === "bug" ? [traceOf(error)] : [], ...causesOf(error).map((cause) => `caused by: ${traceOf(cause)}`)];
 	return lines.length === 0 ? void 0 : lines.join("\n");
 }
 /**
@@ -6033,29 +6024,29 @@ function printedDetail(error, format) {
 	const value = Reflect.get(details, key);
 	return typeof value === "string" ? value : void 0;
 }
-function labelOf(error, { isBug, isWait, style }) {
-	if (isWait(error)) return style.yellow("wait:");
-	return style.red(isBug(error) ? "internal error:" : "error:");
+function labelOf({ exitClass }, style) {
+	if (exitClass === "wait") return style.yellow("wait:");
+	return style.red(exitClass === "bug" ? "internal error:" : "error:");
 }
-function errorLines(error, format) {
-	const fields = fieldsOf$1(error, format);
-	const blocks = [printedDetail(error, format), debugTrace(error, format)].filter((block) => block !== void 0);
+function errorLines(leaf, format) {
+	const fields = fieldsOf$1(leaf, format);
+	const blocks = [printedDetail(leaf.error, format), debugTrace(leaf, format)].filter((block) => block !== void 0);
 	const { style } = format;
-	const label = labelOf(error, format);
+	const label = labelOf(leaf, style);
 	const between = blocks.map((block) => `${block}\n`).join("");
 	const runs = (fields.next ?? []).map((line) => `${style.cyan("run:")} ${line}\n`).join("");
 	return `${label} ${fields.message}\n${between}${style.cyan("hint:")} ${fields.hint}\n${runs}`;
 }
-function formatRuntimeError(error, format) {
-	const errors = errorsOf(error);
+/** The classified errors a run failed with, as stderr carries them. */
+function formatRuntimeError(leaves, format) {
 	if (format.json) {
-		const printed = errors.map((each) => ({
-			...fieldsOf$1(each, format),
-			stack: debugTrace(each, format)
+		const printed = leaves.map((leaf) => ({
+			...fieldsOf$1(leaf, format),
+			stack: debugTrace(leaf, format)
 		}));
 		return `${JSON.stringify({ errors: printed })}\n`;
 	}
-	return errors.map((each) => errorLines(each, format)).join("");
+	return leaves.map((leaf) => errorLines(leaf, format)).join("");
 }
 //#endregion
 //#region ../agent-cli/dist/tail.js
@@ -6085,8 +6076,8 @@ const WINDOWS_EXTENSIONS = ".COM;.EXE;.BAT;.CMD";
 function pathOf(env) {
 	return env[Object.keys(env).find((name) => name.toUpperCase() === "PATH") ?? "PATH"] ?? "";
 }
-function extensionsOf(env) {
-	return process.platform === "win32" ? (env.PATHEXT ?? WINDOWS_EXTENSIONS).split(";") : [""];
+function extensionsOf({ env, platform }) {
+	return platform === "win32" ? (env.PATHEXT ?? WINDOWS_EXTENSIONS).split(";") : [""];
 }
 async function isExecutable(file) {
 	try {
@@ -6098,19 +6089,19 @@ async function isExecutable(file) {
 	}
 }
 /** The file names `name` may have on `PATH`: itself when it already ends in one of the extensions. */
-function fileNamesOf(name, env) {
-	const extensions = extensionsOf(env);
+function fileNamesOf(name, search) {
+	const extensions = extensionsOf(search);
 	const own = extname(name).toUpperCase();
 	return own !== "" && extensions.some((extension) => extension.toUpperCase() === own) ? [name] : extensions.map((extension) => `${name}${extension}`);
 }
-/** Where `name` is found on `PATH` from `env`, or undefined. */
-async function findTool(name, env) {
-	const candidates = pathOf(env).split(delimiter).filter((folder) => folder !== "").flatMap((folder) => fileNamesOf(name, env).map((file) => join(folder, file)));
+/** Where `name` is found on `PATH`, or undefined. */
+async function findTool(name, search) {
+	const candidates = pathOf(search.env).split(delimiter).filter((folder) => folder !== "").flatMap((folder) => fileNamesOf(name, search).map((file) => join(folder, file)));
 	for (const file of candidates) if (await isExecutable(file)) return file;
 }
 /** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
-async function checkTools(tools, env, rerun) {
-	const found = await Promise.all(tools.map((tool) => findTool(tool.name, env)));
+async function checkTools(tools, search, rerun) {
+	const found = await Promise.all(tools.map((tool) => findTool(tool.name, search)));
 	const missing = tools.filter((_tool, index) => found[index] === void 0);
 	if (missing.length === 0) return;
 	const names = missing.map(({ name }) => name).join(", ");
@@ -6122,11 +6113,14 @@ async function checkTools(tools, env, rerun) {
 	});
 }
 /** One `doctor` row per distinct tool the CLI and its Commands declare, with its install command as the fix. */
-function toolRows(tools, commands) {
+function toolRows(tools, commands, platform) {
 	return declaredIn(tools, commands, (command) => command.tools).map(({ name, install }) => ({
 		name,
 		run: async (ctx) => {
-			const file = await findTool(name, ctx.env);
+			const file = await findTool(name, {
+				env: ctx.env,
+				platform
+			});
 			return file === void 0 ? {
 				state: "problem",
 				message: `${name} is not on PATH`,
@@ -6164,7 +6158,10 @@ function batchCommandLine(command, file, args) {
 	return [escapedForCmd(command), ...args.map((arg) => batchArgument(arg, shim))].join(" ");
 }
 async function windowsLaunch(command, args, env) {
-	const file = PATH_SEPARATOR.test(command) ? command : await findTool(command, env);
+	const file = PATH_SEPARATOR.test(command) ? command : await findTool(command, {
+		env,
+		platform: process.platform
+	});
 	if (file === void 0 || !BATCH_FILE.test(file)) return {
 		command,
 		args,
@@ -6928,188 +6925,42 @@ function checkForce(command, label) {
 	if (force.trim() === "") throw new Error(`Command '${label}' declares an empty force; say what ${FORCE_FLAG.flag} replaces`);
 }
 //#endregion
-//#region ../agent-cli/dist/define-command.js
-/** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
-function checkCommand(command, label, table) {
-	checkNoStandardFlags(command, label);
-	checkForce(command, label);
-	checkArrayArgLast(label, command.args);
-	checkStdinFields(label, command.args, command.options);
-	checkNoBooleanArrayOption(label, command.options);
-	checkErrors(command, label, table);
-}
-function checkErrors(command, label, table) {
-	const unknown = (command.errors ?? []).filter((code) => !Object.hasOwn(table, code));
-	if (unknown.length > 0) throw new Error(`${label} declares ${unknown.join(", ")} in errors, a code the Error table lacks`);
-}
-function defineCommandFor() {
-	return declared;
-}
-function declared(command) {
-	return command;
-}
-const defineCommand$1 = defineCommandFor();
-//#endregion
-//#region ../agent-cli/dist/context/project.js
-const PROJECT_INVALID = "PROJECT_INVALID";
-function invalid(path, problem, rerun, options) {
-	return new CliError({
-		code: PROJECT_INVALID,
-		message: `the Project file ${path} is invalid: ${problem}`,
-		hint: `fix ${path}, then run the Next step`,
-		next: [rerun]
-	}, options);
-}
-function readText(path, fileError) {
-	try {
-		return readFileSync(path, "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return void 0;
-		throw fileError(error, {
-			path,
-			access: "read"
-		});
-	}
-}
-function parsed(path, text, schema, rerun) {
-	let json;
-	try {
-		json = JSON.parse(text);
-	} catch (error) {
-		throw invalid(path, messageOf(error), rerun, { cause: error });
-	}
-	const result = schema.safeParse(json);
-	if (!result.success) throw invalid(path, prettifyError(result.error), rerun);
-	return result.data;
-}
-function projectFrom(projectFile, folder, scope) {
-	const path = join(folder, projectFile.file);
-	const text = readText(path, scope.fileError);
-	if (text !== void 0) return {
-		root: folder,
-		settings: parsed(path, text, projectFile.schema, scope.rerun)
+//#region ../agent-cli/dist/context/confirm.js
+const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
+const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
+function checkConfirmation({ rerun, commandLine, given }, expected) {
+	if (given === expected) return;
+	const advice = {
+		hint: "once the user confirms the target, run the Next step",
+		next: [rerun({
+			remove: [CONFIRM_FLAG.flag],
+			add: [CONFIRM_FLAG.flag, expected]
+		})]
 	};
-	const parent = dirname(folder);
-	return parent === folder ? void 0 : projectFrom(projectFile, parent, scope);
-}
-/** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
-function projectOf(projectFile, cwd, scope) {
-	return projectFrom(projectFile, resolve(cwd), scope);
+	if (given === void 0) throw new UsageError({
+		code: CONFIRMATION_REQUIRED,
+		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
+		...advice
+	});
+	throw new UsageError({
+		code: CONFIRMATION_MISMATCH,
+		message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
+		...advice
+	});
 }
 //#endregion
-//#region ../agent-cli/dist/context/secrets.js
-const SECRET_MISSING = "SECRET_MISSING";
-/** `$XDG_CONFIG_HOME/<cli>/.env`, with `~/.config` when the variable is unset or empty. */
-function envFileOf(cliName, env) {
-	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
-	return join(config, cliName, ".env");
-}
-function readDotenv(path, fileError) {
-	let text;
-	try {
-		text = readFileSync(path, "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return {};
-		throw fileError(error, {
-			path,
-			access: "read"
-		});
-	}
-	return parseEnv(text);
-}
-/** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
-function secretOf({ envFile, env, fileError }, name) {
-	const fromEnv = env[name];
-	if (fromEnv) return {
-		value: fromEnv,
-		origin: { kind: "env" }
-	};
-	const fromFile = readDotenv(envFile, fileError)[name];
-	return fromFile ? {
-		value: fromFile,
-		origin: {
-			kind: "file",
-			path: envFile
-		}
-	} : void 0;
-}
-function isNeeded({ optional }) {
-	return optional !== true;
-}
-function missingIn(scope, secrets) {
-	return secrets.filter((secret) => isNeeded(secret) && secretOf(scope, secret.name) === void 0);
-}
-function getItFrom({ get }) {
-	return `(get it from ${get})`;
-}
-function whereToGet(secrets) {
-	return secrets.map((secret) => `${secret.name} ${getItFrom(secret)}`).join(", ");
-}
-/** Fails with `SECRET_MISSING`, naming every missing Secret at once, unless all are set. */
-function checkSecrets(secrets, scope, rerun) {
-	const missing = missingIn(scope, secrets);
-	if (missing.length === 0) return;
-	const names = missing.map(({ name }) => name).join(", ");
+//#region ../agent-cli/dist/context/cost.js
+const NOT_CONFIRMED = "NOT_CONFIRMED";
+/** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
+function checkCost({ rerun, commandLine, yes }, cost) {
+	if (cost === void 0 || yes) return;
 	throw new CliError({
-		code: SECRET_MISSING,
-		message: `${missing.length === 1 ? "a Secret it needs is" : "Secrets it needs are"} not set: ${names}`,
-		hint: `set ${whereToGet(missing)} in the environment or in ${scope.envFile}, then run the Next step`,
-		next: [rerun]
+		code: NOT_CONFIRMED,
+		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
+		hint: "once the user approves the cost, run the Next step",
+		next: [rerun({ add: [YES_FLAG.flag] })]
 	});
 }
-function originOf({ origin }) {
-	return origin.kind === "env" ? "the environment" : origin.path;
-}
-/**
-* The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. A
-* name needed anywhere counts as needed, and an unset optional one goes unmentioned.
-*/
-function secretRows(secrets, commands) {
-	const declared = declaredIn(secrets, commands, (command) => command.secrets);
-	if (declared.length === 0) return [];
-	const needed = new Map(declaredIn(secrets.filter(isNeeded), commands, (command) => command.secrets?.filter(isNeeded)).map((declaration) => [declaration.name, declaration]));
-	return [{
-		name: "secrets",
-		run: ({ env, envFile, fileError }) => {
-			const read = declared.map((declaration) => ({
-				declaration,
-				secret: secretOf({
-					env,
-					envFile,
-					fileError
-				}, declaration.name)
-			}));
-			const missing = read.flatMap(({ declaration, secret }) => {
-				const neededAs = needed.get(declaration.name);
-				return secret === void 0 && neededAs !== void 0 ? [neededAs] : [];
-			});
-			if (missing.length > 0) return {
-				state: "problem",
-				message: `${missing.map((declaration) => `${declaration.name} is not set ${getItFrom(declaration)}`).join(", ")}; add ${missing.length === 1 ? "it" : "them"} to ${envFile} or the environment`
-			};
-			const found = read.flatMap(({ declaration, secret }) => secret === void 0 ? [] : [`${declaration.name} from ${originOf(secret)}`]);
-			return {
-				state: "ok",
-				message: found.length > 0 ? found.join(", ") : "no Secret is set, and none is needed"
-			};
-		}
-	}];
-}
-//#endregion
-//#region ../agent-cli/dist/version.js
-/** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
-function buildStamp() {
-	return {
-		"sha": "8ba1668",
-		"dirty": false,
-		"builtAt": "2026-11-08T16:12:26.000Z"
-	};
-}
-/** The first line of `--version`: the version, and the commit and time of a stamped build. */
-function versionLine({ version }) {
-	const build = buildStamp();
-	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
-}
 //#endregion
 //#region ../agent-cli/dist/context/agent.js
 const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
@@ -7145,36 +6996,785 @@ function isAgent(env) {
 	return MARKERS.some((marker) => marker(env));
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/semver.js
-const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
-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/context/errno.js
+const PERMISSION_DENIED = "PERMISSION_DENIED";
+const DISK_FULL = "DISK_FULL";
+const NOT_FOUND = "NOT_FOUND";
+const ALREADY_EXISTS = "ALREADY_EXISTS";
+const NOT_A_FILE = "NOT_A_FILE";
+function permissionAdvice({ path, access, rerun, env, platform }) {
+	if (platform === "win32") return {
+		hint: `a program may hold ${path} open: close it, then run the Next step`,
+		next: [rerun]
+	};
+	if (!isAgent(env)) return { hint: `check the permissions of ${path} and its folder` };
+	return {
+		hint: `your sandbox may block it: ask your user to type ! then the Next step, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`,
+		next: [rerun]
+	};
 }
-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;
+function fileErrorOf(scope) {
+	return (error, at) => classifyErrno(error, {
+		...at,
+		...scope
+	});
 }
-/** 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);
+function classifyErrno(error, context) {
+	const { path } = context;
+	switch (errnoOf(error)) {
+		case "EACCES":
+		case "EPERM":
+		case "EROFS":
+		case "EBUSY": return new CliError({
+			code: PERMISSION_DENIED,
+			message: `permission denied: ${path}`,
+			...permissionAdvice(context)
+		}, { cause: error });
+		case "ENOSPC":
+		case "EDQUOT": return new CliError({
+			code: DISK_FULL,
+			message: `no space left on the disk holding ${path}`,
+			hint: "free space on that disk, then run the Next step",
+			next: [context.rerun]
+		}, { cause: error });
+		case "ENOENT":
+		case "ENOTDIR":
+		case "ENAMETOOLONG": return new CliError({
+			code: NOT_FOUND,
+			message: `not found: ${path}`,
+			hint: `check that ${path} and its folder exist`
+		}, { cause: error });
+		case "EEXIST": return new CliError({
+			code: ALREADY_EXISTS,
+			message: `already exists: ${path}`,
+			hint: `pass another path, or remove ${path}`
+		}, { cause: error });
+		case "EISDIR": return new CliError({
+			code: NOT_A_FILE,
+			message: `not a file: ${path} is a folder`,
+			hint: `pass the path of a file, not of the folder ${path}`
+		}, { cause: error });
+		default: return error;
+	}
+}
+//#endregion
+//#region ../agent-cli/dist/context/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(rerun) {
+	return new CliError({
+		code: INTERRUPTED,
+		message: "interrupted before it finished",
+		hint: "to finish it, run the Next step, unless it was stopped on purpose; if a tool timeout stopped it, give it longer",
+		next: [rerun]
+	});
+}
+const BOUND_WORDS = {
+	deadline: "deadline",
+	ignoreStop: "timeout"
+};
+function waitHint(bound) {
+	return bound === "ignoreStop" ? "the call may have been billed: ask your user before running the Next step" : "run the Next step later, when the service it waits on may answer faster";
+}
+function deadlineError(commandLine, ms, advice, bound = "deadline") {
+	return new CliError({
+		code: DEADLINE_EXCEEDED,
+		message: `${commandLine} ran past its ${ms} ms ${BOUND_WORDS[bound]}`,
+		...advice
+	});
+}
+/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
+var RunControl = class {
+	signal;
+	#controller = new AbortController();
+	#commandLine;
+	#rerun;
+	#outer;
+	#onOuterAbort = () => this.#controller.abort(interruptedError(this.#rerun));
+	/** 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 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, rerun, outer, clock, progress, runDeadline }) {
+		this.#commandLine = commandLine;
+		this.#rerun = rerun;
+		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, advice } = runDeadline;
+			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, advice())));
+		}
+	}
+	deadline(ms, options = {}) {
+		return options.ignoreStop === true ? this.#abortsAfter(ms, "ignoreStop") : AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
+	}
+	#abortsAfter(ms, bound) {
+		const controller = new AbortController();
+		after(this.#clock, ms, this.#disposed.signal, () => {
+			const advice = {
+				hint: waitHint(bound),
+				next: [this.#rerun]
+			};
+			const reason = deadlineError(this.#commandLine, ms, advice, 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 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/context/operator.js
+const NEEDS_OPERATOR = "NEEDS_OPERATOR";
+/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
+function checkOperator({ operator, commandLine }, env, rerun) {
+	if (!operator || !isAgent(env)) return;
+	throw new CliError({
+		code: NEEDS_OPERATOR,
+		message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
+		hint: "ask the operator to type ! then the Next step",
+		next: [rerun]
+	});
+}
+//#endregion
+//#region ../agent-cli/dist/context/files.js
+const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
+/** Where the Runtime writes `path` before moving it into place; a dead writer's is swept. */
+function tempPathOf(path) {
+	return join(dirname(path), `.${basename(path)}.agent-cli-${process.pid}.tmp`);
+}
+function isAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return errnoOf(error) === "EPERM";
+	}
+}
+async function sweep(folder) {
+	const dead = (await readdir(folder)).filter((name) => {
+		const pid = TEMP_FILE.exec(name)?.[1];
+		return pid !== void 0 && !isAlive(Number(pid));
+	});
+	await Promise.all(dead.map((name) => rm(join(folder, name), { force: true })));
+}
+/** The file a symlink at `path` points to, so a replacing write keeps the link. */
+async function targetOf$1(path) {
+	try {
+		return await realpath(path);
+	} catch (error) {
+		if (isMissingFile(error)) return path;
+		throw error;
+	}
+}
+async function writeWithMode(path, data, mode) {
+	if (mode === void 0) {
+		await writeFile(path, data);
+		return;
+	}
+	await writeFile(path, data, { mode });
+	await chmod(path, mode);
+}
+/** What `link` answers on a file system without hard links, such as exFAT. */
+const NO_HARD_LINKS = /* @__PURE__ */ new Set([
+	"EPERM",
+	"ENOTSUP",
+	"EXDEV"
+]);
+/** A link fails atomically when `path` is taken, so no reader ever sees half a file there. */
+async function linkNew(temp, path, data, mode) {
+	try {
+		await link(temp, path);
+	} catch (error) {
+		if (!NO_HARD_LINKS.has(errnoOf(error))) throw error;
+		await createNew(path, data, mode);
+	}
+}
+/** A file this call created and could not finish is removed, so a rerun does not find half of it. */
+async function createNew(path, data, mode) {
+	const handle = await open(path, "wx", mode);
+	try {
+		await handle.writeFile(data);
+		if (mode !== void 0) await handle.chmod(mode);
+	} catch (error) {
+		await handle.close();
+		await rm(path, { force: true });
+		throw error;
+	}
+	await handle.close();
+}
+const RENAME_ATTEMPTS = 10;
+const RENAME_BACKOFF_MS = 10;
+const HELD_BY_ANOTHER_PROGRAM = /* @__PURE__ */ new Set(["EPERM", "EBUSY"]);
+async function renameRetrying(from, to) {
+	for (let attempt = 1;; attempt++) try {
+		await rename(from, to);
+		return;
+	} catch (error) {
+		if (!(process.platform === "win32" && HELD_BY_ANOTHER_PROGRAM.has(errnoOf(error))) || attempt === RENAME_ATTEMPTS) throw error;
+		await setTimeout$1(attempt * RENAME_BACKOFF_MS);
+	}
+}
+/** Real files for one run: the first write to each folder sweeps the temp files of dead writers. */
+function realFiles() {
+	const swept = /* @__PURE__ */ new Set();
+	return {
+		exists: async (path) => {
+			try {
+				await access(path);
+				return true;
+			} catch (error) {
+				if (isNothingThere(error)) return false;
+				throw error;
+			}
+		},
+		write: async (path, data, options = {}) => {
+			await mkdir(dirname(path), { recursive: true });
+			const target = options.exclusive === true ? path : await targetOf$1(path);
+			const folder = dirname(target);
+			if (!swept.has(folder)) {
+				await sweep(folder);
+				swept.add(folder);
+			}
+			const temp = tempPathOf(target);
+			try {
+				await writeWithMode(temp, data, options.mode);
+				if (options.exclusive === true) {
+					await linkNew(temp, target, data, options.mode);
+					await rm(temp);
+				} else await renameRetrying(temp, target);
+			} catch (error) {
+				await rm(temp, { force: true });
+				throw error;
+			}
+		},
+		read: (path) => readFile(path),
+		list: (folder) => readdir(folder),
+		remove: (path) => rm(path, {
+			recursive: true,
+			force: true
+		}),
+		mkdir: async (path, options) => {
+			const mode = options?.mode;
+			if (options?.exclusive !== true) {
+				await mkdir(path, {
+					recursive: true,
+					mode
+				});
+				return;
+			}
+			await mkdir(dirname(path), {
+				recursive: true,
+				mode
+			});
+			await mkdir(path, { mode });
+		},
+		stat: async (path) => {
+			try {
+				const found = await stat(path, { bigint: true });
+				return {
+					size: Number(found.size),
+					id: `${found.dev}:${found.ino}`,
+					folder: found.isDirectory()
+				};
+			} catch (error) {
+				if (isNothingThere(error)) return void 0;
+				throw error;
+			}
+		},
+		realPath: async (path) => {
+			try {
+				return await realpath(path);
+			} catch (error) {
+				if (isNothingThere(error)) return void 0;
+				throw error;
+			}
+		}
+	};
+}
+/**
+* `files` resolving paths against `cwd`, its failures classified by errno; `list` drops the
+* Runtime's temp files and sorts.
+*/
+function classifiedFiles(files, { cwd, fileError }) {
+	async function at(access, path, work) {
+		const target = resolve(cwd, path);
+		try {
+			return await work(target);
+		} catch (error) {
+			throw fileError(error, {
+				path: target,
+				access
+			});
+		}
+	}
+	return {
+		exists: (path) => at("read", path, (target) => files.exists(target)),
+		write: (path, data, options) => at("write", path, (target) => files.write(target, data, options)),
+		read: (path) => at("read", path, (target) => files.read(target)),
+		list: (folder) => at("read", folder, async (target) => (await files.list(target)).filter((name) => !TEMP_FILE.test(name)).sort()),
+		remove: (path) => at("write", path, (target) => files.remove(target)),
+		mkdir: (path, options) => at("write", path, (target) => files.mkdir(target, options)),
+		stat: (path) => at("read", path, (target) => files.stat(target)),
+		realPath: (path) => at("read", path, (target) => files.realPath(target))
+	};
+}
+//#endregion
+//#region ../agent-cli/dist/context/outputs.js
+const OUTPUT_EXISTS = "OUTPUT_EXISTS";
+/** The outputs of a run on `files`, whose paths resolve against `cwd`. */
+function outputsOf(files, { cwd, fileError }) {
+	const classified = classifiedFiles(files, {
+		cwd,
+		fileError
+	});
+	const unwritten = /* @__PURE__ */ new Set();
+	let forceStep = [];
+	const exclusiveWrite = async (path, data, options) => {
+		const target = resolve(cwd, path);
+		unwritten.delete(target);
+		try {
+			await classified.write(path, data, {
+				...options,
+				exclusive: true
+			});
+		} catch (error) {
+			unwritten.add(target);
+			if (!(error instanceof CliError) || error.code !== "ALREADY_EXISTS") throw error;
+			throw new CliError({
+				code: ALREADY_EXISTS,
+				message: error.message,
+				hint: "once the user agrees to replace it, run the Next step",
+				next: [forceStep]
+			}, { cause: error });
+		}
+	};
+	const guarded = {
+		...classified,
+		write: (path, data, options) => unwritten.has(resolve(cwd, path)) ? exclusiveWrite(path, data, options) : classified.write(path, data, options)
+	};
+	return {
+		files: guarded,
+		refuseOverwrite: async (outputs, { rerun, commandLine, force }) => {
+			if (force) return;
+			const found = await Promise.all(outputs.map((path) => guarded.exists(path)));
+			const existing = outputs.filter((_path, index) => found[index]);
+			if (existing.length === 0) return;
+			const them = existing.length === 1 ? "it" : "them";
+			throw new CliError({
+				code: OUTPUT_EXISTS,
+				message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
+				hint: `once the user agrees to replace ${them}, run the Next step`,
+				next: [rerun({ add: [FORCE_FLAG.flag] })]
+			});
+		},
+		claim: async (outputs, { rerun, force }) => {
+			await probe(outputs, files, {
+				cwd,
+				fileError
+			});
+			if (force) return;
+			forceStep = rerun({ add: [FORCE_FLAG.flag] });
+			for (const path of outputs) unwritten.add(resolve(cwd, path));
+		}
+	};
+}
+async function probe(outputs, files, { cwd, fileError }) {
+	const folders = new Set(outputs.map((path) => dirname(resolve(cwd, path))));
+	await Promise.all([...folders].map(async (folder) => {
+		const probePath = tempPathOf(join(folder, "outputs-probe"));
+		try {
+			await files.mkdir(folder);
+			await files.write(probePath, "");
+			await files.remove(probePath);
+		} catch (error) {
+			throw fileError(error, {
+				path: folder,
+				access: "write"
+			});
+		}
+	}));
+}
+//#endregion
+//#region ../agent-cli/dist/context/project.js
+const PROJECT_INVALID = "PROJECT_INVALID";
+function invalid(path, problem, rerun, options) {
+	return new CliError({
+		code: PROJECT_INVALID,
+		message: `the Project file ${path} is invalid: ${problem}`,
+		hint: `fix ${path}, then run the Next step`,
+		next: [rerun]
+	}, options);
+}
+function readText(path, fileError) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return void 0;
+		throw fileError(error, {
+			path,
+			access: "read"
+		});
+	}
+}
+function parsed(path, text, schema, rerun) {
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch (error) {
+		throw invalid(path, messageOf(error), rerun, { cause: error });
+	}
+	const result = schema.safeParse(json);
+	if (!result.success) throw invalid(path, prettifyError(result.error), rerun);
+	return result.data;
+}
+function projectFrom(projectFile, folder, scope) {
+	const path = join(folder, projectFile.file);
+	const text = readText(path, scope.fileError);
+	if (text !== void 0) return {
+		root: folder,
+		settings: parsed(path, text, projectFile.schema, scope.rerun)
+	};
+	const parent = dirname(folder);
+	return parent === folder ? void 0 : projectFrom(projectFile, parent, scope);
+}
+/** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
+function projectOf(projectFile, cwd, scope) {
+	return projectFrom(projectFile, resolve(cwd), scope);
+}
+//#endregion
+//#region ../agent-cli/dist/context/secrets.js
+const SECRET_MISSING = "SECRET_MISSING";
+/** `$XDG_CONFIG_HOME/<cli>/.env`, with `~/.config` when the variable is unset or empty. */
+function envFileOf(cliName, env) {
+	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+	return join(config, cliName, ".env");
+}
+function readDotenv(path, fileError) {
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return {};
+		throw fileError(error, {
+			path,
+			access: "read"
+		});
+	}
+	return parseEnv(text);
+}
+/** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
+function secretOf({ envFile, env, fileError }, name) {
+	const fromEnv = env[name];
+	if (fromEnv) return {
+		value: fromEnv,
+		origin: { kind: "env" }
+	};
+	const fromFile = readDotenv(envFile, fileError)[name];
+	return fromFile ? {
+		value: fromFile,
+		origin: {
+			kind: "file",
+			path: envFile
+		}
+	} : void 0;
+}
+function isNeeded({ optional }) {
+	return optional !== true;
+}
+function missingIn(scope, secrets) {
+	return secrets.filter((secret) => isNeeded(secret) && secretOf(scope, secret.name) === void 0);
+}
+function getItFrom({ get }) {
+	return `(get it from ${get})`;
+}
+function whereToGet(secrets) {
+	return secrets.map((secret) => `${secret.name} ${getItFrom(secret)}`).join(", ");
+}
+/** Fails with `SECRET_MISSING`, naming every missing Secret at once, unless all are set. */
+function checkSecrets(secrets, scope, rerun) {
+	const missing = missingIn(scope, secrets);
+	if (missing.length === 0) return;
+	const names = missing.map(({ name }) => name).join(", ");
+	throw new CliError({
+		code: SECRET_MISSING,
+		message: `${missing.length === 1 ? "a Secret it needs is" : "Secrets it needs are"} not set: ${names}`,
+		hint: `set ${whereToGet(missing)} in the environment or in ${scope.envFile}, then run the Next step`,
+		next: [rerun]
+	});
+}
+function originOf({ origin }) {
+	return origin.kind === "env" ? "the environment" : origin.path;
+}
+/**
+* The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. A
+* name needed anywhere counts as needed, and an unset optional one goes unmentioned.
+*/
+function secretRows(secrets, commands) {
+	const declared = declaredIn(secrets, commands, (command) => command.secrets);
+	if (declared.length === 0) return [];
+	const needed = new Map(declaredIn(secrets.filter(isNeeded), commands, (command) => command.secrets?.filter(isNeeded)).map((declaration) => [declaration.name, declaration]));
+	return [{
+		name: "secrets",
+		run: ({ env, envFile, fileError }) => {
+			const read = declared.map((declaration) => ({
+				declaration,
+				secret: secretOf({
+					env,
+					envFile,
+					fileError
+				}, declaration.name)
+			}));
+			const missing = read.flatMap(({ declaration, secret }) => {
+				const neededAs = needed.get(declaration.name);
+				return secret === void 0 && neededAs !== void 0 ? [neededAs] : [];
+			});
+			if (missing.length > 0) return {
+				state: "problem",
+				message: `${missing.map((declaration) => `${declaration.name} is not set ${getItFrom(declaration)}`).join(", ")}; add ${missing.length === 1 ? "it" : "them"} to ${envFile} or the environment`
+			};
+			const found = read.flatMap(({ declaration, secret }) => secret === void 0 ? [] : [`${declaration.name} from ${originOf(secret)}`]);
+			return {
+				state: "ok",
+				message: found.length > 0 ? found.join(", ") : "no Secret is set, and none is needed"
+			};
+		}
+	}];
+}
+//#endregion
+//#region ../agent-cli/dist/runtime-codes.js
+const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
+const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
+const NOT_ON_PATH = "NOT_ON_PATH";
+const REGISTRY_UNREACHABLE = "REGISTRY_UNREACHABLE";
+const REGISTRY_AUTH = "REGISTRY_AUTH";
+const INSTALL_FAILED = "INSTALL_FAILED";
+const NPM_FAILED = "NPM_FAILED";
+const NO_LATEST = "NO_LATEST";
+/** The Runtime codes any Command can meet, which no Command declares. */
+const anyCommandErrors = {
+	[INVALID_INPUT]: { class: "caller" },
+	[UNKNOWN_OPTION]: { class: "caller" },
+	[UNKNOWN_COMMAND]: { class: "caller" },
+	[UNKNOWN_FIELD]: { class: "caller" },
+	[CONFIRMATION_REQUIRED]: { class: "caller" },
+	[CONFIRMATION_MISMATCH]: { class: "caller" },
+	[NOT_CONFIRMED]: { class: "operator" },
+	[NEEDS_OPERATOR]: { class: "operator" },
+	[OUTPUT_EXISTS]: { class: "caller" },
+	[STDIN_STALLED]: { class: "caller" },
+	[INTERRUPTED]: { class: "interrupted" },
+	[DEADLINE_EXCEEDED]: { class: "wait" },
+	[INTERNAL]: { class: "bug" },
+	[PERMISSION_DENIED]: { class: "operator" },
+	[DISK_FULL]: { class: "operator" },
+	[NOT_FOUND]: { class: "caller" },
+	[ALREADY_EXISTS]: { class: "caller" },
+	[NOT_A_FILE]: { class: "caller" },
+	[TOOL_FAILED]: { class: "operator" },
+	[TOOL_MISSING]: { class: "operator" },
+	[SECRET_MISSING]: { class: "operator" },
+	[PROJECT_INVALID]: { class: "operator" }
+};
+/**
+* The Runtime codes only some Commands reach: each Command that throws one, Built-in or the CLI's
+* own, declares it in `errors`, as it does a code of the CLI's Error table.
+*/
+const declaredRuntimeErrors = {
+	[DOCTOR_PROBLEMS]: { class: "operator" },
+	[NOT_GLOBAL_INSTALL]: { class: "operator" },
+	[NOT_ON_PATH]: { class: "operator" },
+	[REGISTRY_UNREACHABLE]: { class: "operator" },
+	[REGISTRY_AUTH]: { class: "operator" },
+	[INSTALL_FAILED]: { class: "operator" },
+	[NPM_FAILED]: { class: "operator" },
+	[NO_LATEST]: { class: "source" }
+};
+/** The Runtime's own Error table: every code it fails a run with, and the class that must act. */
+const runtimeErrors = {
+	...anyCommandErrors,
+	...declaredRuntimeErrors
+};
+const anyCommandClasses = Object.values(anyCommandErrors).map((declaration) => declaration.class);
+function isRuntimeCode(code) {
+	return Object.hasOwn(runtimeErrors, code);
+}
+function isDeclaredRuntimeCode(code) {
+	return Object.hasOwn(declaredRuntimeErrors, code);
+}
+/** Whether a Command or `doctor` row throwing `code` must declare it: a code of `table`, or a Runtime one only some reach. */
+function mustDeclare(code, table) {
+	return Object.hasOwn(table, code) || isDeclaredRuntimeCode(code);
+}
+//#endregion
+//#region ../agent-cli/dist/define-command.js
+/** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
+function checkCommand(command, label, table) {
+	checkNoStandardFlags(command, label);
+	checkForce(command, label);
+	checkArrayArgLast(label, command.args);
+	checkStdinFields(label, command.args, command.options);
+	checkNoBooleanArrayOption(label, command.options);
+	checkErrors(command.errors ?? [], label, table);
+}
+/** Throws on a code in `errors` that is neither in `table` nor a Runtime code some Commands declare. */
+function checkErrors(errors, label, table) {
+	const unknown = errors.filter((code) => !mustDeclare(code, table));
+	if (unknown.length > 0) throw new Error(`${label} declares ${unknown.join(", ")} in errors, a code the Error table lacks`);
+}
+function defineCommandFor() {
+	return {
+		list: withEffect("read"),
+		read: withEffect("read"),
+		act: withEffect("act"),
+		serve: withEffect("serve"),
+		write: withEffect("write"),
+		destructive: withEffect("destructive")
+	};
+}
+function withEffect(effect) {
+	return (command) => ({
+		...command,
+		effect
+	});
+}
+const defineCommand$1 = defineCommandFor();
+//#endregion
+//#region ../agent-cli/dist/error-table.js
+/** The Error table a CLI declares, empty when it declares none. */
+function errorTableOf({ errors }) {
+	return errors ?? {};
+}
+/** The `CliError` for a code of `Table`, as `cliError` and `ctx.fail` build it. */
+function cliErrorOf(code, init, options) {
+	return new CliError({
+		...init,
+		code
+	}, options);
+}
+//#endregion
+//#region ../agent-cli/dist/version.js
+/** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
+function buildStamp() {
+	return {
+		"sha": "0478338",
+		"dirty": false,
+		"builtAt": "2026-11-09T05:16:34.000Z"
+	};
+}
+/** The first line of `--version`: the version, and the commit and time of a stamped build. */
+function versionLine({ version }) {
+	const build = buildStamp();
+	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
+}
+//#endregion
+//#region ../agent-cli/dist/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,
@@ -7207,12 +7807,15 @@ function meetsMinimum(version, minimum) {
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/npm.js
-const REGISTRY_UNREACHABLE = "REGISTRY_UNREACHABLE";
-const REGISTRY_AUTH = "REGISTRY_AUTH";
-const INSTALL_FAILED = "INSTALL_FAILED";
-const NPM_FAILED = "NPM_FAILED";
-const NO_LATEST = "NO_LATEST";
-function npmContext(cli, registry, ctx, node, cwd) {
+/** What a Command running npm may fail with, for it to declare in `errors`. */
+const NPM_ERRORS = [
+	REGISTRY_UNREACHABLE,
+	REGISTRY_AUTH,
+	INSTALL_FAILED,
+	NPM_FAILED,
+	NO_LATEST
+];
+function npmContext(cli, registry, ctx, { node, platform }, cwd) {
 	return {
 		cliName: cli.name,
 		rerun: ctx.rerun(),
@@ -7220,7 +7823,9 @@ function npmContext(cli, registry, ctx, node, cwd) {
 		cwd,
 		env: ctx.env,
 		signal: ctx.signal,
-		node
+		node,
+		platform,
+		files: ctx.files
 	};
 }
 const STDERR_TAIL_LINES = 10;
@@ -7262,9 +7867,10 @@ function setupCommandLine({ package: name, flags }) {
 		"setup"
 	].join(" ");
 }
-function npmOf(ctx, windows) {
+async function npmOf(ctx) {
+	const windows = ctx.platform === "win32";
 	const beside = ctx.node === void 0 ? void 0 : join(dirname(ctx.node), windows ? "npm.cmd" : "npm");
-	if (beside === void 0 || !existsSync(beside)) return {
+	if (beside === void 0 || !await ctx.files.exists(beside)) return {
 		path: "npm",
 		env: ctx.env
 	};
@@ -7281,8 +7887,7 @@ function npmOf(ctx, windows) {
 		}
 	};
 }
-function spawnNpm(args, ctx, signal) {
-	const npm = npmOf(ctx, process.platform === "win32");
+function spawnNpm(npm, args, ctx, signal) {
 	return spawnChild(npm.path, args, {
 		cwd: ctx.cwd,
 		env: npm.env,
@@ -7300,7 +7905,7 @@ function authHint(code, ctx) {
 	if (code !== "E403" || !isAgent(ctx.env)) return login;
 	return `a Coding agent's sandbox may refuse ${registry} with a 403: ask your user to type ! and ${RUN_AGAIN}, or to allow ${registry} in the sandbox's network list; if it fails outside the sandbox too, ${login}`;
 }
-function failureOf(call, answer, ctx) {
+function failureOf$1(call, answer, ctx) {
 	const { label: registry, package: name, unreachableHint } = ctx.registry;
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
@@ -7345,7 +7950,7 @@ function noLatest(ctx, message) {
 async function runNpm(call, args, ctx, signal = ctx.signal) {
 	const cache = await mkdtemp(join(tmpdir(), `${ctx.cliName}-npm-`));
 	try {
-		const answer = await spawnNpm([
+		const answer = await spawnNpm(await npmOf(ctx), [
 			...args,
 			`--cache=${join(cache, "cache")}`,
 			"--logs-max=0"
@@ -7357,7 +7962,7 @@ async function runNpm(call, args, ctx, signal = ctx.signal) {
 				hint: "install Node with npm, or put npm on PATH"
 			}, { cause: error });
 		});
-		if (answer.exitCode !== 0) throw failureOf(call, answer, ctx);
+		if (answer.exitCode !== 0) throw failureOf$1(call, answer, ctx);
 		return answer.stdout;
 	} finally {
 		await rm(cache, {
@@ -7407,6 +8012,30 @@ async function latestVersion(ctx) {
 	return version;
 }
 //#endregion
+//#region ../agent-cli/dist/built-ins/read.js
+function isNotFound(error) {
+	return error instanceof CliError && error.code === "NOT_FOUND";
+}
+const decoder = new TextDecoder();
+/** The text of the file at `path`, or `undefined` when nothing is there. */
+async function readIfAny(files, path) {
+	try {
+		return decoder.decode(await files.read(path));
+	} catch (error) {
+		if (isNotFound(error)) return void 0;
+		throw error;
+	}
+}
+/** The text of a file the CLI's own package ships, whose absence is the release's bug. */
+async function readRequired(files, path) {
+	try {
+		return decoder.decode(await files.read(path));
+	} catch (error) {
+		if (!isNotFound(error)) throw error;
+		throw new Error(`the package is missing its own file ${path}`, { cause: error });
+	}
+}
+//#endregion
 //#region ../agent-cli/dist/built-ins/project-root.js
 const MANAGERS = [
 	"pnpm",
@@ -7431,22 +8060,14 @@ function ancestorsOf(dir) {
 	const parent = dirname(dir);
 	return parent === dir ? [dir] : [dir, ...ancestorsOf(parent)];
 }
-async function exists(path) {
-	return await orMissing(stat(path)) !== void 0;
-}
 /** Whether `path` lies strictly inside `dir`. */
 function isInside(dir, path) {
 	const inner = relative(dir, path);
 	return inner !== "" && !inner.startsWith("..") && !isAbsolute(inner);
 }
-async function manifestIn(dir) {
-	let text;
-	try {
-		text = await readFile(join(dir, "package.json"), "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return void 0;
-		throw error;
-	}
+async function manifestIn(files, dir) {
+	const text = await readIfAny(files, join(dir, "package.json"));
+	if (text === void 0) return void 0;
 	let manifest;
 	try {
 		manifest = JSON.parse(text);
@@ -7455,19 +8076,19 @@ async function manifestIn(dir) {
 	}
 	return manifestSchema$1.safeParse(manifest).data;
 }
-async function declaredManager(dir) {
-	const name = (await manifestIn(dir))?.packageManager?.split("@")[0];
+async function declaredManager(files, dir) {
+	const name = (await manifestIn(files, dir))?.packageManager?.split("@")[0];
 	return MANAGERS.find((manager) => manager === name);
 }
-async function lockfileRootOf(cwd) {
-	for (const dir of ancestorsOf(cwd)) for (const [file, kind] of LOCKFILES) if (await exists(join(dir, file))) return {
+async function lockfileRootOf(files, cwd) {
+	for (const dir of ancestorsOf(cwd)) for (const [file, kind] of LOCKFILES) if (await files.exists(join(dir, file))) return {
 		dir,
-		manager: await declaredManager(dir) ?? kind
+		manager: await declaredManager(files, dir) ?? kind
 	};
 }
 /** The package manager's project root: the folder of the nearest lockfile, or `cwd` without one. */
-async function projectRootOf(cwd) {
-	return (await lockfileRootOf(cwd))?.dir ?? cwd;
+async function projectRootOf(files, cwd) {
+	return (await lockfileRootOf(files, cwd))?.dir ?? cwd;
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/install/run-as.js
@@ -7490,29 +8111,30 @@ const LINES = {
 	}
 };
 const packageSchema = object({ version: string() });
-async function manifestListing(name, cwd, root) {
+async function manifestListing(files, name, cwd, root) {
 	const dirs = ancestorsOf(cwd);
 	const top = root === void 0 ? dirs.length : dirs.indexOf(root.dir) + 1;
 	for (const dir of dirs.slice(0, top)) {
-		const manifest = await manifestIn(dir);
+		const manifest = await manifestIn(files, dir);
 		if (manifest?.dependencies?.[name] !== void 0 || manifest?.devDependencies?.[name] !== void 0) return join(dir, "package.json");
 	}
 }
-async function versionIn(manifest) {
+function versionIn(text) {
 	try {
-		return packageSchema.parse(JSON.parse(await readFile(manifest, "utf8"))).version;
+		return packageSchema.parse(JSON.parse(text)).version;
 	} catch (error) {
 		if (error instanceof SyntaxError || error instanceof ZodError) return { reason: messageOf(error) };
 		throw error;
 	}
 }
-async function standingOf(install, bin, cwd, root) {
+async function standingOf(files, install, bin, cwd, root) {
 	if (bin === void 0) return { kind: "source" };
 	for (const projectDir of ancestorsOf(cwd)) {
 		const folder = join(projectDir, "node_modules", install.package);
 		const manifest = join(folder, "package.json");
-		if (!await exists(manifest)) continue;
-		const version = await versionIn(manifest);
+		const text = await readIfAny(files, manifest);
+		if (text === void 0) continue;
+		const version = versionIn(text);
 		if (typeof version !== "string") return {
 			kind: "unreadable",
 			manifest,
@@ -7520,14 +8142,14 @@ async function standingOf(install, bin, cwd, root) {
 		};
 		const copy = {
 			projectDir,
-			realDir: await realpath(folder),
+			realDir: await files.realPath(folder) ?? folder,
 			version
 		};
 		if (!copy.realDir.split(sep).includes("node_modules")) return {
 			kind: "linked",
 			copy
 		};
-		const runningFrom = await orMissing(realpath(bin)) ?? bin;
+		const runningFrom = await files.realPath(bin) ?? bin;
 		return isInside(copy.realDir, runningFrom) ? {
 			kind: "installed",
 			copy
@@ -7537,18 +8159,18 @@ async function standingOf(install, bin, cwd, root) {
 			runningFrom
 		};
 	}
-	const manifest = await manifestListing(install.package, cwd, root);
+	const manifest = await manifestListing(files, install.package, cwd, root);
 	return manifest === void 0 ? { kind: "missing" } : {
 		kind: "listed",
 		manifest
 	};
 }
-async function surveyDependency(install, bin, cwd) {
-	const root = await lockfileRootOf(cwd);
+async function surveyDependency(install, bin, { files, cwd }) {
+	const root = await lockfileRootOf(files, cwd);
 	return {
 		cwd,
 		root,
-		standing: await standingOf(install, bin, cwd, root)
+		standing: await standingOf(files, install, bin, cwd, root)
 	};
 }
 function packagesOf(install) {
@@ -7618,19 +8240,19 @@ function adviceFor(install, root, latest) {
 	if (lines !== void 0) return { fix: lines.upgrade(packages) };
 	return { note: `move ${packages.length === 1 ? packages[0] : `${packages.slice(0, -1).join(", ")} and ${packages.at(-1)}`} to ${latest} with ${root?.manager ?? "the project's package manager"}` };
 }
-function checkOf$1(cli, install, runAs, { bin, node }) {
+function checkOf$1(cli, install, runAs, launch) {
 	let survey;
-	const surveyed = (cwd) => {
-		survey ??= surveyDependency(install, bin, cwd);
+	const surveyed = (ctx) => {
+		survey ??= surveyDependency(install, launch.bin, ctx);
 		return survey;
 	};
 	return {
-		install: async (ctx) => installFinding(cli, runAs, install, await surveyed(ctx.cwd)),
+		install: async (ctx) => installFinding(cli, runAs, install, await surveyed(ctx)),
 		release: async (ctx) => {
-			const { cwd, root, standing } = await surveyed(ctx.cwd);
+			const { cwd, root, standing } = await surveyed(ctx);
 			if (isUnchecked(standing)) return { skipped: skippedFor$1(cli, install, standing) };
 			return {
-				npm: npmContext(cli, registryOf(install, root?.dir), ctx, node, root?.dir ?? cwd),
+				npm: npmContext(cli, registryOf(install, root?.dir), ctx, launch, root?.dir ?? cwd),
 				advise: (latest) => adviceFor(install, root, latest)
 			};
 		}
@@ -7642,222 +8264,22 @@ function dependencyInstall(cli, install) {
 	return {
 		runAs,
 		builtIns: () => ({}),
-		exitClasses: [],
 		check: (launch) => checkOf$1(cli, install, runAs, launch),
 		notice: async () => {}
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/context/errno.js
-const PERMISSION_DENIED = "PERMISSION_DENIED";
-const DISK_FULL = "DISK_FULL";
-const NOT_FOUND = "NOT_FOUND";
-const ALREADY_EXISTS = "ALREADY_EXISTS";
-const NOT_A_FILE = "NOT_A_FILE";
-function permissionAdvice({ path, access, rerun, env, platform }) {
-	if (platform === "win32") return {
-		hint: `a program may hold ${path} open: close it, then run the Next step`,
-		next: [rerun]
-	};
-	if (!isAgent(env)) return { hint: `check the permissions of ${path} and its folder` };
-	return {
-		hint: `your sandbox may block it: ask your user to type ! then the Next step, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`,
-		next: [rerun]
-	};
-}
-function fileErrorOf(scope) {
-	return (error, at) => classifyErrno(error, {
-		...at,
-		...scope
-	});
-}
-function classifyErrno(error, context) {
-	const { path } = context;
-	switch (errnoOf(error)) {
-		case "EACCES":
-		case "EPERM":
-		case "EROFS":
-		case "EBUSY": return new CliError({
-			code: PERMISSION_DENIED,
-			message: `permission denied: ${path}`,
-			...permissionAdvice(context)
-		}, { cause: error });
-		case "ENOSPC":
-		case "EDQUOT": return new CliError({
-			code: DISK_FULL,
-			message: `no space left on the disk holding ${path}`,
-			hint: "free space on that disk, then run the Next step",
-			next: [context.rerun]
-		}, { cause: error });
-		case "ENOENT":
-		case "ENOTDIR":
-		case "ENAMETOOLONG": return new CliError({
-			code: NOT_FOUND,
-			message: `not found: ${path}`,
-			hint: `check that ${path} and its folder exist`
-		}, { cause: error });
-		case "EEXIST": return new CliError({
-			code: ALREADY_EXISTS,
-			message: `already exists: ${path}`,
-			hint: `pass another path, or remove ${path}`
-		}, { cause: error });
-		case "EISDIR": return new CliError({
-			code: NOT_A_FILE,
-			message: `not a file: ${path} is a folder`,
-			hint: `pass the path of a file, not of the folder ${path}`
-		}, { cause: error });
-		default: return error;
-	}
-}
-//#endregion
-//#region ../agent-cli/dist/context/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(rerun) {
-	return new CliError({
-		code: INTERRUPTED,
-		message: "interrupted before it finished",
-		hint: "to finish it, run the Next step, unless it was stopped on purpose; if a tool timeout stopped it, give it longer",
-		next: [rerun]
-	});
-}
-const BOUND_WORDS = {
-	deadline: "deadline",
-	ignoreStop: "timeout"
-};
-function waitHint(bound) {
-	return bound === "ignoreStop" ? "the call may have been billed: ask your user before running the Next step" : "run the Next step later, when the service it waits on may answer faster";
-}
-function deadlineError(commandLine, ms, advice, bound = "deadline") {
-	return new CliError({
-		code: DEADLINE_EXCEEDED,
-		message: `${commandLine} ran past its ${ms} ms ${BOUND_WORDS[bound]}`,
-		...advice
-	});
-}
-/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
-var RunControl = class {
-	signal;
-	#controller = new AbortController();
-	#commandLine;
-	#rerun;
-	#outer;
-	#onOuterAbort = () => this.#controller.abort(interruptedError(this.#rerun));
-	/** 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 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, rerun, outer, clock, progress, runDeadline }) {
-		this.#commandLine = commandLine;
-		this.#rerun = rerun;
-		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, advice } = runDeadline;
-			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, advice())));
-		}
-	}
-	deadline(ms, options = {}) {
-		return options.ignoreStop === true ? this.#abortsAfter(ms, "ignoreStop") : AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
-	}
-	#abortsAfter(ms, bound) {
-		const controller = new AbortController();
-		after(this.#clock, ms, this.#disposed.signal, () => {
-			const advice = {
-				hint: waitHint(bound),
-				next: [this.#rerun]
-			};
-			const reason = deadlineError(this.#commandLine, ms, advice, 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 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/install/global-npm.js
-const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
 /** Where npm puts global packages under its global prefix. */
-function globalModulesDir(prefix) {
-	return process.platform === "win32" ? join(prefix, "node_modules") : join(prefix, "lib", "node_modules");
+function globalModulesDir(prefix, platform) {
+	return platform === "win32" ? join(prefix, "node_modules") : join(prefix, "lib", "node_modules");
+}
+/** Whether `path` itself is a symlink, which a link in a folder above it does not make it. */
+async function isLink(files, path) {
+	const real = await files.realPath(path);
+	if (real === void 0) return false;
+	const folder = await files.realPath(dirname(path));
+	return folder === void 0 || real !== join(folder, basename(path));
 }
 function notGlobal(ctx, message) {
 	return runtimeError({
@@ -7874,11 +8296,11 @@ function notGlobal(ctx, message) {
 async function globalInstallOf(bin, ctx) {
 	if (bin === void 0) throw notGlobal(ctx, `${ctx.cliName} runs from source, not from an npm install`);
 	const prefix = await globalPrefix(ctx);
-	const packageDir = join(globalModulesDir(prefix), ctx.registry.package);
-	const installed = await orMissing(realpath(packageDir));
-	const here = await orMissing(realpath(bin)) ?? bin;
+	const packageDir = join(globalModulesDir(prefix, ctx.platform), ctx.registry.package);
+	const installed = await ctx.files.realPath(packageDir);
+	const here = await ctx.files.realPath(bin) ?? bin;
 	if (installed === void 0 || !isInside(installed, here)) throw notGlobal(ctx, `${ctx.cliName} runs from ${here}, not from npm's global install at ${packageDir}`);
-	if ((await lstat(packageDir)).isSymbolicLink()) throw notGlobal(ctx, `${ctx.cliName} runs from a link to ${installed} (npm link), not from an npm install`);
+	if (await isLink(ctx.files, packageDir)) throw notGlobal(ctx, `${ctx.cliName} runs from a link to ${installed} (npm link), not from an npm install`);
 	return {
 		prefix,
 		packageDir
@@ -7907,25 +8329,32 @@ function globalRegistry(install) {
 	};
 }
 /** npm for a Global install, run in the working directory. */
-function globalNpm(cli, install, ctx, node) {
-	return npmContext(cli, globalRegistry(install), ctx, node, ctx.cwd);
+function globalNpm(cli, install, ctx, launch) {
+	return npmContext(cli, globalRegistry(install), ctx, launch, ctx.cwd);
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/skill/sync.js
-/** Every file under `dir`, relative to it and sorted; none when `dir` is missing. */
-async function filesIn(dir) {
-	return (await orMissing(readdir(dir, {
-		recursive: true,
-		withFileTypes: true
-	})) ?? []).filter((entry) => entry.isFile()).map((entry) => relative(dir, join(entry.parentPath, entry.name))).sort();
-}
-async function sameContent(left, right) {
-	const [a, b] = await Promise.all([readFile(left), readFile(right)]);
-	return a.equals(b);
-}
-async function syncOf(source, copy) {
-	const [shipped, present] = await Promise.all([filesIn(source), filesIn(copy)]);
-	const differs = await Promise.all(shipped.map(async (file) => present.includes(file) && !await sameContent(join(source, file), join(copy, file))));
+async function walk$1(files, dir, inner) {
+	const names = await files.list(join(dir, inner));
+	return (await Promise.all(names.map(async (name) => {
+		const path = join(inner, name);
+		const found = await files.stat(join(dir, path));
+		if (found === void 0) return [];
+		return found.folder ? walk$1(files, dir, path) : [path];
+	}))).flat();
+}
+/** Every file under `dir`, relative to it and sorted; none when `dir` is no folder. */
+async function filesIn(files, dir) {
+	if ((await files.stat(dir))?.folder !== true) return [];
+	return (await walk$1(files, dir, "")).sort();
+}
+async function sameContent(files, left, right) {
+	const [a, b] = await Promise.all([files.read(left), files.read(right)]);
+	return Buffer.from(a).equals(b);
+}
+async function syncOf(files, source, copy) {
+	const [shipped, present] = await Promise.all([filesIn(files, source), filesIn(files, copy)]);
+	const differs = await Promise.all(shipped.map(async (file) => present.includes(file) && !await sameContent(files, join(source, file), join(copy, file))));
 	return {
 		source,
 		copy,
@@ -7935,7 +8364,7 @@ async function syncOf(source, copy) {
 	};
 }
 async function applySync(sync, ctx) {
-	for (const file of [...sync.write, ...sync.replace]) await ctx.files.write(join(sync.copy, file), await readFile(join(sync.source, file)));
+	for (const file of [...sync.write, ...sync.replace]) await ctx.files.write(join(sync.copy, file), await ctx.files.read(join(sync.source, file)));
 	for (const file of sync.remove) await ctx.files.remove(join(sync.copy, file));
 }
 //#endregion
@@ -7956,9 +8385,9 @@ function homeOf(env) {
 	return env.HOME ?? env.USERPROFILE ?? homedir();
 }
 /** The home folders of the Skill copy; the skills installer may have made one a link to the other. */
-async function homeCopiesOf(name, env) {
+async function homeCopiesOf(files, name, env) {
 	const paths = SKILL_DIRS.map((dir) => join(homeOf(env), ...dir, name));
-	const reals = await Promise.all(paths.map(async (path) => orMissing(realpath(path))));
+	const reals = await Promise.all(paths.map((path) => files.realPath(path)));
 	return paths.filter((_path, index) => {
 		const real = reals[index];
 		return real === void 0 || reals.indexOf(real) === index;
@@ -7976,9 +8405,9 @@ const homeSyncSchema = object({
 async function syncHome(cli, packageDir, ctx) {
 	if (cli.skill === void 0) return null;
 	const source = join(packageDir, cli.skill.folder);
-	if ((await filesIn(source)).length === 0) return null;
-	const copies = await homeCopiesOf(cli.name, ctx.env);
-	const syncs = await Promise.all(copies.map((copy) => syncOf(source, copy)));
+	if ((await filesIn(ctx.files, source)).length === 0) return null;
+	const copies = await homeCopiesOf(ctx.files, cli.name, ctx.env);
+	const syncs = await Promise.all(copies.map((copy) => syncOf(ctx.files, source, copy)));
 	for (const sync of syncs) await applySync(sync, ctx);
 	return {
 		copies,
@@ -7995,19 +8424,25 @@ function renderHomeSync(name, sync) {
 	const at = sync.copies.join(", ");
 	return sync.written.length + sync.removed.length === 0 ? [`the ${name} skill at ${at} already matches the package`] : [`copied the ${name} skill to ${at}: wrote ${sync.written.length} files, removed ${sync.removed.length}`];
 }
-async function homeCopyAt(path) {
+async function homeCopyAt(files, path) {
+	let text;
 	try {
-		return {
-			path,
-			state: "readable",
-			stated: skillVersionIn(await readFile(join(path, "SKILL.md"), "utf8"))
-		};
+		text = await readIfAny(files, join(path, "SKILL.md"));
 	} catch (error) {
+		if (!(error instanceof CliError)) throw error;
 		return {
 			path,
-			state: isMissingFile(error) ? "missing" : "unreadable"
+			state: "unreadable"
 		};
 	}
+	return text === void 0 ? {
+		path,
+		state: "missing"
+	} : {
+		path,
+		state: "readable",
+		stated: skillVersionIn(text)
+	};
 }
 function describeCopy(copy) {
 	if (copy.state === "missing") return `no copy at ${copy.path}`;
@@ -8015,8 +8450,8 @@ function describeCopy(copy) {
 	return copy.stated === void 0 ? copy.path : `${copy.path} (${statedVersionNote(copy.stated)})`;
 }
 async function findingOf$1(cli, folder, install, ctx) {
-	const paths = await homeCopiesOf(cli.name, ctx.env);
-	const [copies, shipped] = await Promise.all([Promise.all(paths.map(homeCopyAt)), orMissing(readFile(join(ctx.packageRoot, folder, "SKILL.md"), "utf8"))]);
+	const paths = await homeCopiesOf(ctx.files, cli.name, ctx.env);
+	const [copies, shipped] = await Promise.all([Promise.all(paths.map((path) => homeCopyAt(ctx.files, path))), readIfAny(ctx.files, join(ctx.packageRoot, folder, "SKILL.md"))]);
 	const message = copies.map(describeCopy).join("; ");
 	const shipsStated = shipped !== void 0 && skillVersionIn(shipped) !== void 0;
 	return copies.every((copy) => copy.state === "readable" && (copy.stated === void 0 || shipsStated)) ? {
@@ -8094,14 +8529,9 @@ function upgradeOf({ version, lines }) {
 * What each release after `from` up to `to` asks of the operator, oldest first, from the
 * CHANGELOG.md in `packageDir`; none when the package ships no CHANGELOG.
 */
-async function upgradesOf(packageDir, from, to) {
-	let changelog;
-	try {
-		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return [];
-		throw error;
-	}
+async function upgradesOf(files, packageDir, from, to) {
+	const changelog = await readIfAny(files, join(packageDir, "CHANGELOG.md"));
+	if (changelog === void 0) return [];
 	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version)).flatMap(upgradeOf);
 }
 function renderUpgrade(upgrade) {
@@ -8109,7 +8539,6 @@ function renderUpgrade(upgrade) {
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/setup.js
-const NOT_ON_PATH = "NOT_ON_PATH";
 const setupSchema = object({
 	version: string(),
 	prefix: string(),
@@ -8119,8 +8548,8 @@ const setupSchema = object({
 	docs: string().nullable()
 });
 const installedManifest = object({ version: string() });
-async function versionAt(packageDir) {
-	const text = await orMissing(readFile(join(packageDir, "package.json"), "utf8"));
+async function versionAt(files, packageDir) {
+	const text = await readIfAny(files, join(packageDir, "package.json"));
 	if (text === void 0) return null;
 	try {
 		const parsed = installedManifest.safeParse(JSON.parse(text));
@@ -8130,26 +8559,29 @@ async function versionAt(packageDir) {
 		throw error;
 	}
 }
-function npmOfSetup(cli, install, ctx, node) {
+function npmOfSetup(cli, install, ctx, launch) {
 	return {
-		...globalNpm(cli, install, ctx, node),
+		...globalNpm(cli, install, ctx, launch),
 		rerun: wholeLine(setupLineOf(install))
 	};
 }
 function needsInstall({ from, latest }) {
 	return from === null || standingOf$1(from, latest) === "behind";
 }
-function binDirOf(prefix) {
-	return process.platform === "win32" ? prefix : join(prefix, "bin");
+function binDirOf(prefix, platform) {
+	return platform === "win32" ? prefix : join(prefix, "bin");
 }
-async function canonical(path) {
-	return normalize(await realpath(path).catch(() => path));
+async function canonical(files, path) {
+	const real = await files.realPath(path).catch((error) => {
+		if (!(error instanceof CliError) && errnoOf(error) === void 0) throw error;
+	});
+	return normalize(real ?? path);
 }
-async function assertOnPath(cli, prefix, node, ctx) {
-	const binDir = binDirOf(prefix);
-	const wanted = await canonical(binDir);
+async function assertOnPath(cli, prefix, { node, platform }, ctx) {
+	const binDir = binDirOf(prefix, platform);
+	const wanted = await canonical(ctx.files, binDir);
 	const entries = pathOf(ctx.env).split(delimiter).filter(Boolean);
-	if ((await Promise.all(entries.map(canonical))).includes(wanted)) return;
+	if ((await Promise.all(entries.map((entry) => canonical(ctx.files, entry)))).includes(wanted)) return;
 	throw runtimeError({
 		code: NOT_ON_PATH,
 		message: `${cli.name} is installed in ${binDir}, by the npm of ${node ?? "the Node on PATH"}, a folder not on this shell's PATH`,
@@ -8181,8 +8613,8 @@ function renderSetup(cli, install, setup) {
 	].join("\n");
 }
 /** The built-in `setup`, which runs from any copy, such as npx's, so it never asks to be the global one. */
-function setupCommand(cli, install, { node }) {
-	return defineCommand$1({
+function setupCommand(cli, install, launch) {
+	return defineCommand$1.write({
 		description: "install this CLI and its skill on this machine",
 		examples: [{
 			command: `${cli.name} setup`,
@@ -8191,13 +8623,17 @@ function setupCommand(cli, install, { node }) {
 			command: `${cli.name} setup --dry-run`,
 			note: "show what it would change"
 		}],
-		effect: "write",
+		errors: [
+			NOT_GLOBAL_INSTALL,
+			NOT_ON_PATH,
+			...NPM_ERRORS
+		],
 		output: setupSchema,
 		plan: async (_input, ctx) => {
-			const npm = npmOfSetup(cli, install, ctx, node);
+			const npm = npmOfSetup(cli, install, ctx, launch);
 			const prefix = await globalPrefix(npm);
-			const packageDir = join(globalModulesDir(prefix), install.package);
-			if ((await orMissing(lstat(packageDir)))?.isSymbolicLink() === true) throw runtimeError({
+			const packageDir = join(globalModulesDir(prefix, launch.platform), install.package);
+			if (await isLink(ctx.files, packageDir)) throw runtimeError({
 				code: NOT_GLOBAL_INSTALL,
 				message: `${packageDir} is a link (npm link), which an install would replace`,
 				hint: "remove the link with npm unlink, then run the Next step",
@@ -8205,309 +8641,136 @@ function setupCommand(cli, install, { node }) {
 			});
 			return {
 				package: install.package,
-				from: await versionAt(packageDir),
+				from: await versionAt(ctx.files, packageDir),
 				latest: await latestVersion(npm),
 				prefix,
 				packageDir,
-				copies: cli.skill === void 0 ? [] : await homeCopiesOf(cli.name, ctx.env)
-			};
-		},
-		apply: async (plan, ctx) => {
-			const { from, latest, prefix, packageDir } = plan;
-			const installs = needsInstall(plan);
-			const skill = await ctx.runToEnd(`installing ${plan.package}@${latest}`, async () => {
-				if (installs) {
-					ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
-					await installGlobally(latest, npmOfSetup(cli, install, ctx, node));
-				}
-				return syncHome(cli, packageDir, ctx);
-			}).catch((error) => {
-				throw withSetupLine(error, install);
-			});
-			const setup = {
-				version: installs || from === null ? latest : from,
-				prefix,
-				installed: installs,
-				skill,
-				upgrades: installs && from !== null ? await upgradesOf(packageDir, from, latest) : [],
-				docs: cli.docs === void 0 ? null : join(packageDir, cli.docs)
-			};
-			ctx.deliver(setup);
-			if (ctx.signal.aborted) throw new CliError({
-				code: INTERRUPTED,
-				message: `interrupted, but ${plan.package}@${setup.version} and its skill are already in place`,
-				hint: "nothing to run again"
-			});
-			await assertOnPath(cli, prefix, node, ctx);
-			return setup;
-		},
-		render: (setup) => renderSetup(cli, install, setup),
-		renderPlan: (plan) => [needsInstall(plan) ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}` : `${plan.package}@${plan.from} is already installed under ${plan.prefix}`, ...renderPlannedSync(cli.name, plan.copies)].join("\n")
-	});
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/update.js
-const updateSchema = object({
-	from: string(),
-	latest: string(),
-	installed: object({
-		version: string(),
-		prefix: string()
-	}).nullable(),
-	skill: homeSyncSchema.nullable(),
-	upgrades: array(upgradeSchema)
-});
-function nothingToInstall({ from, latest }) {
-	return standingOf$1(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 skill = renderHomeSync(cli.name, update.skill);
-	return installed === null ? [nothingToInstall(update), ...skill].join("\n") : [
-		`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`,
-		...skill,
-		...update.upgrades.map(renderUpgrade)
-	].join("\n");
-}
-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"
-	});
-}
-/** The built-in `update`, for a CLI installed globally with npm. */
-function updateCommand(cli, install, { bin, node }) {
-	return defineCommand$1({
-		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 = globalNpm(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,
-				copies: cli.skill === void 0 ? [] : await homeCopiesOf(cli.name, ctx.env)
+				copies: cli.skill === void 0 ? [] : await homeCopiesOf(ctx.files, cli.name, ctx.env)
 			};
 		},
 		apply: async (plan, ctx) => {
-			const { from, latest, prefix } = plan;
-			if (standingOf$1(from, latest) !== "behind") return {
-				from,
-				latest,
-				installed: null,
-				skill: await syncHome(cli, plan.packageDir, ctx),
-				upgrades: []
-			};
-			ctx.signal.throwIfAborted();
-			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
-			const skill = await ctx.runToEnd(`installing ${plan.package}@${latest}`, async () => {
-				await installGlobally(latest, globalNpm(cli, install, ctx, node));
-				return syncHome(cli, plan.packageDir, ctx);
-			});
-			const update = {
-				from,
-				latest,
-				installed: {
-					version: latest,
-					prefix
-				},
-				skill,
-				upgrades: await upgradesOf(plan.packageDir, from, latest)
-			};
-			if (ctx.signal.aborted) {
-				ctx.deliver(update);
-				throw interruptedAfterInstall(plan);
-			}
-			return update;
-		},
-		render: (update) => renderUpdate(cli, install, update),
-		renderPlan: (plan) => [standingOf$1(plan.from, plan.latest) === "behind" ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}, replacing ${plan.from}` : nothingToInstall(plan), ...renderPlannedSync(cli.name, plan.copies)].join("\n")
-	});
-}
-//#endregion
-//#region ../agent-cli/dist/context/files.js
-const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
-/** Where the Runtime writes `path` before moving it into place; a dead writer's is swept. */
-function tempPathOf(path) {
-	return join(dirname(path), `.${basename(path)}.agent-cli-${process.pid}.tmp`);
-}
-function isAlive(pid) {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return errnoOf(error) === "EPERM";
-	}
-}
-async function sweep(folder) {
-	const dead = (await readdir(folder)).filter((name) => {
-		const pid = TEMP_FILE.exec(name)?.[1];
-		return pid !== void 0 && !isAlive(Number(pid));
-	});
-	await Promise.all(dead.map((name) => rm(join(folder, name), { force: true })));
-}
-/** The file a symlink at `path` points to, so a replacing write keeps the link. */
-async function targetOf$1(path) {
-	try {
-		return await realpath(path);
-	} catch (error) {
-		if (isMissingFile(error)) return path;
-		throw error;
-	}
-}
-async function writeWithMode(path, data, mode) {
-	if (mode === void 0) {
-		await writeFile(path, data);
-		return;
-	}
-	await writeFile(path, data, { mode });
-	await chmod(path, mode);
-}
-/** What `link` answers on a file system without hard links, such as exFAT. */
-const NO_HARD_LINKS = /* @__PURE__ */ new Set([
-	"EPERM",
-	"ENOTSUP",
-	"EXDEV"
-]);
-/** A link fails atomically when `path` is taken, so no reader ever sees half a file there. */
-async function linkNew(temp, path, data, mode) {
-	try {
-		await link(temp, path);
-	} catch (error) {
-		if (!NO_HARD_LINKS.has(errnoOf(error))) throw error;
-		await createNew(path, data, mode);
-	}
-}
-/** A file this call created and could not finish is removed, so a rerun does not find half of it. */
-async function createNew(path, data, mode) {
-	const handle = await open(path, "wx", mode);
-	try {
-		await handle.writeFile(data);
-		if (mode !== void 0) await handle.chmod(mode);
-	} catch (error) {
-		await handle.close();
-		await rm(path, { force: true });
-		throw error;
-	}
-	await handle.close();
-}
-const RENAME_ATTEMPTS = 10;
-const RENAME_BACKOFF_MS = 10;
-const HELD_BY_ANOTHER_PROGRAM = /* @__PURE__ */ new Set(["EPERM", "EBUSY"]);
-async function renameRetrying(from, to) {
-	for (let attempt = 1;; attempt++) try {
-		await rename(from, to);
-		return;
-	} catch (error) {
-		if (!(process.platform === "win32" && HELD_BY_ANOTHER_PROGRAM.has(errnoOf(error))) || attempt === RENAME_ATTEMPTS) throw error;
-		await setTimeout$1(attempt * RENAME_BACKOFF_MS);
-	}
-}
-/** Real files for one run: the first write to each folder sweeps the temp files of dead writers. */
-function realFiles() {
-	const swept = /* @__PURE__ */ new Set();
-	return {
-		exists: async (path) => {
-			try {
-				await access(path);
-				return true;
-			} catch (error) {
-				if (isNothingThere(error)) return false;
-				throw error;
-			}
-		},
-		write: async (path, data, options = {}) => {
-			await mkdir(dirname(path), { recursive: true });
-			const target = options.exclusive === true ? path : await targetOf$1(path);
-			const folder = dirname(target);
-			if (!swept.has(folder)) {
-				await sweep(folder);
-				swept.add(folder);
-			}
-			const temp = tempPathOf(target);
-			try {
-				await writeWithMode(temp, data, options.mode);
-				if (options.exclusive === true) {
-					await linkNew(temp, target, data, options.mode);
-					await rm(temp);
-				} else await renameRetrying(temp, target);
-			} catch (error) {
-				await rm(temp, { force: true });
-				throw error;
-			}
-		},
-		read: (path) => readFile(path),
-		list: (folder) => readdir(folder),
-		remove: (path) => rm(path, {
-			recursive: true,
-			force: true
-		}),
-		mkdir: async (path, options) => {
-			const mode = options?.mode;
-			if (options?.exclusive !== true) {
-				await mkdir(path, {
-					recursive: true,
-					mode
-				});
-				return;
-			}
-			await mkdir(dirname(path), {
-				recursive: true,
-				mode
+			const { from, latest, prefix, packageDir } = plan;
+			const installs = needsInstall(plan);
+			const skill = await ctx.runToEnd(`installing ${plan.package}@${latest}`, async () => {
+				if (installs) {
+					ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
+					await installGlobally(latest, npmOfSetup(cli, install, ctx, launch));
+				}
+				return syncHome(cli, packageDir, ctx);
+			}).catch((error) => {
+				throw withSetupLine(error, install);
 			});
-			await mkdir(path, { mode });
+			const setup = {
+				version: installs || from === null ? latest : from,
+				prefix,
+				installed: installs,
+				skill,
+				upgrades: installs && from !== null ? await upgradesOf(ctx.files, packageDir, from, latest) : [],
+				docs: cli.docs === void 0 ? null : join(packageDir, cli.docs)
+			};
+			ctx.deliver(setup);
+			if (ctx.signal.aborted) throw new CliError({
+				code: INTERRUPTED,
+				message: `interrupted, but ${plan.package}@${setup.version} and its skill are already in place`,
+				hint: "nothing to run again"
+			});
+			await assertOnPath(cli, prefix, launch, ctx);
+			return setup;
 		},
-		stat: async (path) => {
-			try {
-				const { size, dev, ino } = await stat(path, { bigint: true });
-				return {
-					size: Number(size),
-					id: `${dev}:${ino}`
-				};
-			} catch (error) {
-				if (isNothingThere(error)) return void 0;
-				throw error;
-			}
-		}
-	};
+		render: (setup) => renderSetup(cli, install, setup),
+		renderPlan: (plan) => [needsInstall(plan) ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}` : `${plan.package}@${plan.from} is already installed under ${plan.prefix}`, ...renderPlannedSync(cli.name, plan.copies)].join("\n")
+	});
 }
-/**
-* `files` resolving paths against `cwd`, its failures classified by errno; `list` drops the
-* Runtime's temp files and sorts.
-*/
-function classifiedFiles(files, { cwd, fileError }) {
-	async function at(access, path, work) {
-		const target = resolve(cwd, path);
-		try {
-			return await work(target);
-		} catch (error) {
-			throw fileError(error, {
-				path: target,
-				access
+//#endregion
+//#region ../agent-cli/dist/built-ins/update.js
+const updateSchema = object({
+	from: string(),
+	latest: string(),
+	installed: object({
+		version: string(),
+		prefix: string()
+	}).nullable(),
+	skill: homeSyncSchema.nullable(),
+	upgrades: array(upgradeSchema)
+});
+function nothingToInstall({ from, latest }) {
+	return standingOf$1(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 skill = renderHomeSync(cli.name, update.skill);
+	return installed === null ? [nothingToInstall(update), ...skill].join("\n") : [
+		`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`,
+		...skill,
+		...update.upgrades.map(renderUpgrade)
+	].join("\n");
+}
+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"
+	});
+}
+/** The built-in `update`, for a CLI installed globally with npm. */
+function updateCommand(cli, install, launch) {
+	return defineCommand$1.write({
+		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"
+		}],
+		errors: [NOT_GLOBAL_INSTALL, ...NPM_ERRORS],
+		output: updateSchema,
+		plan: async (_input, ctx) => {
+			const npm = globalNpm(cli, install, ctx, launch);
+			const copy = await globalInstallOf(launch.bin, npm);
+			return {
+				package: install.package,
+				from: cli.version,
+				latest: await latestVersion(npm),
+				prefix: copy.prefix,
+				packageDir: copy.packageDir,
+				copies: cli.skill === void 0 ? [] : await homeCopiesOf(ctx.files, cli.name, ctx.env)
+			};
+		},
+		apply: async (plan, ctx) => {
+			const { from, latest, prefix } = plan;
+			if (standingOf$1(from, latest) !== "behind") return {
+				from,
+				latest,
+				installed: null,
+				skill: await syncHome(cli, plan.packageDir, ctx),
+				upgrades: []
+			};
+			ctx.signal.throwIfAborted();
+			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
+			const skill = await ctx.runToEnd(`installing ${plan.package}@${latest}`, async () => {
+				await installGlobally(latest, globalNpm(cli, install, ctx, launch));
+				return syncHome(cli, plan.packageDir, ctx);
 			});
-		}
-	}
-	return {
-		exists: (path) => at("read", path, (target) => files.exists(target)),
-		write: (path, data, options) => at("write", path, (target) => files.write(target, data, options)),
-		read: (path) => at("read", path, (target) => files.read(target)),
-		list: (folder) => at("read", folder, async (target) => (await files.list(target)).filter((name) => !TEMP_FILE.test(name)).sort()),
-		remove: (path) => at("write", path, (target) => files.remove(target)),
-		mkdir: (path, options) => at("write", path, (target) => files.mkdir(target, options)),
-		stat: (path) => at("read", path, (target) => files.stat(target))
-	};
+			const update = {
+				from,
+				latest,
+				installed: {
+					version: latest,
+					prefix
+				},
+				skill,
+				upgrades: await upgradesOf(ctx.files, plan.packageDir, from, latest)
+			};
+			if (ctx.signal.aborted) {
+				ctx.deliver(update);
+				throw interruptedAfterInstall(plan);
+			}
+			return update;
+		},
+		render: (update) => renderUpdate(cli, install, update),
+		renderPlan: (plan) => [standingOf$1(plan.from, plan.latest) === "behind" ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}, replacing ${plan.from}` : nothingToInstall(plan), ...renderPlannedSync(cli.name, plan.copies)].join("\n")
+	});
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/install/release-check.js
@@ -8572,25 +8835,19 @@ function parsedCheck(text) {
 		return;
 	}
 }
-async function lastCheck(file) {
-	const text = await orMissing(readFile(file, "utf8"));
+async function lastCheck(files, file) {
+	const text = await readIfAny(files, file);
 	return text === void 0 ? void 0 : parsedCheck(text);
 }
-async function writeCheck(file, check) {
-	await mkdir(dirname(file), { recursive: true });
-	const temp = tempPathOf(file);
-	await writeFile(temp, JSON.stringify(check));
-	await rename(temp, file);
-}
-async function startCheck(cli, install, file, last, { node }, ctx) {
+async function startCheck(cli, install, file, last, launch, ctx) {
 	const checkedAt = ctx.clock.now();
 	const previous = last?.latest ?? "";
-	await writeCheck(file, {
+	await ctx.files.write(file, JSON.stringify({
 		checkedAt,
 		latest: last?.latest
-	});
-	const npm = globalNpm(cli, install, ctx, node);
-	const { path, env } = npmOf(npm, process.platform === "win32");
+	}));
+	const npm = globalNpm(cli, install, ctx, launch);
+	const { path, env } = await npmOf(npm);
 	await ctx.spawnDetached(process.execPath, [
 		"-e",
 		CHECK_SCRIPT,
@@ -8623,7 +8880,7 @@ async function releaseCheck(cli, install, runAs, launch, ctx) {
 }
 async function checkAndTell(cli, install, runAs, launch, ctx) {
 	const file = cacheFileOf(cli.name, ctx.env);
-	const last = await lastCheck(file);
+	const last = await lastCheck(ctx.files, file);
 	if (last?.error !== void 0) debugLine(cli, ctx, last.error);
 	if (last === void 0 || ctx.clock.now() - last.checkedAt >= CHECK_INTERVAL_MS) await startCheck(cli, install, file, last, launch, ctx);
 	const latest = last?.latest;
@@ -8632,14 +8889,14 @@ async function checkAndTell(cli, install, runAs, launch, ctx) {
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/install/global.js
-function checkOf(cli, install, { bin, node }) {
+function checkOf(cli, install, launch) {
 	return {
 		install: async (ctx) => {
-			const npm = globalNpm(cli, install, ctx, node);
+			const npm = globalNpm(cli, install, ctx, launch);
 			try {
 				return {
 					state: "ok",
-					message: `a global npm install under ${(await globalInstallOf(bin, npm)).prefix}`
+					message: `a global npm install under ${(await globalInstallOf(launch.bin, npm)).prefix}`
 				};
 			} catch (error) {
 				if (error instanceof CliError && error.code === "NOT_GLOBAL_INSTALL") return {
@@ -8653,7 +8910,7 @@ function checkOf(cli, install, { bin, node }) {
 		release: async (ctx) => {
 			const fix = `${cli.name} update`;
 			return {
-				npm: globalNpm(cli, install, ctx, node),
+				npm: globalNpm(cli, install, ctx, launch),
 				advise: () => ({ fix })
 			};
 		}
@@ -8667,7 +8924,6 @@ function globalInstall(cli, install) {
 			setup: setupCommand(cli, install, launch),
 			update: updateCommand(cli, install, launch)
 		}),
-		exitClasses: ["source"],
 		check: (launch) => checkOf(cli, install, launch),
 		notice: (launch, ctx) => releaseCheck(cli, install, adapter.runAs, launch, ctx)
 	};
@@ -8684,7 +8940,6 @@ function noInstall(cli) {
 	return {
 		runAs: runAsOf(cli),
 		builtIns: () => ({}),
-		exitClasses: [],
 		check: () => ({
 			install: skipped,
 			release: async () => ({ skipped: await skipped() })
@@ -8715,9 +8970,9 @@ function withSection({ name, text: section }, text) {
 	if (text === "") return `${whole}\n`;
 	return `${text}${text.endsWith("\n") ? "" : "\n"}\n${whole}\n`;
 }
-async function agentsMdAt(agents, root) {
+async function agentsMdAt(files, agents, root) {
 	const path = join(root, "AGENTS.md");
-	const existing = await orMissing(readFile(path, "utf8"));
+	const existing = await readIfAny(files, path);
 	if (existing === void 0) return {
 		path,
 		agents,
@@ -8734,9 +8989,9 @@ async function agentsMdAt(agents, root) {
 		change: existing.includes(markersOf(agents.name).begin) ? "rewrite" : "add"
 	};
 }
-async function handEditsAt(root) {
+async function handEditsAt(files, root) {
 	const claudeMd = join(root, "CLAUDE.md");
-	const text = await orMissing(readFile(claudeMd, "utf8"));
+	const text = await readIfAny(files, claudeMd);
 	if (text === void 0 || text.split(/\r?\n/).some((line) => line.trim() === "@AGENTS.md")) return [];
 	return [`add a line \`@AGENTS.md\` to ${claudeMd}, so Claude Code reads AGENTS.md`];
 }
@@ -8746,8 +9001,8 @@ function agentsRow(agents, install) {
 		name: "agents",
 		advisory: true,
 		run: async (ctx) => {
-			const root = await projectRootOf(ctx.cwd);
-			const { path, change } = await agentsMdAt(agents, root);
+			const root = await projectRootOf(ctx.files, ctx.cwd);
+			const { path, change } = await agentsMdAt(ctx.files, agents, root);
 			const fix = `${install.runAs} skill install`;
 			if (change === "rewrite") return {
 				state: "problem",
@@ -8760,7 +9015,7 @@ function agentsRow(agents, install) {
 				fix
 			};
 			const holds = `${path} holds the ${name} Agents section`;
-			const [edit] = await handEditsAt(root);
+			const [edit] = await handEditsAt(ctx.files, root);
 			return edit === void 0 ? {
 				state: "ok",
 				message: holds
@@ -8774,8 +9029,8 @@ function agentsRow(agents, install) {
 //#endregion
 //#region ../agent-cli/dist/built-ins/skill/install-command.js
 /** The project root and the Skill copy under it, as `skill install` writes it. */
-async function skillCopyOf(cli, cwd) {
-	const root = await projectRootOf(cwd);
+async function skillCopyOf(files, cli, cwd) {
+	const root = await projectRootOf(files, cwd);
 	return {
 		root,
 		copy: join(root, ".claude", "skills", cli.name)
@@ -8791,12 +9046,14 @@ const installSchema = object({
 	}).nullable(),
 	handEdits: array(string())
 });
-async function planOf(cli, folder, agents, cwd, packageRoot) {
-	const { root, copy } = await skillCopyOf(cli, cwd);
+async function planOf(cli, folder, agents, { files, cwd, packageRoot }) {
+	const source = join(packageRoot, folder);
+	await readRequired(files, join(source, "SKILL.md"));
+	const { root, copy } = await skillCopyOf(files, cli, cwd);
 	return {
-		...await syncOf(join(packageRoot, folder), copy),
-		agentsMd: agents === void 0 ? null : await agentsMdAt(agents, root),
-		handEdits: agents === void 0 ? [] : await handEditsAt(root)
+		...await syncOf(files, source, copy),
+		agentsMd: agents === void 0 ? null : await agentsMdAt(files, agents, root),
+		handEdits: agents === void 0 ? [] : await handEditsAt(files, root)
 	};
 }
 const SECTION_VERBS = {
@@ -8828,7 +9085,7 @@ function renderInstalled(cli, data) {
 }
 /** The built-in `skill install`, for a CLI whose skill ships in its package. */
 function skillInstallCommand(cli, folder, agents) {
-	return defineCommand$1({
+	return defineCommand$1.write({
 		description: agents === void 0 ? "copy this CLI's skill into the project" : "copy this CLI's skill into the project and write its Agents section",
 		examples: [{
 			command: `${cli.name} skill install`,
@@ -8837,14 +9094,13 @@ function skillInstallCommand(cli, folder, agents) {
 			command: `${cli.name} skill install --dry-run`,
 			note: "show what it would change"
 		}],
-		effect: "write",
 		output: installSchema,
-		plan: (_input, ctx) => planOf(cli, folder, agents, ctx.cwd, ctx.packageRoot),
+		plan: (_input, ctx) => planOf(cli, folder, agents, ctx),
 		apply: async (plan, ctx) => {
 			await applySync(plan, ctx);
 			const { agentsMd } = plan;
 			if (agentsMd !== null && agentsMd.change !== null) {
-				const existing = await orMissing(readFile(agentsMd.path, "utf8")) ?? "";
+				const existing = await readIfAny(ctx.files, agentsMd.path) ?? "";
 				await ctx.files.write(agentsMd.path, withSection(agentsMd.agents, existing));
 			}
 			return {
@@ -8866,13 +9122,13 @@ function skillInstallCommand(cli, folder, agents) {
 //#region ../agent-cli/dist/built-ins/skill/project.js
 async function personalCopyOf(name, copy, ctx) {
 	const home = join(homeOf(ctx.env), ".claude", "skills", name);
-	const real = await orMissing(realpath(home));
-	return real === void 0 || real === await orMissing(realpath(copy)) ? void 0 : home;
+	const real = await ctx.files.realPath(home);
+	return real === void 0 || real === await ctx.files.realPath(copy) ? void 0 : home;
 }
 /** The project root's copy against the package's, and any under home. */
 async function findingOf(cli, folder, install, ctx) {
-	const { copy } = await skillCopyOf(cli, ctx.cwd);
-	const [installed, shipped] = await Promise.all([orMissing(readFile(join(copy, "SKILL.md"), "utf8")), readFile(join(ctx.packageRoot, folder, "SKILL.md"), "utf8")]);
+	const { copy } = await skillCopyOf(ctx.files, cli, ctx.cwd);
+	const [installed, shipped] = await Promise.all([readIfAny(ctx.files, join(copy, "SKILL.md")), readRequired(ctx.files, join(ctx.packageRoot, folder, "SKILL.md"))]);
 	const stated = installed === void 0 ? void 0 : skillVersionIn(installed);
 	const left = stated !== void 0 && skillVersionIn(shipped) === void 0;
 	const found = left ? `${copy} (${statedVersionNote(stated)})` : copy;
@@ -9050,7 +9306,7 @@ function registryRow(cli, check) {
 function doctorChecks(cli, launch, scope) {
 	const install = installOf(cli);
 	const check = install.check(launch);
-	const tools = toolRows(cli.tools ?? [], cli.commands);
+	const tools = toolRows(cli.tools ?? [], cli.commands, launch.platform);
 	return {
 		checks: [
 			buildRow(cli),
@@ -9066,6 +9322,8 @@ function doctorChecks(cli, launch, scope) {
 		tools: new Set(tools.map(({ name }) => name))
 	};
 }
+//#endregion
+//#region ../agent-cli/dist/built-ins/doctor.js
 const DEFAULT_DEADLINE_MS = 1e4;
 const MS_PER_SECOND = 1e3;
 const MIN_LABEL_WIDTH = 8;
@@ -9136,12 +9394,12 @@ async function rowOf(check, ctx, { read, runAs, tools }) {
 			check: check.name,
 			...finding
 		},
-		advisory: check.advisory === true
+		check
 	};
 }
 function nextOf(checked, doctorLine) {
 	const fixes = checked.flatMap(({ row }) => row.fix === void 0 ? [] : [row.fix]);
-	const unfixed = checked.some(({ row, advisory }) => advisory && row.state === "problem" && row.fix === void 0);
+	const unfixed = checked.some(({ row, check }) => check.advisory === true && row.state === "problem" && row.fix === void 0);
 	return [...new Set(unfixed ? [...fixes, doctorLine] : fixes)];
 }
 function render({ rows, next }, style) {
@@ -9170,9 +9428,14 @@ function failure(cliName, rerun, problems) {
 	});
 	return new AggregateError(errors);
 }
+function checkedRows(error, problems, table) {
+	const undeclared = problems.flatMap(({ row, check }) => row.code !== void 0 && mustDeclare(row.code, table) && !check.errors?.includes(row.code) ? [`the ${check.name} row failed with ${row.code}`] : []);
+	if (undeclared.length === 0) return error;
+	return new Error(`doctor: ${undeclared.join("; ")}, which its errors do not declare`, { cause: error });
+}
 /** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
 function doctorCommand(cli, launch) {
-	return defineCommand$1({
+	const doctor = defineCommand$1.read({
 		description: "check the setup and say what fixes each problem",
 		examples: [{
 			command: `${cli.name} doctor`,
@@ -9181,7 +9444,6 @@ function doctorCommand(cli, launch) {
 			command: `${cli.name} doctor --json`,
 			note: "get the rows and fixes as data"
 		}],
-		effect: "read",
 		output: reportSchema,
 		run: async (_input, ctx) => {
 			const rowsScope = {
@@ -9201,15 +9463,20 @@ function doctorCommand(cli, launch) {
 				ctx.deliver(report);
 				ctx.signal.throwIfAborted();
 			}
-			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
+			const problems = checked.filter(({ row, check }) => row.state === "problem" && check.advisory !== true);
 			if (problems.length > 0) {
 				ctx.deliver(report);
-				throw failure(cli.name, ctx.rerun(), problems);
+				throw checkedRows(failure(cli.name, ctx.rerun(), problems.map(({ row }) => row)), problems, errorTableOf(cli));
 			}
 			return report;
 		},
 		render
 	});
+	const rowCodes = (cli.doctor ?? []).flatMap((row) => row.advisory === true ? [] : row.errors ?? []);
+	return {
+		...doctor,
+		errors: [.../* @__PURE__ */ new Set([DOCTOR_PROBLEMS, ...rowCodes])]
+	};
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/commands.js
@@ -9309,19 +9576,6 @@ function specOf(commandLine, node, place) {
 	return isCommand(node) ? commandSpec(commandLine, node, place) : group(commandLine, specsOf(commandLine, node, place));
 }
 //#endregion
-//#region ../agent-cli/dist/error-table.js
-/** The Error table a CLI declares, empty when it declares none. */
-function errorTableOf({ errors }) {
-	return errors ?? {};
-}
-/** The `CliError` for a code of `Table`, as `cliError` and `ctx.fail` build it. */
-function cliErrorOf(code, init, options) {
-	return new CliError({
-		...init,
-		code
-	}, options);
-}
-//#endregion
 //#region ../agent-cli/dist/exit-classes.js
 const SIGNAL_EXIT_CODES = {
 	SIGINT: 130,
@@ -9334,95 +9588,38 @@ const EXIT_CODES = {
 	wait: 75,
 	bug: 70
 };
-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: "bug",
-	PERMISSION_DENIED: "operator",
-	DISK_FULL: "operator",
-	NOT_FOUND: "caller",
-	ALREADY_EXISTS: "caller",
-	NOT_A_FILE: "caller",
-	TOOL_FAILED: "operator",
-	TOOL_MISSING: "operator",
-	SECRET_MISSING: "operator",
-	PROJECT_INVALID: "operator",
-	DOCTOR_PROBLEMS: "operator",
-	NOT_GLOBAL_INSTALL: "operator",
-	NOT_ON_PATH: "operator",
-	REGISTRY_UNREACHABLE: "operator",
-	REGISTRY_AUTH: "operator",
-	INSTALL_FAILED: "operator",
-	NPM_FAILED: "operator",
-	NO_LATEST: "source"
-};
-function isRuntimeCode(code) {
-	return Object.hasOwn(RUNTIME_EXIT_CLASSES, code);
-}
 /** The codes of `errors` that the Runtime already declares, which a CLI cannot redeclare. */
 function runtimeCodesIn(errors) {
 	return Object.keys(errors).filter(isRuntimeCode);
 }
-function exitClassOfOne(error, errors) {
-	if (!(error instanceof CliError)) return "bug";
-	if (error instanceof UsageError) return "caller";
-	if (isRuntimeCode(error.code)) return RUNTIME_EXIT_CLASSES[error.code];
-	return errors[error.code]?.class ?? "bug";
-}
-function isBug(error, errors) {
-	return exitClassOfOne(error, errors) === "bug";
+/** The class of `code` in the Runtime's Error table or else in the CLI's `errors`. */
+function classOfCode(code, errors) {
+	return isRuntimeCode(code) ? runtimeErrors[code].class : errors[code]?.class;
 }
-function isWait(error, errors) {
-	return exitClassOfOne(error, errors) === "wait";
+function declaredCodesOf(node) {
+	return node.kind === "command" ? node.command.errors ?? [] : Object.values(node.commands).flatMap(declaredCodesOf);
 }
-const ACT_FIRST = [
-	"caller",
-	"operator",
-	"source",
-	"wait",
-	"interrupted"
-];
-function exitClassOf(error, errors) {
-	const classes = errorsOf(error).map((each) => exitClassOfOne(each, errors));
-	if (classes.includes("bug")) return "bug";
-	return ACT_FIRST.find((exitClass) => classes.includes(exitClass)) ?? "bug";
+function isDeclarable(exitClass) {
+	return exitClass !== void 0 && exitClass !== "bug" && exitClass !== "interrupted";
 }
 /**
-* The classes other than bug and interrupt that a run of `cli` can end in: those of the Runtime's
-* codes it can reach, and those of its own table.
+* The classes other than bug and interrupt that a run of `cli` can end in: those of the Runtime
+* codes any Command can meet, those of the codes its Commands under `root` declare, Built-ins
+* included, and those of its own table.
 */
-function reachableExitClasses(cli) {
-	const runtime = [
-		"caller",
-		"operator",
-		"wait",
-		...cli.commands === void 0 ? [] : installOf(cli).exitClasses
+function reachableExitClasses(cli, root) {
+	const table = errorTableOf(cli);
+	const classes = [
+		...anyCommandClasses,
+		...declaredCodesOf(root).map((code) => classOfCode(code, table)),
+		...Object.values(table).map((declaration) => declaration.class)
 	];
-	const own = Object.values(errorTableOf(cli)).map((declaration) => declaration.class);
-	return /* @__PURE__ */ new Set([...runtime, ...own]);
+	return new Set(classes.filter(isDeclarable));
 }
 /** The signal named by an interrupt's abort reason; any other reason counts as Ctrl-C. */
 function stopSignalOf(reason) {
 	return reason === "SIGTERM" ? "SIGTERM" : "SIGINT";
 }
-/**
-* The exit code of a run that failed with `error`, given the CLI's error table; `stop` is the
-* signal that interrupted it, if any.
-*/
-function exitCodeOf(error, errors, stop) {
-	const exitClass = exitClassOf(error, errors);
-	return exitClass === "interrupted" ? SIGNAL_EXIT_CODES[stopSignalOf(stop?.reason)] : EXIT_CODES[exitClass];
-}
 //#endregion
 //#region ../agent-cli/dist/agent-cli.js
 function checkOwnCodes(errors) {
@@ -9443,7 +9640,7 @@ function checkDocs({ name, docs }) {
 	if (docs === void 0) return;
 	if (!(docs !== "" && !isAbsolute(docs) && !normalize(docs).startsWith(".."))) throw new Error(`${name} declares docs ${JSON.stringify(docs)}: name a folder inside its package, relative to the package root`);
 }
-function checkCli(cli) {
+function checkDeclared(cli) {
 	const table = errorTableOf(cli);
 	checkDocs(cli);
 	if (cli.commands === void 0) {
@@ -9454,9 +9651,11 @@ function checkCli(cli) {
 	checkSkill(cli);
 	const { commands } = cli;
 	checkTree(commands, [], table);
+	for (const row of cli.doctor ?? []) checkErrors(row.errors ?? [], `the ${row.name} row of doctor`, table);
 	const taken = Object.keys(builtInCommands(cli, {
 		bin: void 0,
-		node: void 0
+		node: void 0,
+		platform: process.platform
 	})).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;
@@ -9514,16 +9713,17 @@ function resolved(cli) {
 }
 /**
 * Takes the CLI's ports factory, Project file and Error table once; the `defineCommand`,
-* `defineCli` and `cliError` it returns are typed by them.
+* `defineDoctorCheck`, `defineCli` and `cliError` it returns are typed by them.
 */
 function agentCli(values = {}) {
 	checkOwnCodes(errorTableOf(values));
 	return {
 		defineCommand: defineCommandFor(),
-		defineCli: (cli) => checkCli({
+		defineCli: (cli) => checkDeclared({
 			...resolved(cli),
 			...values
 		}),
+		defineDoctorCheck: (row) => row,
 		cliError: cliErrorOf
 	};
 }
@@ -9844,37 +10044,6 @@ function route(root, invocation) {
 	return walk(root, argv.filter((word, index) => !(index < options.length && word === JSON_FLAG.flag)), json, invocation);
 }
 //#endregion
-//#region ../agent-cli/dist/command-line/route-line.js
-/** Routes `argv`, the line's words after the Run-as, to a Command of `root`. */
-function routeLine(root, runAs, argv) {
-	if (!argv.ok) return {
-		ok: false,
-		reason: `it does not tokenize: ${argv.reason}`
-	};
-	const invocation = {
-		runAs,
-		argv: argv.words,
-		flags: []
-	};
-	const routed = route(root, invocation);
-	switch (routed.kind) {
-		case "usage error": return {
-			ok: false,
-			reason: routed.error.message
-		};
-		case "help":
-		case "version": return {
-			ok: false,
-			reason: "it names no Command"
-		};
-		case "command": return {
-			ok: true,
-			routed,
-			invocation
-		};
-	}
-}
-//#endregion
 //#region ../agent-cli/dist/command-line/shell-words.js
 const BLANK = /\s/;
 const SHELL_SYNTAX = /* @__PURE__ */ new Set([
@@ -9973,39 +10142,126 @@ function shellWords(line) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/check-next-steps.js
-function argvOf(words, runAs) {
-	const line = shellWords(lineOf(words, runAs));
-	const lead = shellWords(runAs);
-	if (!lead.ok) return lead;
-	if (!line.ok) return line;
-	return {
-		ok: true,
-		words: line.words.slice(lead.words.length)
+//#region ../agent-cli/dist/command-line/line-problem.js
+const STDIN_TEXT = "text from stdin";
+/**
+* Why `line` would not run a Command of `root`: it does not tokenize, start with its lead, route to
+* a Command or pass its schemas; `undefined` when it would.
+*/
+async function lineProblem(root, { text, lead, runAs }) {
+	const words = shellWords(text);
+	if (!words.ok) return `it does not tokenize: ${words.reason}`;
+	const leadWords = shellWords(lead);
+	if (!leadWords.ok) return `its lead does not tokenize: ${leadWords.reason}`;
+	if (leadWords.words.some((word, index) => words.words[index] !== word)) return `it does not start with \`${lead}\``;
+	const invocation = {
+		runAs,
+		argv: words.words.slice(leadWords.words.length),
+		flags: []
 	};
+	const routed = route(root, invocation);
+	switch (routed.kind) {
+		case "usage error": return routed.error.message;
+		case "help":
+		case "version": return "it names no Command";
+		case "command": try {
+			await parseCommand(routed, invocation, async () => STDIN_TEXT);
+			return;
+		} catch (error) {
+			if (error instanceof UsageError) return error.message;
+			throw error;
+		}
+	}
 }
+//#endregion
+//#region ../agent-cli/dist/check-next-steps.js
 /**
 * Why `step` would not run a Command of `root`, or `undefined` when it would. A line given whole is
 * not checked, since it may run another program.
 */
-function nextStepProblem(root, runAs, step) {
+async function nextStepProblem(root, runAs, step) {
 	const words = wordsOf(step);
 	if (words === void 0) return void 0;
-	const line = routeLine(root, runAs, argvOf(words, runAs));
-	if (!line.ok) return line.reason;
-	const { routed } = line;
-	const { unknownOptions } = tokenize(routed.words, knownFlags(routed.spec));
-	return unknownOptions.length === 0 ? void 0 : `unknown option ${unknownOptions.join(", ")}`;
-}
-/** `error`, or a bug naming each of its Next steps that would not run. */
-function checkedNextSteps(error, check, runAs) {
-	const problems = errorsOf(error).flatMap((leaf) => leaf instanceof CliError ? leaf.next.flatMap((step) => {
-		const problem = check(step);
-		return problem === void 0 ? [] : [`\`${lineOf(step, runAs)}\`, a Next step of ${leaf.code}: ${problem}`];
-	}) : []);
+	return lineProblem(root, {
+		text: lineOf(words, runAs),
+		lead: runAs,
+		runAs
+	});
+}
+/** The check that a failure's Next steps run Commands of `root`: a bug names each that would not. */
+function nextStepCheck(root, runAs) {
+	return (error) => checkedNextSteps(error, root, runAs);
+}
+async function checkedNextSteps(error, root, runAs) {
+	const problems = [];
+	for (const leaf of errorsOf(error)) {
+		if (!(leaf instanceof CliError)) continue;
+		for (const step of leaf.next) {
+			const problem = await nextStepProblem(root, runAs, step);
+			if (problem !== void 0) problems.push(`\`${lineOf(step, runAs)}\`, a Next step of ${leaf.code}: ${problem}`);
+		}
+	}
 	return problems.length === 0 ? error : new Error(`a Next step would not run: ${problems.join("; ")}`, { cause: error });
 }
 //#endregion
+//#region ../agent-cli/dist/failure.js
+/**
+* What a run that threw `error` reports: the interrupt and deadline rewrite, then the undeclared
+* code check, then the Next step check, each leaf classified, and the exit code they give.
+*/
+async function failureOf(error, sources) {
+	const { command, control, nextStepCheck } = sources;
+	const rewritten = control === void 0 ? error : control.errorAfter(error);
+	const declared = command === void 0 ? rewritten : checkedCodes(rewritten, command, sources);
+	return failureFrom(classified(nextStepCheck === void 0 ? declared : await nextStepCheck(declared), sources.errors), sources.stop);
+}
+/** `failure` with `error`'s leaves after its own, which may change its exit code. */
+function withLeaves(failure, error, sources) {
+	return failureFrom([...failure.leaves, ...classified(error, sources.errors)], sources.stop);
+}
+function classified(error, errors) {
+	return errorsOf(error).map((leaf) => ({
+		error: leaf,
+		exitClass: exitClassOfOne(leaf, errors)
+	}));
+}
+function failureFrom(leaves, stop) {
+	const exitClass = exitClassOf(leaves);
+	return {
+		leaves,
+		exitCode: exitClass === "interrupted" ? SIGNAL_EXIT_CODES[stopSignalOf(stop?.reason)] : EXIT_CODES[exitClass]
+	};
+}
+function exitClassOfOne(error, errors) {
+	if (!(error instanceof CliError)) return "bug";
+	if (error instanceof UsageError) return "caller";
+	return classOfCode(error.code, errors) ?? "bug";
+}
+const ACT_FIRST = [
+	"caller",
+	"operator",
+	"source",
+	"wait",
+	"interrupted"
+];
+function exitClassOf(leaves) {
+	const classes = leaves.map((leaf) => leaf.exitClass);
+	if (classes.includes("bug")) return "bug";
+	return ACT_FIRST.find((exitClass) => classes.includes(exitClass)) ?? "bug";
+}
+/**
+* `error`, or a bug naming each code in it that the Command must declare in its `errors` and does
+* not: one of the Error table, or a Runtime code only some Commands reach.
+*/
+function checkedCodes(error, { command, path }, { cliName, errors }) {
+	const declared = new Set(command.errors ?? []);
+	const undeclared = errorsOf(error).flatMap((leaf) => leaf instanceof CliError && mustDeclare(leaf.code, errors) && !declared.has(leaf.code) ? [leaf.code] : []);
+	if (undeclared.length === 0) return error;
+	const label = commandLabel(path, cliName).join(" ");
+	const codes = [...new Set(undeclared)].join(", ");
+	return new Error(`\`${label}\` threw ${codes}, which its errors do not declare`, { cause: error });
+}
+//#endregion
 //#region ../agent-cli/dist/help.js
 function table(rows) {
 	const width = Math.max(...rows.map(([left]) => left.length));
@@ -10043,10 +10299,10 @@ const EXIT_MEANINGS = {
 	source: "someone at the source acts",
 	wait: "not done yet: do what the hint says, then run it again"
 };
-function exitCodeRows(cli) {
+function exitCodeRows(cli, root) {
 	return [
 		["0", "done"],
-		...[...[...reachableExitClasses(cli)].map((exitClass) => [EXIT_CODES[exitClass], EXIT_MEANINGS[exitClass]]), [EXIT_CODES.bug, `a bug in ${cli.name}`]].sort(([a], [b]) => a - b).map(([code, meaning]) => [String(code), meaning]),
+		...[...[...reachableExitClasses(cli, root)].map((exitClass) => [EXIT_CODES[exitClass], EXIT_MEANINGS[exitClass]]), [EXIT_CODES.bug, `a bug in ${cli.name}`]].sort(([a], [b]) => a - b).map(([code, meaning]) => [String(code), meaning]),
 		[Object.values(SIGNAL_EXIT_CODES).join(", "), "interrupted"]
 	];
 }
@@ -10064,7 +10320,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(`${cli.name} ${cli.version}`, root, style, cli.description), ...section("Exit codes", exitCodeRows(cli), style), ...examplesSection(rootExamples(root), style));
+	return lines(...root.kind === "command" ? commandLines(root, style, { examples: false }) : listingLines(`${cli.name} ${cli.version}`, root, style, cli.description), ...section("Exit codes", exitCodeRows(cli, root), style), ...examplesSection(rootExamples(root), style));
 }
 function groupHelp(group, style) {
 	return lines(...listingLines(group.commandLine, group, style));
@@ -10142,7 +10398,7 @@ function commandData(spec, table) {
 		secrets: spec.command.secrets ?? [],
 		errors: (spec.command.errors ?? []).map((code) => ({
 			code,
-			class: table[code]?.class
+			class: classOfCode(code, table)
 		})),
 		args: inputSchema(spec.command.args ?? object({})),
 		options: optionsSchema(spec.options),
@@ -10175,7 +10431,10 @@ function errorsData(errors) {
 function publishedTable(table, root) {
 	if (root.kind !== "command") return table;
 	const declared = new Set(root.command.errors ?? []);
-	return Object.fromEntries(Object.entries(table).filter(([code]) => declared.has(code)));
+	return Object.fromEntries(Object.entries({
+		...table,
+		...declaredRuntimeErrors
+	}).filter(([code]) => declared.has(code)));
 }
 function cliHelpJson(cli, root) {
 	const { name, version, description } = cli;
@@ -10225,15 +10484,20 @@ function noticeLine(text, json) {
 function stderrLine(key, text, json) {
 	return json ? `${JSON.stringify({ [key]: text })}\n` : `${text}\n`;
 }
-function errorText(error, format) {
-	const text = formatRuntimeError(error, {
+function errorText({ leaves }, format) {
+	const text = formatRuntimeError(leaves, {
 		...format,
-		runAs: format.invocation.runAs,
-		isBug: (each) => isBug(each, format.errors),
-		isWait: (each) => isWait(each, format.errors)
+		runAs: format.invocation.runAs
 	});
 	const { usageHelp, json } = format;
-	return usageHelp !== void 0 && !json && error instanceof UsageError ? `${text}\n${usageHelp}` : text;
+	return usageHelp !== void 0 && !json && leaves.some((leaf) => leaf.error instanceof UsageError) ? `${text}\n${usageHelp}` : text;
+}
+function failedResult(failure, format) {
+	return {
+		stdout: "",
+		stderr: errorText(failure, format),
+		exitCode: failure.exitCode
+	};
 }
 function stdoutOf({ value, render }, format, spill) {
 	const text = printed(value, render, format);
@@ -10251,14 +10515,9 @@ const STOPPED_RESULT = {
 	stdout: "",
 	stderr: "",
 	exitCode: SUCCESS_EXIT_CODE
-};
-function errorResult(error, format) {
-	const checked = format.checkNextStep === void 0 ? error : checkedNextSteps(error, format.checkNextStep, format.invocation.runAs);
-	return {
-		stdout: "",
-		stderr: errorText(checked, format),
-		exitCode: exitCodeOf(checked, format.errors, format.stop)
-	};
+};
+async function errorResult(error, format) {
+	return failedResult(await failureOf(error, format), format);
 }
 async function commandResult(settled, format, spill) {
 	if (settled.ok) try {
@@ -10272,23 +10531,23 @@ async function commandResult(settled, format, spill) {
 	}
 	const { error, delivered } = settled;
 	if (delivered === void 0) return errorResult(error, format);
+	const failure = await failureOf(error, format);
 	let outcome;
 	try {
 		outcome = delivered();
 	} catch (rejected) {
-		return errorResult(new AggregateError([...errorsOf(error), rejected]), format);
+		return failedResult(withLeaves(failure, rejected, format), format);
 	}
-	const result = errorResult(error, format);
+	const result = failedResult(failure, format);
 	try {
 		return {
 			...result,
 			stdout: await stdoutOf(outcome, format, spill)
 		};
 	} catch (spillError) {
-		const both = new AggregateError([...errorsOf(error), spillError]);
 		return {
 			...result,
-			stderr: errorText(both, format)
+			stderr: errorText(withLeaves(failure, spillError, format), format)
 		};
 	}
 }
@@ -10352,107 +10611,6 @@ function rootSpec(cli, launch) {
 	} : groupSpec(names, cli.commands, builtInCommands(cli, launch));
 }
 //#endregion
-//#region ../agent-cli/dist/command-errors.js
-/**
-* `error`, or a bug naming each Error table code in it that the Command does not declare in its
-* `errors`. Runtime codes are never in the table, and a built-in's failures, `doctor` rows'
-* included, belong to no declaration, so both pass.
-*/
-function checkedCodes(error, { command, path, builtIn }, cli) {
-	if (builtIn) return error;
-	const table = errorTableOf(cli);
-	const declared = new Set(command.errors ?? []);
-	const undeclared = errorsOf(error).flatMap((leaf) => leaf instanceof CliError && Object.hasOwn(table, leaf.code) && !declared.has(leaf.code) ? [leaf.code] : []);
-	if (undeclared.length === 0) return error;
-	const label = commandLabel(path, cli.name).join(" ");
-	const codes = [...new Set(undeclared)].join(", ");
-	return new Error(`\`${label}\` threw ${codes}, which its errors do not declare`, { cause: error });
-}
-//#endregion
-//#region ../agent-cli/dist/context/operator.js
-const NEEDS_OPERATOR = "NEEDS_OPERATOR";
-/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
-function checkOperator({ operator, commandLine }, env, rerun) {
-	if (!operator || !isAgent(env)) return;
-	throw new CliError({
-		code: NEEDS_OPERATOR,
-		message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
-		hint: "ask the operator to type ! then the Next step",
-		next: [rerun]
-	});
-}
-//#endregion
-//#region ../agent-cli/dist/context/outputs.js
-const OUTPUT_EXISTS = "OUTPUT_EXISTS";
-/** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
-async function checkOutputs({ rerun, commandLine, force, files }, outputs) {
-	if (outputs === void 0 || force) return;
-	const found = await Promise.all(outputs.map((path) => files.exists(path)));
-	const existing = outputs.filter((_path, index) => found[index]);
-	if (existing.length === 0) return;
-	const them = existing.length === 1 ? "it" : "them";
-	throw new CliError({
-		code: OUTPUT_EXISTS,
-		message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
-		hint: `once the user agrees to replace ${them}, run the Next step`,
-		next: [rerun({ add: [FORCE_FLAG.flag] })]
-	});
-}
-/** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
-function outputsGuard(files, cwd) {
-	const unwritten = /* @__PURE__ */ new Set();
-	let forceStep = [];
-	const exclusiveWrite = async (path, data, options) => {
-		const target = resolve(cwd, path);
-		unwritten.delete(target);
-		try {
-			await files.write(path, data, {
-				...options,
-				exclusive: true
-			});
-		} catch (error) {
-			unwritten.add(target);
-			if (!(error instanceof CliError) || error.code !== "ALREADY_EXISTS") throw error;
-			throw new CliError({
-				code: ALREADY_EXISTS,
-				message: error.message,
-				hint: "once the user agrees to replace it, run the Next step",
-				next: [forceStep]
-			}, { cause: error });
-		}
-	};
-	return {
-		files: {
-			...files,
-			write: (path, data, options) => unwritten.has(resolve(cwd, path)) ? exclusiveWrite(path, data, options) : files.write(path, data, options)
-		},
-		guard: (outputs, step) => {
-			forceStep = step;
-			for (const path of outputs) unwritten.add(resolve(cwd, path));
-		}
-	};
-}
-/**
-* Creates each output folder and a temp file in it, so a sandbox denial fails before `apply`
-* spends anything. The temp file's name is the Runtime's, so a crashed run's leftover is swept.
-*/
-async function probeOutputs({ files, cwd, fileError }, outputs) {
-	const folders = new Set(outputs.map((path) => dirname(resolve(cwd, path))));
-	await Promise.all([...folders].map(async (folder) => {
-		const probe = tempPathOf(join(folder, "outputs-probe"));
-		try {
-			await files.mkdir(folder);
-			await files.write(probe, "");
-			await files.remove(probe);
-		} catch (error) {
-			throw fileError(error, {
-				path: folder,
-				access: "write"
-			});
-		}
-	}));
-}
-//#endregion
 //#region ../agent-cli/dist/context/spill.js
 const STDOUT_BUDGET_CHARS = 3e4;
 const SPILL_RETENTION_MS = 6048e5;
@@ -11033,43 +11191,6 @@ function resolveOptions(options) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/context/confirm.js
-const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
-const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
-function checkConfirmation({ rerun, commandLine, given }, expected) {
-	if (given === expected) return;
-	const advice = {
-		hint: "once the user confirms the target, run the Next step",
-		next: [rerun({
-			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}`,
-		...advice
-	});
-	throw new UsageError({
-		code: CONFIRMATION_MISMATCH,
-		message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
-		...advice
-	});
-}
-//#endregion
-//#region ../agent-cli/dist/context/cost.js
-const NOT_CONFIRMED = "NOT_CONFIRMED";
-/** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
-function checkCost({ rerun, commandLine, yes }, cost) {
-	if (cost === void 0 || yes) return;
-	throw new CliError({
-		code: NOT_CONFIRMED,
-		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
-		hint: "once the user approves the cost, run the Next step",
-		next: [rerun({ add: [YES_FLAG.flag] })]
-	});
-}
-//#endregion
 //#region ../agent-cli/dist/execute.js
 const PLAN_INDENT = "  ";
 function outcomeOf(value, render) {
@@ -11117,8 +11238,8 @@ function serveContextOf(ctx, end) {
 	const serveCtx = Object.create(ctx);
 	return Object.assign(serveCtx, { end });
 }
-async function execute(command, input, ctx, { dryRun, confirm, yes, page, commandLine, started, files, guardOutputs }) {
-	await checkTools(command.tools ?? [], ctx.env, ctx.rerun());
+async function execute(command, input, ctx, { flags, commandLine, started, outputs: runOutputs }) {
+	await checkTools(command.tools ?? [], ctx, ctx.rerun());
 	const { env, envFile, fileError } = ctx;
 	checkSecrets(command.secrets ?? [], {
 		env,
@@ -11129,7 +11250,7 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, page, comman
 		const { render } = command;
 		return outcomeOf(await command.run({
 			...input,
-			...page
+			...flags.page
 		}, ctx), (data, style) => render === void 0 ? encode(data.items) : render(data, style));
 	}
 	if (command.effect === "read" || command.effect === "act") return dataOutcome(command, await command.run(input, ctx), commandLine);
@@ -11144,32 +11265,28 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, page, comman
 		return outcome;
 	}
 	const plan = await command.plan(input, ctx);
-	if (dryRun) return dryRunOutcome(command, plan, commandLine);
+	if (ctx.dryRun) return dryRunOutcome(command, plan, commandLine);
 	const outputs = command.outputs?.(plan);
-	await checkOutputs({
-		rerun: ctx.rerun,
+	const { rerun, force } = ctx;
+	if (outputs !== void 0) await runOutputs.refuseOverwrite(outputs, {
+		rerun,
 		commandLine,
-		force: ctx.force,
-		files: ctx.files
-	}, outputs);
+		force
+	});
 	checkCost({
-		rerun: ctx.rerun,
+		rerun,
 		commandLine,
-		yes
+		yes: flags.yes
 	}, command.cost?.(plan));
 	if (command.effect === "destructive") checkConfirmation({
-		rerun: ctx.rerun,
+		rerun,
 		commandLine,
-		given: confirm
+		given: flags.confirm
 	}, command.confirm(plan));
-	if (outputs !== void 0) {
-		await probeOutputs({
-			files,
-			cwd: ctx.cwd,
-			fileError: ctx.fileError
-		}, outputs);
-		if (!ctx.force) guardOutputs(outputs, ctx.rerun({ add: [FORCE_FLAG.flag] }));
-	}
+	if (outputs !== void 0) await runOutputs.claim(outputs, {
+		rerun,
+		force
+	});
 	return dataOutcome(command, await command.apply(plan, ctx), commandLine);
 }
 const manifestSchema = object({ bugs: union([string(), object({ url: string() })]).transform((value) => typeof value === "string" ? value : value.url).optional().catch(void 0) });
@@ -11185,16 +11302,7 @@ function manifestAt(packageRoot) {
 	return parsed.success ? parsed.data : NO_MANIFEST;
 }
 //#endregion
-//#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 runDeadlineAdvice(resumed, pipedLine) {
-	return resumed === void 0 ? { hint: stdinNeverEndedHint(pipedLine) } : {
-		hint: "run the Next step to continue the work",
-		next: [resumed]
-	};
-}
+//#region ../agent-cli/dist/run-scope.js
 function selfOf(name, bin) {
 	return bin === void 0 ? [name] : [
 		process.execPath,
@@ -11213,49 +11321,83 @@ function portsOf(cli, replacement) {
 	if (replacement !== void 0) return () => replacement;
 	return cli.ports ?? (() => ({}));
 }
-function portsBaseOf(scope, signal) {
-	const { cli, options, packageRoot, progress, fileError, rerun, clock, files } = scope;
-	const { cwd, env } = options;
+function runScopeOf(cli, routed, settings, write, baseInvocation) {
+	const { cwd, env } = settings;
+	const clock = settings.clock ?? realClock;
+	const platform = settings.platform ?? process.platform;
+	const invocation = {
+		...baseInvocation,
+		flags: knownFlags(routed.spec),
+		stdinArg: stdinArgOf(routed)
+	};
+	const rerun = (change) => ({
+		kind: "rerun",
+		words: changedArgv(invocation, change),
+		stdinArg: invocation.stdinArg
+	});
+	const fileError = fileErrorOf({
+		rerun: rerun(),
+		env,
+		platform
+	});
+	const outputs = outputsOf(settings.files ?? realFiles(), {
+		cwd,
+		fileError
+	});
+	const packageRoot = packageRootOf(settings.bin, cwd);
+	const progress = (message) => write.stderr(progressLine(message, routed.json));
 	const envFile = envFileOf(cli.name, env);
+	const spawning = {
+		fileError,
+		rerun: rerun()
+	};
 	return {
-		cwd,
-		env,
-		packageRoot,
-		progress,
-		secret: (name) => secretOf({
-			envFile,
-			env,
-			fileError
-		}, name),
-		envFile,
+		invocation,
+		rerun,
 		fileError,
-		version: cli.version,
-		build: buildStamp(),
-		self: selfOf(cli.name, options.bin),
-		signal,
 		clock,
-		files,
-		spawn: contextSpawn(options.spawn ?? realSpawn, {
-			cwd,
-			env,
-			signal
-		}, {
-			fileError,
-			rerun
-		}),
-		spawnDetached: contextSpawnDetached(spawnDetachedOf(options), {
+		platform,
+		outputs,
+		progress,
+		notice: (text) => write.stderr(noticeLine(text, routed.json)),
+		packageRoot,
+		ports: portsOf(cli, settings.ports),
+		portsBase: (signal) => ({
 			cwd,
 			env,
-			signal
-		}, {
+			platform,
+			packageRoot,
+			progress,
+			secret: (name) => secretOf({
+				envFile,
+				env,
+				fileError
+			}, name),
+			envFile,
 			fileError,
-			rerun
+			version: cli.version,
+			build: buildStamp(),
+			self: selfOf(cli.name, settings.bin),
+			signal,
+			clock,
+			files: outputs.files,
+			spawn: contextSpawn(settings.spawn ?? realSpawn, {
+				cwd,
+				env,
+				signal
+			}, spawning),
+			spawnDetached: contextSpawnDetached(spawnDetachedOf(settings), {
+				cwd,
+				env,
+				signal
+			}, spawning)
 		})
 	};
 }
-function contextOf(portsBase, control, parts) {
-	const { ports, project, force, dryRun, secrets = [], rerun, deliver, notice } = parts;
-	const declared = new Map(secrets.map((declaration) => [declaration.name, declaration]));
+function contextOf(scope, control, { command, flags, project, deliver }) {
+	const portsBase = scope.portsBase(control.signal);
+	const ports = once(() => scope.ports(portsBase));
+	const declared = new Map((command.secrets ?? []).map((declaration) => [declaration.name, declaration]));
 	function secret(name) {
 		const declaration = declared.get(name);
 		if (declaration === void 0) throw new Error(`ctx.secret("${name}") names a Secret the Command does not declare`);
@@ -11273,47 +11415,57 @@ function contextOf(portsBase, control, parts) {
 			return ports();
 		},
 		project,
-		force,
-		dryRun,
-		rerun,
+		force: flags.force,
+		dryRun: flags.dryRun,
+		rerun: scope.rerun,
 		poll: (check, { intervalMs, signal: stop }) => poll(portsBase.clock, check, intervalMs, stop === void 0 ? control.signal : AbortSignal.any([control.signal, stop])),
 		deliver,
-		notice
+		notice: scope.notice
+	};
+}
+/** `build` runs on the first call; later calls give its value or throw its error again. */
+function once(build) {
+	let outcome;
+	return () => {
+		if (outcome === void 0) try {
+			outcome = {
+				ok: true,
+				value: build()
+			};
+		} catch (error) {
+			outcome = {
+				ok: false,
+				error
+			};
+		}
+		if (outcome.ok) return outcome.value;
+		throw outcome.error;
+	};
+}
+//#endregion
+//#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 runDeadlineAdvice(resumed, pipedLine) {
+	return resumed === void 0 ? { hint: stdinNeverEndedHint(pipedLine) } : {
+		hint: "run the Next step to continue the work",
+		next: [resumed]
 	};
 }
-/** Leaves the Side task running, so the caller writes the result before it waits for it. */
+/**
+* Leaves the Side task running, so the caller writes the result before it waits for it.
+*
+* A gate that needs no `ctx` (operator, parse, Project file) runs here; one that does (tools,
+* Secrets, the Plan's) runs in `execute`, after the Notices, so a failing run still delivers them.
+*/
 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 progress = (message) => write.stderr(progressLine(message, routed.json));
-	const invocation = {
-		...baseFormat.invocation,
-		flags: knownFlags(routed.spec),
-		stdinArg: stdinArgOf(routed)
-	};
-	const rerunOf = (change) => ({
-		kind: "rerun",
-		words: changedArgv(invocation, change),
-		stdinArg: invocation.stdinArg
-	});
+	const scope = runScopeOf(cli, routed, options, write, baseFormat.invocation);
+	const { invocation, rerun: rerunOf, fileError, clock, outputs, progress, platform } = scope;
 	const rerun = rerunOf();
-	const fileError = fileErrorOf({
-		rerun,
-		env,
-		platform
-	});
-	const format = {
-		...baseFormat,
-		bugs: () => manifestAt(packageRoot).bugs,
-		json: routed.json,
-		invocation
-	};
 	const pipedLine = commandLineOf({
 		...invocation,
 		stdinArg: void 0
@@ -11330,10 +11482,18 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			advice: () => runDeadlineAdvice(resumed, pipedLine)
 		}
 	});
-	const failed = (error, finishSideTask) => {
+	const format = {
+		...baseFormat,
+		command: routed.spec,
+		control,
+		bugs: () => manifestAt(scope.packageRoot).bugs,
+		json: routed.json,
+		invocation
+	};
+	const failed = async (error, finishSideTask) => {
 		control.close();
 		return {
-			result: errorResult(error, format),
+			result: await errorResult(error, format),
 			finishSideTask
 		};
 	};
@@ -11352,24 +11512,9 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	}
 	const { input, flags } = parsed;
 	resumed = command.deadline?.resume(input, rerunOf);
-	const outputs = outputsGuard(classifiedFiles(files, {
-		cwd,
-		fileError
-	}), cwd);
-	const scope = {
-		cli,
-		options,
-		packageRoot,
-		progress,
-		fileError,
-		rerun,
-		clock,
-		files: outputs.files
-	};
-	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));
+		const sideBase = scope.portsBase(sideSignal);
+		const sidePorts = once(() => scope.ports(sideBase));
 		return {
 			...sideBase,
 			command: routed.spec.path,
@@ -11394,14 +11539,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		return failed(error, finishSideTask);
 	}
 	let delivered;
-	const ctx = contextOf(portsBase, control, {
-		ports: once(() => ports(portsBase)),
+	const ctx = contextOf(scope, control, {
+		command,
+		flags,
 		project,
-		force: flags.force,
-		dryRun: flags.dryRun,
-		secrets: command.secrets,
-		rerun: rerunOf,
-		notice: (text) => write.stderr(noticeLine(text, routed.json)),
 		deliver: (data) => {
 			delivered = () => dataOutcome(command, data, commandLine);
 		}
@@ -11420,19 +11561,16 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		const outcome = await control.settle(noticesOf(cli, {
 			builtIn,
 			bin: options.bin,
-			node: options.node
+			node: options.node,
+			platform
 		}, ctx).then(() => execute(command, input, ctx, {
-			dryRun: flags.dryRun,
-			confirm: flags.confirm,
-			yes: flags.yes,
-			page: flags.page,
+			flags,
 			commandLine,
 			started: async (outcome) => {
 				write.stdout(await startedOutput(outcome, format, spill));
 				served = true;
 			},
-			files,
-			guardOutputs: outputs.guard
+			outputs
 		})));
 		if (served) return {
 			result: STOPPED_RESULT,
@@ -11449,7 +11587,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		};
 		settled = {
 			ok: false,
-			error: checkedCodes(control.errorAfter(error), routed.spec, cli),
+			error,
 			delivered
 		};
 	}
@@ -11461,25 +11599,6 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		finishSideTask
 	};
 }
-/** `build` runs on the first call; later calls give its value or throw its error again. */
-function once(build) {
-	let outcome;
-	return () => {
-		if (outcome === void 0) try {
-			outcome = {
-				ok: true,
-				value: build()
-			};
-		} catch (error) {
-			outcome = {
-				ok: false,
-				error
-			};
-		}
-		if (outcome.ok) return outcome.value;
-		throw outcome.error;
-	};
-}
 async function noticesOf(cli, launch, ctx) {
 	await installOf(cli).notice(launch, ctx);
 }
@@ -11538,7 +11657,8 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 	const runAs = runAsOf(cli);
 	const root = rootSpec(cli, {
 		bin: options.bin,
-		node: options.node
+		node: options.node,
+		platform: options.platform ?? process.platform
 	});
 	const format = {
 		cliName: cli.name,
@@ -11552,7 +11672,7 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 		json: false,
 		errors: errorTableOf(cli),
 		stop: options.signal,
-		...options.checkNextSteps === true ? { checkNextStep: (step) => nextStepProblem(root, runAs, step) } : {}
+		...options.checkNextSteps === true ? { nextStepCheck: nextStepCheck(root, runAs) } : {}
 	};
 	const routed = route(root, format.invocation);
 	const misused = (node) => isAgent(options.env) ? {
@@ -11631,7 +11751,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.27.0",
+	version: "0.29.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },
@@ -11918,13 +12038,12 @@ async function ensureFree(path) {
 //#region src/bin.ts
 await runProcess(defineCli({
 	manifest: package_default,
-	command: defineCommand({
+	command: defineCommand.write({
 		description: "Create a new Agent CLI project in ./<name>",
 		examples: [{
 			command: "create-agent-cli weather --description \"Weather forecasts\"",
 			note: "create ./weather, install dependencies and make the first commit"
 		}],
-		effect: "write",
 		errors: ["STEP_FAILED"],
 		args: object({ name: string().regex(PACKAGE_NAME, "must be a lowercase npm package name, such as weather or @me/weather").describe("package name; its unscoped part names the bin and the directory") }),
 		options: object({