@duyquangnvx/create-agent-cli 0.29.0 → 0.30.1

package/CHANGELOG.md

@@ -4,6 +4,28 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.30.1 (2026-11-09)
+
+### Fixed
+
+- `ctx.spawn` kills a child that ignores SIGTERM with SIGKILL 2 s after stopping it, so it no longer outlives the CLI and the Command's cleanup runs within the grace.
+- Nothing of a run reaches stdout or stderr after its output, so the error a caller reads last stays last: a Side task's own progress, and progress from a Command still running past its grace, such as `finishing <name>` from a `runToEnd` it starts late, were printed after the output while the run waited for its Side task. A Side task's failure under `<NAME>_DEBUG=1` still prints after it.
+
+## v0.30.0 (2026-11-09)
+
+### Added
+
+- A Side task learns how its run ended: `SideTaskRun` has `ended`, a promise of `RunEnd`, `{ exitCode, errors: [{ code, message }] }` with no errors on success, as the caller sees it, the Runtime's codes such as `INTERRUPTED` included. `RunEnd` and `RunEndError` are exported.
+- `defineCli({ skill })` of a Global install takes `add`, the whole line that installs the skill from its Skill Hub, so the Hub sees who installed it. `setup` then copies no skill and ends with `run: <add>`, its `--json` `skill` being `{ add }`, on every run; `update` leaves the Skill copy alone, its `skill` being `null`; and `doctor`'s `skill` row passes on any one home copy and gives `add` as the fix when there is none. `defineCli` throws on an empty or multi-line `add`, and on `add` beside any install but a Global install. Users whose copy came from the package move to the Hub when they run `setup` again, so a CLI that adds `add` asks them to.
+
+### Changed
+
+- **Breaking:** `defineCli({ sideTask })` also runs for a Command whose input is rejected, such as a missing arg or an unknown option after its name, with `dryRun` false, so a usage count also counts those runs.
+
+### Upgrade from v0.29.0
+
+- A Side task that must not count a run whose input was rejected awaits `ended` and skips that run by its error code, such as `INVALID_INPUT`.
+
 ## v0.29.0 (2026-11-09)
 
 ### Added

package/dist/bin.js

@@ -5740,6 +5740,40 @@ function untilAborted(signal) {
 	});
 }
 //#endregion
+//#region ../agent-cli/dist/clock.js
+const realClock = {
+	now: () => Date.now(),
+	sleep: (ms, signal) => new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	})
+};
+/** Runs `then` once `ms` have passed on `clock`; aborting `cancel` drops it. */
+function after(clock, ms, cancel, then) {
+	clock.sleep(ms, cancel).then(then, (error) => {
+		if (!cancel.aborted) throw error;
+	});
+}
+async function poll(clock, check, intervalMs, signal) {
+	for (;;) {
+		signal.throwIfAborted();
+		const value = await check();
+		if (value !== void 0) return value;
+		await clock.sleep(intervalMs, signal);
+	}
+}
+//#endregion
 //#region ../agent-cli/dist/command-line/tokenize.js
 const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
 function isOptionLike(word) {
@@ -5972,10 +6006,19 @@ 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}`;
 }
+/** The code and message the caller sees for one error a run failed with. */
+function runEndErrorOf(error) {
+	return error instanceof CliError ? {
+		code: error.code,
+		message: error.message
+	} : {
+		code: INTERNAL,
+		message: messageOf(error)
+	};
+}
 function fieldsOf$1({ error, exitClass }, format) {
 	if (!(error instanceof CliError)) return {
-		code: INTERNAL,
-		message: messageOf(error),
+		...runEndErrorOf(error),
 		hint: bugHint(format)
 	};
 	const { code, message, hint, details, retryAt, next } = error;
@@ -6055,6 +6098,149 @@ function lastLines(output, count) {
 	return output.trim().split("\n").slice(-count).join("\n");
 }
 //#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/define.js
 function isCommand(node) {
 	return typeof node.effect === "string";
@@ -6137,6 +6323,7 @@ function toolRows(tools, commands, platform) {
 const TOOL_FAILED = "TOOL_FAILED";
 const STDERR_TAIL_LINES$1 = 20;
 const SIGNAL_EXIT_BASE = 128;
+const KILL_AFTER_MS = 2e3;
 const BATCH_FILE = /\.(?:cmd|bat)$/i;
 const CMD_SHIM = /\.cmd$/i;
 const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
@@ -6173,9 +6360,10 @@ async function windowsLaunch(command, args, env) {
 		shell: true
 	};
 }
-function stop(child) {
+function stop(child, exited) {
 	if (process.platform !== "win32" || child.pid === void 0) {
 		child.kill();
+		after(realClock, KILL_AFTER_MS, exited, () => child.kill("SIGKILL"));
 		return Promise.resolve();
 	}
 	const pid = String(child.pid);
@@ -6271,8 +6459,9 @@ async function spawnChild(command, args, { cwd, env, signal, onLine, stdin, deta
 			detached: detached && process.platform !== "win32"
 		});
 		let stopped = Promise.resolve();
+		const exited = new AbortController();
 		const kill = () => {
-			stopped = stop(child);
+			stopped = stop(child, exited.signal);
 		};
 		signal.addEventListener("abort", kill, { once: true });
 		let callerFailure;
@@ -6295,7 +6484,9 @@ async function spawnChild(command, args, { cwd, env, signal, onLine, stdin, deta
 			stderrLines.push(chunk);
 		});
 		if (stdin !== void 0 && child.stdin !== null) feed(child.stdin, stdin, signal).catch(fail);
+		child.once("exit", () => exited.abort());
 		child.on("error", (error) => {
+			exited.abort();
 			signal.removeEventListener("abort", kill);
 			reject(error);
 		});
@@ -6444,40 +6635,6 @@ function contextSpawnDetached(run, defaults, scope) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/clock.js
-const realClock = {
-	now: () => Date.now(),
-	sleep: (ms, signal) => new Promise((resolve, reject) => {
-		if (signal?.aborted === true) {
-			reject(signal.reason);
-			return;
-		}
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(signal?.reason);
-		};
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		signal?.addEventListener("abort", onAbort, { once: true });
-	})
-};
-/** Runs `then` once `ms` have passed on `clock`; aborting `cancel` drops it. */
-function after(clock, ms, cancel, then) {
-	clock.sleep(ms, cancel).then(then, (error) => {
-		if (!cancel.aborted) throw error;
-	});
-}
-async function poll(clock, check, intervalMs, signal) {
-	for (;;) {
-		signal.throwIfAborted();
-		const value = await check();
-		if (value !== void 0) return value;
-		await clock.sleep(intervalMs, signal);
-	}
-}
-//#endregion
 //#region ../agent-cli/dist/context/stdin.js
 const STDIN_META = "stdin";
 function isStdinSchema(schema) {
@@ -7058,149 +7215,6 @@ function classifyErrno(error, context) {
 	}
 }
 //#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. */
@@ -7734,9 +7748,9 @@ function cliErrorOf(code, init, options) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "0478338",
+		"sha": "7f79c40",
 		"dirty": false,
-		"builtAt": "2026-11-09T05:16:34.000Z"
+		"builtAt": "2026-11-09T07:03:37.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -8398,12 +8412,19 @@ const homeSyncSchema = object({
 	written: array(string()),
 	removed: array(string())
 });
+function copiedFromPackage(skill) {
+	return skill !== void 0 && skill.add === void 0;
+}
+/** The home Skill copies `setup` and `update` write: none when the skill comes from its Skill Hub. */
+async function syncedCopiesOf(cli, ctx) {
+	return copiedFromPackage(cli.skill) ? homeCopiesOf(ctx.files, cli.name, ctx.env) : [];
+}
 /**
 * Makes each home Skill copy match the folder in the package at `packageDir`. Null when the CLI
-* declares no skill, or that package ships none, which must not empty a copy.
+* declares no skill, its Skill Hub installs it, or that package ships none, which must not empty a copy.
 */
 async function syncHome(cli, packageDir, ctx) {
-	if (cli.skill === void 0) return null;
+	if (!copiedFromPackage(cli.skill)) return null;
 	const source = join(packageDir, cli.skill.folder);
 	if ((await filesIn(ctx.files, source)).length === 0) return null;
 	const copies = await homeCopiesOf(ctx.files, cli.name, ctx.env);
@@ -8463,14 +8484,27 @@ async function findingOf$1(cli, folder, install, ctx) {
 		fix: `${install.runAs} setup`
 	};
 }
-/** A skill the package ships, which `setup` and `update` copy under home. */
-function homeSkill(cli, { folder }, install) {
+async function hubFindingOf(cli, add, ctx) {
+	const paths = await homeCopiesOf(ctx.files, cli.name, ctx.env);
+	const copies = await Promise.all(paths.map((path) => homeCopyAt(ctx.files, path)));
+	const found = copies.filter((copy) => copy.state !== "missing");
+	return found.length === 0 ? {
+		state: "problem",
+		message: copies.map(describeCopy).join("; "),
+		fix: add
+	} : {
+		state: "ok",
+		message: found.map((copy) => copy.path).join("; ")
+	};
+}
+/** A skill the package ships, which `setup` and `update` copy under home unless its Skill Hub installs it. */
+function homeSkill(cli, { folder, add }, install) {
 	return {
 		builtIns: {},
 		rows: [{
 			name: "skill",
 			advisory: true,
-			run: (ctx) => findingOf$1(cli, folder, install, ctx)
+			run: (ctx) => add === void 0 ? findingOf$1(cli, folder, install, ctx) : hubFindingOf(cli, add, ctx)
 		}]
 	};
 }
@@ -8543,7 +8577,7 @@ const setupSchema = object({
 	version: string(),
 	prefix: string(),
 	installed: boolean(),
-	skill: homeSyncSchema.nullable(),
+	skill: union([homeSyncSchema, object({ add: string() })]).nullable(),
 	upgrades: array(upgradeSchema),
 	docs: string().nullable()
 });
@@ -8603,13 +8637,23 @@ function withSetupLine(error, install) {
 		next: [wholeLine(setupLineOf(install))]
 	}, { cause: error });
 }
+function renderNext(name, docs, skill) {
+	const read = docs === null ? [] : [`docs ${docs}`];
+	if (skill === null || !("add" in skill)) return docs === null ? read : [...read, `Read that folder before using ${name}.`];
+	const then = docs === null ? "" : `, then read that folder before using ${name}`;
+	return [
+		...read,
+		`Install the ${name} skill from its Skill Hub${then}.`,
+		`run: ${skill.add}`
+	];
+}
 function renderSetup(cli, install, setup) {
-	const { version, prefix, docs } = setup;
+	const { version, prefix, docs, skill } = setup;
 	return [
 		setup.installed ? `installed ${install.package}@${version} with the npm under ${prefix}` : `${install.package}@${version} is already installed under ${prefix}`,
-		...renderHomeSync(cli.name, setup.skill),
+		...skill !== null && "copies" in skill ? renderHomeSync(cli.name, skill) : [],
 		...setup.upgrades.map(renderUpgrade),
-		...docs === null ? [] : [`docs ${docs}`, `Read that folder before using ${cli.name}.`]
+		...renderNext(cli.name, docs, skill)
 	].join("\n");
 }
 /** The built-in `setup`, which runs from any copy, such as npx's, so it never asks to be the global one. */
@@ -8645,7 +8689,7 @@ function setupCommand(cli, install, launch) {
 				latest: await latestVersion(npm),
 				prefix,
 				packageDir,
-				copies: cli.skill === void 0 ? [] : await homeCopiesOf(ctx.files, cli.name, ctx.env)
+				copies: await syncedCopiesOf(cli, ctx)
 			};
 		},
 		apply: async (plan, ctx) => {
@@ -8664,16 +8708,25 @@ function setupCommand(cli, install, launch) {
 				version: installs || from === null ? latest : from,
 				prefix,
 				installed: installs,
-				skill,
+				skill: cli.skill?.add === void 0 ? skill : { add: cli.skill.add },
 				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"
-			});
+			if (ctx.signal.aborted) {
+				const add = cli.skill?.add;
+				if (add === void 0) throw new CliError({
+					code: INTERRUPTED,
+					message: `interrupted, but ${plan.package}@${setup.version} and its skill are already in place`,
+					hint: "nothing to run again"
+				});
+				throw runtimeError({
+					code: INTERRUPTED,
+					message: `interrupted, but ${plan.package}@${setup.version} is already installed`,
+					hint: "run the Next step to install its skill from its Skill Hub",
+					next: [wholeLine(add)]
+				});
+			}
 			await assertOnPath(cli, prefix, launch, ctx);
 			return setup;
 		},
@@ -8734,7 +8787,7 @@ function updateCommand(cli, install, launch) {
 				latest: await latestVersion(npm),
 				prefix: copy.prefix,
 				packageDir: copy.packageDir,
-				copies: cli.skill === void 0 ? [] : await homeCopiesOf(ctx.files, cli.name, ctx.env)
+				copies: await syncedCopiesOf(cli, ctx)
 			};
 		},
 		apply: async (plan, ctx) => {
@@ -9635,6 +9688,11 @@ function checkTree(commands, path, table) {
 }
 function checkSkill({ name, skill, install }) {
 	if (skill?.agents !== void 0 && install?.mode === "global") throw new Error(`${name} declares an Agents section on a Global install, which has no repo to write it to`);
+	const add = skill?.add;
+	if (add === void 0) return;
+	if (add.trim() === "") throw new Error(`${name} declares an empty Skill Hub install line`);
+	if (/[\r\n]/.test(add)) throw new Error(`${name} declares a Skill Hub install line holding a line break`);
+	if (install?.mode !== "global") throw new Error(`${name} declares a Skill Hub install line, which only a Global install uses: any other's Skill copy goes in the project`);
 }
 function checkDocs({ name, docs }) {
 	if (docs === void 0) return;
@@ -9732,17 +9790,25 @@ function agentCli(values = {}) {
 /** How long a run waits for its Side task once its output is written. */
 const SIDE_TASK_WAIT_MS = 1e3;
 const noSideTask = async () => {};
+const NO_SIDE_TASK = {
+	end: () => {},
+	finish: noSideTask
+};
 function waitOver() {
 	return new DOMException(`the side task ran past its ${SIDE_TASK_WAIT_MS} ms wait`, "TimeoutError");
 }
 function startSideTask(sideTask, runWith, { clock, failed }) {
-	if (sideTask === void 0) return noSideTask;
+	if (sideTask === void 0) return NO_SIDE_TASK;
+	let end = () => {};
+	const ended = new Promise((resolve) => {
+		end = resolve;
+	});
 	const controller = new AbortController();
 	const { signal } = controller;
-	const running = (async () => sideTask(runWith(signal)))().catch((error) => {
+	const running = (async () => sideTask(runWith(signal, ended)))().catch((error) => {
 		if (!(signal.aborted && error === signal.reason)) failed(error);
 	});
-	return async () => {
+	const finish = async () => {
 		const waited = new AbortController();
 		const capped = new Promise((resolve) => after(clock, SIDE_TASK_WAIT_MS, waited.signal, () => {
 			const over = waitOver();
@@ -9753,6 +9819,10 @@ function startSideTask(sideTask, runWith, { clock, failed }) {
 		await Promise.race([running, capped]);
 		waited.abort();
 	};
+	return {
+		end,
+		finish
+	};
 }
 //#endregion
 //#region ../agent-cli/dist/command-line/suggest.js
@@ -10492,11 +10562,24 @@ function errorText({ leaves }, format) {
 	const { usageHelp, json } = format;
 	return usageHelp !== void 0 && !json && leaves.some((leaf) => leaf.error instanceof UsageError) ? `${text}\n${usageHelp}` : text;
 }
+function endOf(failure) {
+	return {
+		exitCode: failure.exitCode,
+		errors: failure.leaves.map((leaf) => runEndErrorOf(leaf.error))
+	};
+}
+const SUCCEEDED = {
+	exitCode: SUCCESS_EXIT_CODE,
+	errors: []
+};
 function failedResult(failure, format) {
 	return {
-		stdout: "",
-		stderr: errorText(failure, format),
-		exitCode: failure.exitCode
+		result: {
+			stdout: "",
+			stderr: errorText(failure, format),
+			exitCode: failure.exitCode
+		},
+		end: endOf(failure)
 	};
 }
 function stdoutOf({ value, render }, format, spill) {
@@ -10511,10 +10594,13 @@ function startedOutput(outcome, format, spill) {
 	}, spill);
 }
 /** A serve Command stopped, or ended itself, after it started: that is how it is meant to end. */
-const STOPPED_RESULT = {
-	stdout: "",
-	stderr: "",
-	exitCode: SUCCESS_EXIT_CODE
+const STOPPED = {
+	result: {
+		stdout: "",
+		stderr: "",
+		exitCode: SUCCESS_EXIT_CODE
+	},
+	end: SUCCEEDED
 };
 async function errorResult(error, format) {
 	return failedResult(await failureOf(error, format), format);
@@ -10522,9 +10608,12 @@ async function errorResult(error, format) {
 async function commandResult(settled, format, spill) {
 	if (settled.ok) try {
 		return {
-			stdout: await stdoutOf(settled.outcome, format, spill),
-			stderr: "",
-			exitCode: SUCCESS_EXIT_CODE
+			result: {
+				stdout: await stdoutOf(settled.outcome, format, spill),
+				stderr: "",
+				exitCode: SUCCESS_EXIT_CODE
+			},
+			end: SUCCEEDED
 		};
 	} catch (spillError) {
 		return errorResult(spillError, format);
@@ -10538,16 +10627,26 @@ async function commandResult(settled, format, spill) {
 	} catch (rejected) {
 		return failedResult(withLeaves(failure, rejected, format), format);
 	}
-	const result = failedResult(failure, format);
+	const { result, end } = failedResult(failure, format);
 	try {
 		return {
-			...result,
-			stdout: await stdoutOf(outcome, format, spill)
+			result: {
+				...result,
+				stdout: await stdoutOf(outcome, format, spill)
+			},
+			end
 		};
 	} catch (spillError) {
+		const lost = withLeaves(failure, spillError, format);
 		return {
-			...result,
-			stderr: errorText(withLeaves(failure, spillError, format), format)
+			result: {
+				...result,
+				stderr: errorText(lost, format)
+			},
+			end: {
+				...endOf(lost),
+				exitCode: result.exitCode
+			}
 		};
 	}
 }
@@ -11490,13 +11589,35 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		json: routed.json,
 		invocation
 	};
-	const failed = async (error, finishSideTask) => {
-		control.close();
+	const sideTaskOf = (dryRun) => startSideTask(builtIn ? void 0 : cli.sideTask?.bind(cli), (sideSignal, ended) => {
+		const sideBase = scope.portsBase(sideSignal);
+		const sidePorts = once(() => scope.ports(sideBase));
+		return {
+			...sideBase,
+			command: routed.spec.path,
+			dryRun,
+			ended,
+			get ports() {
+				return sidePorts();
+			}
+		};
+	}, {
+		clock,
+		failed: (error) => {
+			if (isDebug(baseFormat)) write.debug(progressLine(`side task failed: ${traceOf(error)}`, routed.json));
+		}
+	});
+	const ran = ({ result, end }, sideTask) => {
+		sideTask.end(end);
 		return {
-			result: await errorResult(error, format),
-			finishSideTask
+			result,
+			finishSideTask: sideTask.finish
 		};
 	};
+	const failed = (error) => {
+		control.close();
+		return errorResult(error, format);
+	};
 	let parsed;
 	try {
 		checkOperator(routed.spec, env, rerun);
@@ -11508,27 +11629,11 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			});
 		});
 	} catch (error) {
-		return failed(error, noSideTask);
+		return ran(await failed(error), sideTaskOf(false));
 	}
 	const { input, flags } = parsed;
 	resumed = command.deadline?.resume(input, rerunOf);
-	const finishSideTask = startSideTask(builtIn ? void 0 : cli.sideTask?.bind(cli), (sideSignal) => {
-		const sideBase = scope.portsBase(sideSignal);
-		const sidePorts = once(() => scope.ports(sideBase));
-		return {
-			...sideBase,
-			command: routed.spec.path,
-			dryRun: flags.dryRun,
-			get ports() {
-				return sidePorts();
-			}
-		};
-	}, {
-		clock,
-		failed: (error) => {
-			if (isDebug(baseFormat)) progress(`side task failed: ${traceOf(error)}`);
-		}
-	});
+	const sideTask = sideTaskOf(flags.dryRun);
 	let project;
 	try {
 		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, {
@@ -11536,7 +11641,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			rerun
 		});
 	} catch (error) {
-		return failed(error, finishSideTask);
+		return ran(await failed(error), sideTask);
 	}
 	let delivered;
 	const ctx = contextOf(scope, control, {
@@ -11572,32 +11677,23 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			},
 			outputs
 		})));
-		if (served) return {
-			result: STOPPED_RESULT,
-			finishSideTask
-		};
+		if (served) return ran(STOPPED, sideTask);
 		settled = {
 			ok: true,
 			outcome
 		};
 	} catch (error) {
-		if (served && control.signal.aborted) return {
-			result: STOPPED_RESULT,
-			finishSideTask
-		};
+		if (served && control.signal.aborted) return ran(STOPPED, sideTask);
 		settled = {
 			ok: false,
 			error,
 			delivered
 		};
 	}
-	return {
-		result: await commandResult(settled, {
-			...format,
-			fields: flags.fields
-		}, spill),
-		finishSideTask
-	};
+	return ran(await commandResult(settled, {
+		...format,
+		fields: flags.fields
+	}, spill), sideTask);
 }
 async function noticesOf(cli, launch, ctx) {
 	await installOf(cli).notice(launch, ctx);
@@ -11648,7 +11744,16 @@ async function whileStopping(signal, onStop, work) {
 }
 /** Runs the CLI, writes its output, then waits for the Side task it started. */
 async function runWithProgress(cli, argv, options, write, stopNotice) {
-	const { result, finishSideTask } = await routeAndRun(cli, argv, options, write, stopNotice);
+	let resultWritten = false;
+	const gated = (writeTo) => (text) => {
+		if (!resultWritten) writeTo(text);
+	};
+	const { result, finishSideTask } = await routeAndRun(cli, argv, options, {
+		stdout: gated(write.stdout),
+		stderr: gated(write.stderr),
+		debug: write.stderr
+	}, stopNotice);
+	resultWritten = true;
 	await write.result(result);
 	await finishSideTask();
 	return result;
@@ -11685,10 +11790,10 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 			...format,
 			json: routed.json
 		}));
-		case "usage error": return ranAlone(errorResult(routed.error, {
+		case "usage error": return ranAlone((await errorResult(routed.error, {
 			...misused(routed.node),
 			json: routed.json
-		}));
+		})).result);
 		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(cli, routed, options, write, misused(routed.spec)));
 	}
 }
@@ -11751,7 +11856,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.29.0",
+	version: "0.30.1",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.29.0",
+    "@duyquangnvx/agent-cli": "0.30.1",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },