@animus-ui/cli 0.1.11 → 0.1.13

package/dist/index.mjs

@@ -1,113 +1,192 @@
-import { AnimusConfigError, assertKnownOptionKeys, buildPathAliasesJson, contentHash, createExcludeMatcher, readTsconfigAliasPairs, resolveMode, runStructuralSelfCheck } from "@animus-ui/extract/pipeline";
+import { AnimusConfigError, assertKnownOptionKeys, assertNoRetiredEngineSelection, buildPathAliasesJson, contentHash, createExcludeMatcher, readTsconfigAliasPairs, resolveMode, runStructuralSelfCheck } from "@animus-ui/extract/pipeline";
 import { parseArgs } from "node:util";
-import { CLI_COMMIT_ARTIFACT, CLI_LOCK_ARTIFACT, ExtractionSession, MANIFEST_ARTIFACT, SESSION_ASSETS_DIR, STYLES_ARTIFACT, SYSTEM_PROPS_ARTIFACT, collectSessionAssets, getAnalyzedHashes, getManifestJson, getSessionArtifactDir, getSharedCss, getSharedSystemProps, startTurbopackWatcher, verifyCommitRecord } from "@animus-ui/extract/session";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "fs";
+import { ANIMUS_ARTIFACT_DIR, CLI_COMMIT_ARTIFACT, CLI_LOCK_ARTIFACT, ExtractionSession, MANIFEST_ARTIFACT, SESSION_ASSETS_DIR, STYLES_ARTIFACT, SYSTEM_PROPS_ARTIFACT, checkLockLiveness, collectSessionAssets, decodeCommitRecord, getAnalyzedHashes, getManifestJson, getSharedCss, getSharedSystemProps, holdDirectoryClaim, isLockHolderAlive, lockRecordBytes, readCliLockRecord, startTurbopackWatcher, verifyCommitRecord } from "@animus-ui/extract/session";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "fs";
 import { dirname, isAbsolute, join, relative, resolve } from "path";
 import { pathToFileURL } from "url";
+const SHUTDOWN_SIGNALS = [["SIGINT", 130], ["SIGTERM", 143]];
+/** Removal is mandatory on the normal path: `main()` is re-enterable in
+*  process, so a listener left behind accumulates one per call. */
+function installShutdownSignals({ release, drain }) {
+	let stage = "armed";
+	const registered = SHUTDOWN_SIGNALS.map(([signal, exitCode]) => {
+		const listener = () => {
+			if (stage === "released") return;
+			if (stage === "draining") {
+				stage = "released";
+				release({
+					exitCode,
+					signal,
+					abandoned: true
+				});
+				process.exit(exitCode);
+			} else if (drain === void 0) {
+				stage = "released";
+				release({
+					exitCode,
+					signal,
+					abandoned: false
+				});
+			} else {
+				stage = "draining";
+				(async () => {
+					try {
+						await drain(exitCode, signal);
+					} catch {}
+					if (stage !== "draining") return;
+					stage = "released";
+					release({
+						exitCode,
+						signal,
+						abandoned: false
+					});
+				})();
+			}
+		};
+		process.on(signal, listener);
+		return {
+			signal,
+			listener
+		};
+	});
+	return () => {
+		for (const { signal, listener } of registered) process.removeListener(signal, listener);
+	};
+}
+//#endregion
 //#region src/writer.ts
-/**
-* Deterministic fixed-path artifact writer (design D3): raw payload bytes —
-* no session envelope, no per-invocation identity — staged into a private
-* subdirectory, VERIFIED there, then renamed into place with `commit.json`
-* LAST carrying content hashes of every payload (asset files included), so
-* a reader holding only the record and the payload bytes can verify set
-* completeness and consistency — and a publication that cannot verify
-* never replaces the previous generation. A single-writer advisory lock
-* fails loud instead of last-writer-wins; the lock never outlives the
-* invocation, so repeated identical builds are byte-identical trees.
-*/
 const STYLES_FILE = STYLES_ARTIFACT;
 const SYSTEM_PROPS_FILE = SYSTEM_PROPS_ARTIFACT;
 const MANIFEST_FILE = MANIFEST_ARTIFACT;
 const COMMIT_FILE = CLI_COMMIT_ARTIFACT;
 const LOCK_FILE = CLI_LOCK_ARTIFACT;
 const ASSETS_DIR = SESSION_ASSETS_DIR;
-/** Publication rejected by the pre-swap consistency check: the staged set
-*  did not verify, and the previous generation was left untouched. */
+function isFileExistsError(error) {
+	return error instanceof Object && "code" in error && error.code === "EEXIST";
+}
+/** Rejected by the pre-swap consistency check: the staged set did not
+*  verify, and the previous generation was left untouched. */
 var PublishInconsistencyError = class extends Error {
+	failures;
 	constructor(failures) {
 		super(`Staged publication failed its consistency check:\n  - ${failures.join("\n  - ")}`);
 		this.failures = failures;
 		this.name = "PublishInconsistencyError";
 	}
 };
-/** Take the single-writer advisory lock, failing loud on a live holder.
-*  Returns a release function. */
+var PublishSwapIncompleteError = class extends Error {
+	outDir;
+	landed;
+	failure;
+	constructor(outDir, landed, failure) {
+		super(`Publication of ${outDir} stopped mid-swap after replacing ${landed.join(", ")} — the directory now mixes two generations and its commit record does not describe it. The next successful publication rewrites the whole set. Cause: ${String(failure)}`);
+		this.outDir = outDir;
+		this.landed = landed;
+		this.failure = failure;
+		this.name = "PublishSwapIncompleteError";
+	}
+};
+/** A refused claim on the output tree: another process owns it, or its lock
+*  cannot be proven dead. Extends `AnimusConfigError`, so it exits 2. */
+var AnimusLockConflictError = class extends AnimusConfigError {
+	constructor(message) {
+		super(message);
+		this.name = "AnimusLockConflictError";
+	}
+};
+const STAGING_PREFIX = ".staging-";
+/** One list drives the staged write, the commit record, the rename, and the
+*  unfinished-publication probe; the order is swap order. */
+const NAMED_PAYLOAD_FIELDS = [
+	[STYLES_FILE, "stylesCss"],
+	[SYSTEM_PROPS_FILE, "systemPropsJs"],
+	[MANIFEST_FILE, "manifestJson"]
+];
+const PUBLISHED_NAMES = [...NAMED_PAYLOAD_FIELDS.map(([name]) => name), COMMIT_FILE];
+/** Called only while the claim is held — deciding a tree is debris and
+*  deleting it is a write. A live pid's tree is its own working set. */
+function reapAbandonedStaging(outDir) {
+	let entries;
+	try {
+		entries = readdirSync(outDir);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (!entry.startsWith(STAGING_PREFIX)) continue;
+		const pid = Number(entry.slice(9));
+		if (!Number.isInteger(pid) || isLockHolderAlive(pid)) continue;
+		console.error(`[animus] Removing staging directory ${entry} left by dead pid ${pid}`);
+		rmSync(join(outDir, entry), {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Reported, not refused: this run republishes the whole set, which is the
+*  repair; refusing would leave the directory wedged. */
+function reportUnfinishedPublication(outDir) {
+	if (!PUBLISHED_NAMES.some((name) => existsSync(join(outDir, name)))) return;
+	const failures = verifyCommitRecord(outDir);
+	if (failures.length === 0) return;
+	console.error(`[animus] ${outDir} holds artifacts that do not match its commit record — a previous publication did not finish:\n  - ${failures.join("\n  - ")}\n[animus] This run replaces the whole set; until it does, nothing in that directory is consistent.`);
+}
+/** Take the single-writer advisory lock; a live holder is a hard failure. */
 function acquireLock(outDir) {
 	mkdirSync(outDir, { recursive: true });
 	const lockPath = join(outDir, LOCK_FILE);
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	try {
-		writeFileSync(lockPath, JSON.stringify({
-			pid: process.pid,
-			startedAt: (/* @__PURE__ */ new Date()).toISOString()
-		}), { flag: "wx" });
+		writeFileSync(lockPath, lockRecordBytes(startedAt), { flag: "wx" });
 	} catch (error) {
-		if (error.code !== "EEXIST") throw error;
-		let holder = {};
-		try {
-			holder = JSON.parse(readFileSync(lockPath, "utf-8"));
-		} catch {}
-		if (typeof holder.pid === "number" && isProcessAlive(holder.pid)) throw new AnimusConfigError(`Another animus process (pid ${holder.pid}, started ${holder.startedAt ?? "unknown"}) owns ${outDir} — wait for it or pass --out-dir to write elsewhere.`);
-		console.error(`[animus] Replacing stale lock left by dead pid ${holder.pid ?? "?"}`);
+		if (!isFileExistsError(error)) throw error;
+		const lock = readCliLockRecord(outDir);
+		let staleReason = "the lock file was removed between the failed claim and the read";
+		if (lock.kind === "held") {
+			const liveness = checkLockLiveness(lock.record);
+			if (liveness.live) throw new AnimusLockConflictError(`Another animus process (pid ${lock.record.pid}, started ${lock.record.startedAt ?? "unknown"}) owns ${outDir} — wait for it or pass --out-dir to write elsewhere.`);
+			staleReason = liveness.reason;
+		}
+		if (lock.kind === "indeterminate") throw new AnimusLockConflictError(`${join(outDir, LOCK_FILE)} exists but is not a readable lock record — its holder cannot be identified. Remove the file if no animus process is running, or pass --out-dir to write elsewhere.`);
+		console.error(`[animus] Replacing stale lock: ${staleReason}`);
 		rmSync(lockPath, { force: true });
 		try {
-			writeFileSync(lockPath, JSON.stringify({
-				pid: process.pid,
-				startedAt: (/* @__PURE__ */ new Date()).toISOString()
-			}), { flag: "wx" });
+			writeFileSync(lockPath, lockRecordBytes(startedAt), { flag: "wx" });
 		} catch (retryError) {
-			if (retryError.code !== "EEXIST") throw retryError;
-			throw new AnimusConfigError(`Another animus process re-acquired ${outDir} while a stale lock was being replaced — wait for it or pass --out-dir.`);
+			if (!isFileExistsError(retryError)) throw retryError;
+			throw new AnimusLockConflictError(`Another animus process re-acquired ${outDir} while a stale lock was being replaced — wait for it or pass --out-dir.`);
 		}
 	}
-	return () => {
-		rmSync(lockPath, { force: true });
-	};
-}
-function isProcessAlive(pid) {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch {
-		return false;
-	}
+	reapAbandonedStaging(outDir);
+	reportUnfinishedPublication(outDir);
+	return holdDirectoryClaim(outDir, {
+		write: "rename",
+		startedAt
+	});
 }
-/** Asset names under `assets/` that outDir's current commit record
-*  published, or empty when no record is readable. */
 function publishedAssetNames(outDir) {
+	let record;
 	try {
-		const record = JSON.parse(readFileSync(join(outDir, COMMIT_FILE), "utf-8"));
-		return new Set(Object.keys(record.payloads ?? {}).filter((name) => name.startsWith(`${ASSETS_DIR}/`)).map((name) => name.slice(ASSETS_DIR.length + 1)));
+		record = decodeCommitRecord(readFileSync(join(outDir, COMMIT_FILE), "utf-8"));
 	} catch {
 		return /* @__PURE__ */ new Set();
 	}
+	if (record === null) return /* @__PURE__ */ new Set();
+	return new Set(Object.keys(record.payloads).filter((name) => name.startsWith(`${ASSETS_DIR}/`)).map((name) => name.slice(ASSETS_DIR.length + 1)));
 }
-/**
-* Publish the payload set. The set is STAGED into a private subdirectory,
-* verified there (recompute-and-compare, the same check
-* `verifyPublishedSet` runs), and only a verified set is renamed into
-* place: payloads first, asset files next, the commit record LAST. A set
-* that cannot verify throws `PublishInconsistencyError` with the previous
-* generation untouched — "keeping last-good artifacts" must be literally
-* true for the watch loop's rejection path. The record carries only
-* content-derived data (asset entries sorted by name) so the full tree is
-* byte-identical across identical-input runs.
-*/
+/** Staged, verified, then renamed into place with the commit record LAST. A
+*  set that cannot verify throws with the previous generation untouched. */
 function publishArtifacts(outDir, payloads) {
 	mkdirSync(outDir, { recursive: true });
 	const previouslyPublishedAssets = publishedAssetNames(outDir);
-	const staging = join(outDir, `.staging-${process.pid}`);
+	const staging = join(outDir, `${STAGING_PREFIX}${process.pid}`);
 	rmSync(staging, {
 		recursive: true,
 		force: true
 	});
 	mkdirSync(staging, { recursive: true });
 	try {
-		const namedPayloads = [
-			[STYLES_FILE, payloads.stylesCss],
-			[SYSTEM_PROPS_FILE, payloads.systemPropsJs],
-			[MANIFEST_FILE, payloads.manifestJson]
-		];
+		const namedPayloads = NAMED_PAYLOAD_FIELDS.map(([name, field]) => [name, payloads[field]]);
 		const record = {
 			schema: 1,
 			payloads: {}
@@ -125,22 +204,35 @@ function publishArtifacts(outDir, payloads) {
 			}
 		}
 		writeFileSync(join(staging, COMMIT_FILE), JSON.stringify(record, null, 2) + "\n");
-		const failures = verifyPublishedSet(staging);
+		const failures = verifyCommitRecord(staging);
 		if (failures.length > 0) throw new PublishInconsistencyError(failures);
-		for (const [name] of namedPayloads) renameSync(join(staging, name), join(outDir, name));
-		const publishedAssetsDir = join(outDir, ASSETS_DIR);
-		if (assets.length > 0) {
-			mkdirSync(publishedAssetsDir, { recursive: true });
-			for (const { name } of assets) renameSync(join(staging, ASSETS_DIR, name), join(publishedAssetsDir, name));
-		}
-		const expectedNames = new Set(assets.map((asset) => asset.name));
-		for (const name of previouslyPublishedAssets) {
-			if (expectedNames.has(name)) continue;
-			try {
-				unlinkSync(join(publishedAssetsDir, name));
-			} catch {}
+		const landed = [];
+		try {
+			for (const [name] of namedPayloads) {
+				renameSync(join(staging, name), join(outDir, name));
+				landed.push(name);
+			}
+			const publishedAssetsDir = join(outDir, ASSETS_DIR);
+			if (assets.length > 0) {
+				mkdirSync(publishedAssetsDir, { recursive: true });
+				for (const { name } of assets) {
+					renameSync(join(staging, ASSETS_DIR, name), join(publishedAssetsDir, name));
+					landed.push(`${ASSETS_DIR}/${name}`);
+				}
+			}
+			const expectedNames = new Set(assets.map((asset) => asset.name));
+			for (const name of previouslyPublishedAssets) {
+				if (expectedNames.has(name)) continue;
+				try {
+					unlinkSync(join(publishedAssetsDir, name));
+				} catch {}
+			}
+			renameSync(join(staging, COMMIT_FILE), join(outDir, COMMIT_FILE));
+			landed.push(COMMIT_FILE);
+		} catch (error) {
+			if (landed.length === 0) throw error;
+			throw new PublishSwapIncompleteError(outDir, landed, error);
 		}
-		renameSync(join(staging, COMMIT_FILE), join(outDir, COMMIT_FILE));
 		return record;
 	} finally {
 		rmSync(staging, {
@@ -149,42 +241,14 @@ function publishArtifacts(outDir, payloads) {
 		});
 	}
 }
-/** The documented consistency check — the session-shared implementation
-*  (published-set.ts): recompute every payload hash raw-bytes and compare
-*  against the commit record. Returns failure lines (empty = consistent). */
-function verifyPublishedSet(outDir) {
-	return verifyCommitRecord(outDir);
-}
 //#endregion
 //#region src/build.ts
-/**
-* `animus build` — one-shot extraction over the SAME drive loop every
-* driver uses (`ExtractionSession`; NS1/NS4: no second composition), then
-* export of the raw payloads to the fixed-path deterministic artifact
-* contract (design D3) via the CLI writer. The one-shot session tree is
-* removed after export — no session-dir accumulation per CI run.
-*
-* Failure policy (design D5): silent-empty success is impossible —
-* system-load failure, zero discovered files, and structural emptiness are
-* fatal in EVERY mode, independent of `strict`.
-*
-* The preflight, session construction, and shared-state publication steps
-* are exported helpers: `animus watch` (watch.ts) runs the same checks and
-* the same writer path per publication instead of forking them.
-*/
-/** Thrown for failures whose exit class is "extraction failure" (1). */
 var ExtractionFailure = class extends Error {};
-/** Thrown for failures whose exit class is "config/usage error" (2). */
 var UsageFailure = class extends Error {};
-/** Thrown for failures whose exit class is "engine/environment" (3). */
 var EnvironmentFailure = class extends Error {};
-/** The CLI's one stderr prefix convention (stdout stays machine-only) —
-*  shared with watch.ts. */
 const err = (...parts) => console.error("[animus]", ...parts);
-/** Preflight shared by build and watch: root and system-module existence
-*  are usage errors (exit 2) decided before any engine work; a missing
-*  platform binary is an environment failure (exit 3) surfaced with the
-*  loader's own remediation text. */
+/** Existence checks run before the engine loads, so a misconfigured
+*  project exits 2 rather than 3. */
 async function runPreflight(config) {
 	const { root, options } = config;
 	if (!existsSync(root)) throw new UsageFailure(`Root directory not found: ${root}`);
@@ -196,14 +260,11 @@ async function runPreflight(config) {
 		throw new EnvironmentFailure(`Extraction engine failed to load: ${String(error)}`);
 	}
 }
-/** The one CLI session shape: self-ingestion guard applied (an outDir
-*  inside the root is force-excluded from discovery, loudly), driver label
-*  and root authority set, tsconfig `paths` harvested as the alias source
-*  (no live bundler config exists for this driver). */
 function createCliSession(config) {
 	const { root, outDir, options } = config;
 	const session = new ExtractionSession(options);
 	const relOut = relative(root, outDir);
+	if (relOut === "") throw new UsageFailure(`The artifact directory is the root itself (${outDir}) — the published ${STYLES_FILE}/${SYSTEM_PROPS_FILE}/${MANIFEST_FILE} would be re-ingested as source on the next run. Pass --out-dir with a subdirectory (the default is ${ANIMUS_ARTIFACT_DIR}) or point --root at the source tree.`);
 	if (!relOut.startsWith("..") && !config.excludePatterns.some((p) => relOut.includes(p) || p === relOut)) {
 		const anchored = `${relOut.split("\\").join("/")}/**`;
 		session.structuralExclude = [anchored];
@@ -211,17 +272,12 @@ function createCliSession(config) {
 	}
 	session.driverLabel = "animus";
 	session.rootDir = root;
-	const builtAliases = buildPathAliasesJson(readTsconfigAliasPairs(root), root);
+	session.staleAssetPruning = "every-cycle";
+	const aliasPairs = readTsconfigAliasPairs(root);
+	const builtAliases = buildPathAliasesJson(aliasPairs, root);
 	if (builtAliases) session.pathAliasesJson = builtAliases.json;
 	return session;
 }
-/**
-* Publish the session's shared-state payloads through the deterministic
-* CLI writer (design D3) — the SINGLE publication path for build and every
-* watch cycle. Zero analyzed files, an unreadable manifest, and structural
-* emptiness throw ExtractionFailure (silent-empty success is impossible);
-* a post-publish consistency failure throws EnvironmentFailure.
-*/
 function publishSharedPayloads(config, session) {
 	const { root, outDir, options } = config;
 	const fileCount = getAnalyzedHashes()?.size ?? 0;
@@ -231,7 +287,8 @@ function publishSharedPayloads(config, session) {
 	const systemPropsJs = getSharedSystemProps();
 	let componentCount = session.lastComponentCount ?? -1;
 	if (componentCount < 0) try {
-		componentCount = Object.keys(JSON.parse(manifestJson).components ?? {}).length;
+		const manifest = JSON.parse(manifestJson);
+		componentCount = Object.keys(manifest.components).length;
 	} catch {
 		throw new ExtractionFailure("Analysis published no readable manifest");
 	}
@@ -262,9 +319,28 @@ function publishSharedPayloads(config, session) {
 		fileCount
 	};
 }
-/** Discovery-outcome report (stderr): per-specifier accounting plus
-*  dead-pattern visibility — a user exclusion that matched nothing is
-*  named instead of silently inert. */
+/** Synchronous: the signal paths call `process.exit` next, which runs no
+*  pending microtask. The tree goes first, with the lock still held. */
+function releaseRunClaims(session, releaseLock) {
+	if (session) {
+		try {
+			rmSync(session.sessionDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		session.close();
+	}
+	releaseLock();
+}
+function createRunClaimRelease(getSession, releaseLock) {
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		releaseRunClaims(getSession(), releaseLock);
+	};
+}
 function reportDiscoveryOutcomes(config, session) {
 	for (const { specifier, outcome, fileCount: files } of session.lastExternalOutcomes) err(`include '${specifier}': ${outcome}${outcome === "resolved" ? ` (${files} files)` : ""}`);
 	const stats = session.getExcludeStats();
@@ -275,6 +351,12 @@ async function runBuild(config) {
 	await runPreflight(config);
 	const release = acquireLock(outDir);
 	let session = null;
+	const releaseClaims = createRunClaimRelease(() => session, release);
+	const removeShutdownSignals = installShutdownSignals({ release: ({ exitCode, signal }) => {
+		err(`build interrupted by ${signal} — releasing ${outDir}`);
+		releaseClaims();
+		process.exit(exitCode);
+	} });
 	try {
 		session = createCliSession(config);
 		try {
@@ -291,53 +373,106 @@ async function runBuild(config) {
 			fileCount
 		};
 	} finally {
-		release();
-		const dir = session?.sessionDir ?? getSessionArtifactDir();
-		if (dir) rmSync(dir, {
-			recursive: true,
-			force: true
-		});
+		removeShutdownSignals();
+		releaseClaims();
 	}
 }
 //#endregion
 //#region src/config.ts
-/**
-* CLI config resolution — the third driver over the shared option core
-* (shared-driver-config): documented precedence flags > config file >
-* defaults, one root authority, explicit emission mode (the CLI never
-* sniffs NODE_ENV), and a fully inspectable resolved projection for
-* `--print-config`.
-*/
-/** Config filenames probed in order under the config-search root. */
 const CONFIG_FILENAMES = [
 	"animus.config.json",
 	"animus.config.mjs",
 	"animus.config.js",
 	"animus.config.ts"
 ];
+const isConfigReference = (value) => Object(value) === value;
+const isConfigCallable = (value) => {
+	if (!isConfigReference(value)) return false;
+	try {
+		Function.prototype.toString.call(value);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const isConfigRecord = (value) => isConfigReference(value) && !Array.isArray(value) && !isConfigCallable(value);
+const acceptsConfigPrimitive = (value, read) => {
+	if (isConfigReference(value)) return false;
+	try {
+		read();
+		return true;
+	} catch {
+		return false;
+	}
+};
+const isConfigString = (value) => acceptsConfigPrimitive(value, () => String.prototype.valueOf.call(value));
+const isConfigBoolean = (value) => acceptsConfigPrimitive(value, () => Boolean.prototype.valueOf.call(value));
+const isConfigNumber = (value) => acceptsConfigPrimitive(value, () => Number.prototype.valueOf.call(value));
+const isConfigStringArray = (value) => Array.isArray(value) && value.every((entry) => isConfigString(entry));
+function isStaticCssComponentOverride(value) {
+	if (!isConfigRecord(value)) return false;
+	const variants = value.variants;
+	if (variants !== void 0 && variants !== "*" && (!isConfigRecord(variants) || Object.values(variants).some((entry) => entry !== "*" && !isConfigStringArray(entry)))) return false;
+	const states = value.states;
+	if (states !== void 0 && states !== "*" && !isConfigStringArray(states)) return false;
+	return value.dynamicProps === void 0 || isConfigStringArray(value.dynamicProps);
+}
+function isStaticCssConfig(value) {
+	if (!isConfigRecord(value)) return false;
+	if (value.components !== void 0 && (!isConfigRecord(value.components) || Object.values(value.components).some((component) => !isStaticCssComponentOverride(component)))) return false;
+	if (value.systemProps === void 0) return true;
+	if (!isConfigRecord(value.systemProps)) return false;
+	return Object.values(value.systemProps).every((values) => Array.isArray(values) && values.every((entry) => isConfigString(entry) || isConfigNumber(entry) || isConfigRecord(entry) && Object.values(entry).every((responsiveValue) => isConfigString(responsiveValue) || isConfigNumber(responsiveValue))));
+}
+function configObject(value, message) {
+	if (isConfigRecord(value)) return value;
+	throw new AnimusConfigError(message);
+}
+function configStaticCss(value) {
+	if (value === void 0) return void 0;
+	if (isStaticCssConfig(value)) return value;
+	throw new AnimusConfigError(`Invalid value for "staticCss" — expected a static CSS declaration object, got ${JSON.stringify(value)}.`);
+}
+function parseLoadedCliConfig(raw) {
+	assertNoRetiredEngineSelection(isConfigString(raw.engine) ? raw.engine : void 0);
+	assertKnownOptionKeys(raw);
+	const cliValue = raw.cli;
+	const cli = isConfigRecord(cliValue) ? cliValue : {};
+	if (cli.outDir !== void 0 && !isConfigString(cli.outDir)) throw new AnimusConfigError(`Invalid value for "cli.outDir" — expected a string path, got ${JSON.stringify(cli.outDir)}.`);
+	return {
+		core: {
+			system: isConfigString(raw.system) ? raw.system : void 0,
+			root: isConfigString(raw.root) ? raw.root : void 0,
+			exclude: isConfigStringArray(raw.exclude) ? raw.exclude : void 0,
+			extensions: isConfigStringArray(raw.extensions) ? raw.extensions : void 0,
+			strict: isConfigBoolean(raw.strict) ? raw.strict : void 0,
+			verbose: isConfigBoolean(raw.verbose) ? raw.verbose : void 0,
+			prefix: isConfigString(raw.prefix) ? raw.prefix : void 0,
+			targets: isConfigString(raw.targets) || isConfigStringArray(raw.targets) ? raw.targets : void 0,
+			minify: isConfigBoolean(raw.minify) ? raw.minify : void 0,
+			staticCss: configStaticCss(raw.staticCss),
+			layers: isConfigStringArray(raw.layers) ? raw.layers : void 0,
+			mode: raw.mode === "development" || raw.mode === "production" ? raw.mode : void 0
+		},
+		cli: { outDir: cli.outDir }
+	};
+}
 async function loadConfigFile(path) {
 	if (path.endsWith(".json")) try {
-		return JSON.parse(readFileSync(path, "utf-8"));
+		return configObject(JSON.parse(readFileSync(path, "utf-8")), `${path} must contain a config object`);
 	} catch (error) {
 		throw new AnimusConfigError(`Failed to parse ${path}: ${String(error)}`);
 	}
 	try {
-		const mod = await import(pathToFileURL(path).href);
-		const value = mod.default ?? mod;
-		if (typeof value !== "object" || value === null) throw new AnimusConfigError(`${path} must default-export a config object`);
-		return value;
+		const mod = configObject(await import(pathToFileURL(path).href), `${path} must evaluate to a module object`);
+		return configObject(mod.default ?? mod, `${path} must default-export a config object`);
 	} catch (error) {
 		if (error instanceof AnimusConfigError) throw error;
-		const code = error.code;
+		const code = isConfigRecord(error) && isConfigString(error.code) ? error.code : void 0;
 		if (path.endsWith(".ts") && code === "ERR_UNKNOWN_FILE_EXTENSION") throw new AnimusConfigError(`${path}: this Node runtime cannot evaluate TypeScript config files (native type stripping requires Node >= 23.6 unflagged; the supported floor for .ts configs). Use animus.config.mjs or animus.config.json instead.`);
 		throw new AnimusConfigError(`Failed to load config ${path}: ${String(error)}`);
 	}
 }
-/**
-* Resolve the effective CLI configuration. Precedence: flags > config file
-* > documented defaults. Scalar flags override; `--exclude` values merge
-* (exclusion semantics are merge-only by contract).
-*/
 async function resolveCliConfig(flags, cwd) {
 	const flagRoot = flags.root ? resolve(cwd, flags.root) : null;
 	let configFile = null;
@@ -351,11 +486,25 @@ async function resolveCliConfig(flags, cwd) {
 			break;
 		}
 	}
-	const raw = configFile ? await loadConfigFile(configFile) : {};
-	assertKnownOptionKeys(raw);
-	const fileRoot = raw["root"];
+	const loaded = parseLoadedCliConfig(configFile ? await loadConfigFile(configFile) : {});
+	const raw = loaded.core;
+	const fileRoot = raw.root;
 	const configDir = configFile ? dirname(configFile) : cwd;
-	const effectiveRoot = flagRoot ?? (typeof fileRoot === "string" ? resolve(configDir, fileRoot) : configFile ? configDir : cwd);
+	let rootSource;
+	let effectiveRoot;
+	if (flagRoot !== null) {
+		rootSource = "flag";
+		effectiveRoot = flagRoot;
+	} else if (fileRoot !== void 0) {
+		rootSource = "config-file";
+		effectiveRoot = resolve(configDir, fileRoot);
+	} else if (configFile) {
+		rootSource = "config-dir";
+		effectiveRoot = configDir;
+	} else {
+		rootSource = "cwd";
+		effectiveRoot = cwd;
+	}
 	const provenance = {};
 	const pick = (key, flagValue) => {
 		if (flagValue !== void 0) {
@@ -370,21 +519,21 @@ async function resolveCliConfig(flags, cwd) {
 		provenance[key] = "default";
 	};
 	const system = pick("system", flags.system);
-	if (typeof system !== "string" || system.length === 0) throw new AnimusConfigError("Missing required option `system` — pass --system ./src/ds.ts or set \"system\" in animus.config.");
-	const exclude = [...Array.isArray(raw["exclude"]) ? raw["exclude"] : [], ...flags.exclude ?? []];
-	if (exclude.length > 0) provenance["exclude"] = "explicit";
-	else provenance["exclude"] = "default";
+	if (system === void 0 || system.length === 0) throw new AnimusConfigError("Missing required option `system` — pass --system ./src/ds.ts or set \"system\" in animus.config.");
+	const fileExclude = raw.exclude;
+	const flagExclude = flags.exclude;
+	const excludeIsExplicit = fileExclude !== void 0 || flagExclude !== void 0 && flagExclude.length > 0;
+	const exclude = [...fileExclude ?? [], ...flagExclude ?? []];
+	provenance["exclude"] = excludeIsExplicit ? "explicit" : "default";
 	if (flags.mode !== void 0 && flags.mode !== "development" && flags.mode !== "production") throw new AnimusConfigError(`Invalid --mode "${flags.mode}" — expected "development" or "production".`);
-	const resolvedMode = resolveMode(flags.mode ?? raw["mode"], () => "production");
+	const resolvedMode = resolveMode(flags.mode ?? raw.mode, () => "production");
 	provenance["mode"] = resolvedMode.provenance;
-	const cliNamespace = raw["cli"] ?? {};
-	if (cliNamespace.outDir !== void 0 && typeof cliNamespace.outDir !== "string") throw new AnimusConfigError(`Invalid value for "cli.outDir" — expected a string path, got ${JSON.stringify(cliNamespace.outDir)}.`);
-	const outDirSetting = flags.outDir ?? cliNamespace.outDir ?? ".animus";
+	const outDirSetting = flags.outDir ?? loaded.cli.outDir ?? ANIMUS_ARTIFACT_DIR;
 	const outDir = isAbsolute(outDirSetting) ? outDirSetting : resolve(effectiveRoot, outDirSetting);
-	provenance["outDir"] = flags.outDir !== void 0 || cliNamespace.outDir !== void 0 ? "explicit" : "driver-default";
+	provenance["outDir"] = flags.outDir !== void 0 || loaded.cli.outDir !== void 0 ? "explicit" : "driver-default";
 	const options = {
 		system,
-		exclude: exclude.length > 0 ? exclude : void 0,
+		exclude: excludeIsExplicit ? exclude : void 0,
 		extensions: pick("extensions", void 0),
 		strict: pick("strict", flags.strict),
 		verbose: pick("verbose", flags.verbose),
@@ -399,6 +548,7 @@ async function resolveCliConfig(flags, cwd) {
 	return {
 		driver: "cli",
 		root: effectiveRoot,
+		rootSource,
 		configFile,
 		options,
 		outDir,
@@ -407,7 +557,12 @@ async function resolveCliConfig(flags, cwd) {
 		provenance
 	};
 }
-/** The `--print-config` projection: everything effective, nothing hidden. */
+/** Announced only for the root authority the invocation does not state:
+*  `--root` and a config-file `root` are the user's own words. */
+function inferredRootNotice(config, cwd) {
+	if (config.rootSource !== "config-dir" || config.root === cwd) return null;
+	return `root ${config.root} was inferred from the directory of ${config.configFile} — every relative path resolves against it, not against ${cwd}. Pass --root to choose the root yourself.`;
+}
 function projectResolvedConfig(config) {
 	return {
 		driver: config.driver,
@@ -422,58 +577,19 @@ function projectResolvedConfig(config) {
 		minify: config.options.minify ?? null,
 		prefix: config.options.prefix ?? null,
 		layers: config.options.layers ?? null,
+		extensions: config.options.extensions ?? null,
+		staticCss: config.options.staticCss ?? null,
 		exclude: config.excludePatterns,
 		provenance: config.provenance
 	};
 }
 //#endregion
 //#region src/watch.ts
-/**
-* `animus watch` — the session's watcher loop as a long-lived foreground
-* process (openspec: standalone-extraction-cli, design D5 watch half).
-*
-* Contract:
-* - Readiness is an explicit observable event distinct from idle: ONE
-*   structured stderr `watch ready` line after the first complete,
-*   consistent publication (plus the session status artifact's additive
-*   monotonic `ready` field, schema-bumped compatibly).
-* - Mid-run failures keep last-good output and report per-cycle on stderr;
-*   every publication goes through the SAME deterministic CLI writer as
-*   `animus build` (design D3) and the advisory lock is held for the
-*   watch's lifetime.
-* - Watch-capability degradation is loud and names roots: a persistent
-*   stderr warning per unwatched root at every publication, and
-*   `--fail-on-degraded` for orchestrators that would rather die (exit 3).
-* - The process stays alive on purpose: the session watcher unrefs every
-*   handle (it must never hold a plugin host's process open), so the CLI
-*   holds its own ref'd keepalive. SIGINT exits 130, SIGTERM 143, both
-*   releasing the lock and removing the session tree — a watch keeps its
-*   session tree alive WHILE RUNNING (transform consumers may exist) and
-*   removes it on clean shutdown, unlike build's publish-then-remove.
-*
-* COORDINATION: `external-source-watch-ingestion` owns watch-ingestion
-* semantics — this verb consumes `startTurbopackWatcher` and
-* `handleWatchUpdate` as-is (the per-cycle wrapper below only observes
-* cycle boundaries to drive publication policy; it forks no ingestion
-* behavior).
-*/
-/** Signal exit conventions (128 + signal number) plus the degraded-exit
-*  class: watch capability loss is an environment failure (taxonomy 3). */
-const EXIT_SIGINT = 130;
-const EXIT_SIGTERM = 143;
 const EXIT_DEGRADED = 3;
-/**
-* The degradation list for one publication — every root whose edits the
-* watch will NOT observe, with the reason. Sources:
-* - the project root itself when the platform watcher could not start
-*   (recursive fs.watch unavailable / registration failed — the session
-*   degrades to no-watch with a warning and returns no handle);
-* - external roots resolved through node_modules (documented unwatchable —
-*   the orchestrator never registers them; its own guardrail-G2 comment on
-*   `openExternalWatcher`'s early return);
-* - external roots whose watcher failed after registration (the session's
-*   sticky `external-watch:` diagnostics, which carry the reason).
-*/
+const PROJECT_WATCH_REASONS = {
+	unavailable: "platform watcher unavailable — NO source edits will be observed; restart the watch after changes",
+	"already-watched": "root already claimed by another watcher in this process — NO source edits will be observed by THIS watch; run one watch per root (restarting collides the same way)"
+};
 function collectDegradedRoots(inputs) {
 	const seen = /* @__PURE__ */ new Set();
 	const degraded = [];
@@ -485,7 +601,7 @@ function collectDegradedRoots(inputs) {
 			reason
 		});
 	};
-	if (!inputs.projectWatchActive) add(inputs.projectRoot, "platform watcher unavailable — NO source edits will be observed; restart the watch after changes");
+	if (inputs.projectWatch !== "active") add(inputs.projectRoot, PROJECT_WATCH_REASONS[inputs.projectWatch]);
 	for (const root of inputs.externalWatchRoots) if (root.split(/[\\/]/).includes("node_modules")) add(root, "resolved through node_modules (documented unwatchable) — edits in this package require a restart");
 	const stickyPrefix = "external-watch:";
 	for (const [key, message] of inputs.stickyDiagnostics) {
@@ -494,14 +610,13 @@ function collectDegradedRoots(inputs) {
 	}
 	return degraded;
 }
-/** One persistent stderr warning per unwatched root (design D5: loud,
-*  names the root and the consequence, repeated at every publication —
-*  never a one-shot). */
 function formatDegradedRootLine(entry) {
 	return `watch degraded root=${entry.root} — ${entry.reason}`;
 }
-/** Composite key of the shared payload set — the cycle-level dedupe gate
-*  (a no-op analysis republishes nothing; disk bytes stay untouched). */
+function formatCyclePublishFailure(outDir, error) {
+	if (error instanceof PublishSwapIncompleteError) return `watch cycle publication failed mid-swap — ${outDir} is NOT last-good: ${String(error)}`;
+	return `watch cycle publication rejected — keeping last-good artifacts in ${outDir}: ${String(error)}`;
+}
 function currentPayloadKey() {
 	return [
 		contentHash(getManifestJson() ?? ""),
@@ -509,76 +624,90 @@ function currentPayloadKey() {
 		contentHash(getSharedSystemProps())
 	].join(":");
 }
-/**
-* Run the watch loop. Resolves with the process exit code on shutdown
-* (130 SIGINT / 143 SIGTERM / 3 --fail-on-degraded trip). Startup
-* failures — preflight, first pipeline, first publication — THROW with
-* the same taxonomy as build: readiness is a contract (NS3), so a
-* supervisor either observes the ready event or observes a nonzero exit,
-* never a silent hang with no first publication.
-*/
+/** Resolves with the process exit code at shutdown. Startup failures throw,
+*  so a supervisor sees either `watch ready` or a nonzero exit, never a hang. */
 async function runWatch(config, flags) {
 	const { outDir, root } = config;
 	await runPreflight(config);
 	const release = acquireLock(outDir);
-	let session;
-	let firstPublication;
+	let constructed = null;
+	const releaseClaims = createRunClaimRelease(() => constructed, release);
+	let watcher = null;
+	let startup;
 	try {
-		session = createCliSession(config);
+		const created = createCliSession(config);
+		constructed = created;
+		const claim = startTurbopackWatcher(created, root, { holdEvents: true });
+		if (claim.kind === "started") watcher = claim.handle;
 		try {
-			await session.runFullPipeline();
+			await created.runFullPipeline();
 		} catch (error) {
 			throw new ExtractionFailure(String(error));
 		}
-		firstPublication = publishSharedPayloads(config, session);
-		reportDiscoveryOutcomes(config, session);
+		const publication = publishSharedPayloads(config, created);
+		reportDiscoveryOutcomes(config, created);
+		startup = {
+			session: created,
+			claim,
+			publication
+		};
 	} catch (error) {
-		release();
-		const dir = session?.sessionDir ?? getSessionArtifactDir();
-		if (dir) rmSync(dir, {
-			recursive: true,
-			force: true
-		});
+		watcher?.close();
+		releaseClaims();
 		throw error;
 	}
+	const { session, claim } = startup;
+	let lastPublication = startup.publication;
 	let publications = 1;
 	let lastPublishedKey = currentPayloadKey();
 	return new Promise((resolvePromise) => {
-		let settled = false;
-		let watcher = null;
 		const keepalive = setInterval(() => {}, 2 ** 30);
-		const shutdown = (code, reason) => {
-			if (settled) return;
-			settled = true;
-			process.removeListener("SIGINT", onSigint);
-			process.removeListener("SIGTERM", onSigterm);
+		let shuttingDown = null;
+		let finished = false;
+		const reportShutdown = (reason, drain) => {
+			err(`watch shutdown reason=${reason} publications=${publications}` + (drain === void 0 ? "" : ` drain=${drain}`));
+		};
+		const finish = (code, reason, drain) => {
+			if (finished) return;
+			finished = true;
+			releaseClaims();
+			removeShutdownSignals();
+			clearInterval(keepalive);
+			reportShutdown(reason, drain);
+			resolvePromise(code);
+		};
+		const drainThenFinish = async (code, reason) => {
 			watcher?.close();
-			(async () => {
-				try {
-					await Promise.race([watcher?.settle() ?? Promise.resolve(), new Promise((res) => setTimeout(res, 1e4).unref?.())]);
-				} catch {}
-				try {
-					rmSync(session.sessionDir, {
-						recursive: true,
-						force: true
-					});
-				} catch {}
-				release();
-				clearInterval(keepalive);
-				err(`watch shutdown reason=${reason} publications=${publications}`);
-				resolvePromise(code);
-			})();
+			err(`watch shutdown starting reason=${reason} — draining the in-flight cycle before releasing ${outDir} (signal again to exit at once)`);
+			let bound = null;
+			try {
+				await Promise.race([watcher?.settle() ?? Promise.resolve(), new Promise((res) => {
+					bound = setTimeout(res, 1e4);
+					bound.unref?.();
+				})]);
+			} catch {} finally {
+				if (bound !== null) clearTimeout(bound);
+			}
+			finish(code, reason);
 		};
-		const onSigint = () => shutdown(EXIT_SIGINT, "SIGINT");
-		const onSigterm = () => shutdown(EXIT_SIGTERM, "SIGTERM");
-		process.on("SIGINT", onSigint);
-		process.on("SIGTERM", onSigterm);
-		/** Print the per-publication degradation warnings. Returns true when
-		*  --fail-on-degraded tripped (shutdown already initiated). */
+		const shutdown = (code, reason) => {
+			if (shuttingDown !== null) return shuttingDown;
+			shuttingDown = drainThenFinish(code, reason);
+			return shuttingDown;
+		};
+		const removeShutdownSignals = installShutdownSignals({
+			drain: shutdown,
+			release: ({ exitCode, signal, abandoned }) => {
+				if (!abandoned) return;
+				err(`watch ${signal} during shutdown — abandoning the drain and releasing ${outDir}`);
+				finish(exitCode, signal, "abandoned");
+			}
+		});
+		/** True when --fail-on-degraded tripped and shutdown has begun. */
 		const reportDegradation = () => {
 			const degraded = collectDegradedRoots({
 				projectRoot: root,
-				projectWatchActive: watcher !== null && !watcher.died,
+				projectWatch: claim.kind === "already-watched" ? "already-watched" : watcher !== null && !watcher.died ? "active" : "unavailable",
 				externalWatchRoots: session.externalWatchRoots,
 				stickyDiagnostics: session.stickyDiagnostics
 			});
@@ -590,60 +719,51 @@ async function runWatch(config, flags) {
 			}
 			return false;
 		};
-		const baseHandleWatchUpdate = session.handleWatchUpdate.bind(session);
-		session.handleWatchUpdate = async (changes) => {
-			if (settled) return;
-			try {
-				await baseHandleWatchUpdate(changes);
-			} catch (error) {
-				if (settled) return;
-				err(`watch cycle failed — keeping last-good artifacts in ${outDir}: ${String(error)}`);
+		session.onCycleSettled = (cause) => {
+			if (shuttingDown !== null) return;
+			if (cause !== null) {
+				err(`watch cycle failed — keeping last-good artifacts in ${outDir}: ${String(cause)}`);
 				return;
 			}
-			if (settled) return;
 			const key = currentPayloadKey();
 			if (key === lastPublishedKey) return;
 			let outcome;
 			try {
 				outcome = publishSharedPayloads(config, session);
 			} catch (error) {
-				err(`watch cycle publication rejected — keeping last-good artifacts in ${outDir}: ${String(error)}`);
+				err(formatCyclePublishFailure(outDir, error));
 				return;
 			}
 			lastPublishedKey = key;
+			lastPublication = outcome;
 			publications += 1;
 			err(`watch republished components=${outcome.componentCount} files=${outcome.fileCount} outDir=${outDir}`);
 			reportDegradation();
 		};
-		watcher = startTurbopackWatcher(session, root);
 		if (watcher) watcher.onDied = () => {
-			if (!settled) reportDegradation();
+			if (shuttingDown === null) reportDegradation();
 		};
-		if (reportDegradation()) return;
-		err(`watch ready components=${firstPublication.componentCount} files=${firstPublication.fileCount} outDir=${outDir}`);
+		(async () => {
+			try {
+				await watcher?.deliverHeldEvents();
+			} catch {}
+			if (shuttingDown !== null) return;
+			if (reportDegradation()) return;
+			err(`watch ready components=${lastPublication.componentCount} files=${lastPublication.fileCount} outDir=${outDir}`);
+		})();
 	});
 }
 //#endregion
 //#region src/index.ts
-/**
-* `animus` — the standalone extraction CLI (openspec:
-* standalone-extraction-cli).
-*
-* Contract (design D5): stdout carries machine output ONLY (today: the
-* `--print-config` JSON projection); every human-facing line goes to
-* stderr. Exit taxonomy: 0 success · 1 extraction/strict failure · 2
-* config/usage error · 3 engine/environment failure.
-*
-* UNSTABLE MODULE SURFACE: the package's programmatic exports (`main`,
-* `exitCodeFor`, the EXIT_* constants) exist for the repo's own lanes and
-* tests; the supported consumer surface is the `animus` binary. The module
-* API may change without semver ceremony until a consumer contract ships
-* (standalone-extraction-cli inc 07).
-*/
+/** The supported consumer surface is the `animus` binary; the programmatic
+*  exports may change without semver ceremony. */
 const EXIT_OK = 0;
 const EXIT_EXTRACTION = 1;
 const EXIT_USAGE = 2;
 const EXIT_ENVIRONMENT = 3;
+/** Nothing in this module returns it: `bin/animus.mjs` decides the install
+*  failure class, since this module is the one that did not load. */
+const EXIT_INSTALL = 4;
 const USAGE = `animus — standalone Animus extraction
 
 Usage:
@@ -657,27 +777,36 @@ Options:
   --root <path>       Root every relative input resolves against
   --config <path>     Explicit config file (default: animus.config.* in root)
   --out-dir <path>    Artifact directory (default: <root>/.animus)
-  --exclude <glob>    Additional exclusion (repeatable; MERGES with defaults)
+  --exclude <glob>    Additional exclusion (repeatable; MERGES with defaults;
+                      an explicit exclude: [] in the config file means none)
   --mode <m>          'development' | 'production' (default: production)
   --targets <query>   Browserslist query for CSS lowering
-  --strict            Escalate extraction warnings to failures
+  --strict            Fail on inputs that could not be read or resolved
   --fail-on-degraded  watch only: exit 3 instead of running with unwatched
                       roots (degradation is otherwise reported and tolerated)
   --verbose           Verbose logging (stderr)
   --print-config      Alias of the print-config command
   --help              This text
 
-Exit codes: 0 success · 1 extraction failure · 2 config error · 3 engine failure
-Watch shutdown: SIGINT exits 130, SIGTERM 143 (lock released, last-good kept)
+Exit codes: 0 success · 1 extraction failure · 2 config error · 3 engine
+failure · 4 the animus install could not be loaded
+Shutdown signals: SIGINT exits 130, SIGTERM 143 (lock released, last-good kept)
 `;
-/** Classify an error into the documented exit taxonomy. ExtractionFailure
-*  and unclassified errors deliberately share the extraction exit class —
-*  an unknown throw during a build IS a failed extraction to a supervisor. */
+function readThrownMessage(error) {
+	return error.message;
+}
+/** Unclassified throws share the extraction class: an unknown throw during
+*  a build is a failed extraction to a supervisor. */
 function exitCodeFor(error) {
 	if (error instanceof UsageFailure || error instanceof AnimusConfigError) return 2;
 	if (error instanceof EnvironmentFailure) return 3;
 	return 1;
 }
+function reportUsageError(reason) {
+	console.error(`[animus] ${reason}`);
+	console.error(USAGE);
+	process.exitCode = 2;
+}
 async function main(argv = process.argv.slice(2)) {
 	let parsed;
 	try {
@@ -703,9 +832,7 @@ async function main(argv = process.argv.slice(2)) {
 			}
 		});
 	} catch (error) {
-		console.error(`[animus] ${String(error.message)}`);
-		console.error(USAGE);
-		process.exitCode = 2;
+		reportUsageError(String(readThrownMessage(error)));
 		return;
 	}
 	const { values, positionals } = parsed;
@@ -715,6 +842,14 @@ async function main(argv = process.argv.slice(2)) {
 		return;
 	}
 	const command = positionals[0];
+	if (positionals.length > 1) {
+		reportUsageError(`Unexpected argument '${positionals[1]}' — one command per invocation`);
+		return;
+	}
+	if (command !== "build" && command !== "watch" && command !== "print-config") {
+		reportUsageError(`Unknown command '${command}'`);
+		return;
+	}
 	const flags = {
 		system: values.system,
 		root: values.root,
@@ -726,8 +861,11 @@ async function main(argv = process.argv.slice(2)) {
 		targets: values.targets,
 		exclude: values.exclude
 	};
+	const cwd = process.cwd();
 	try {
-		const config = await resolveCliConfig(flags, process.cwd());
+		const config = await resolveCliConfig(flags, cwd);
+		const rootNotice = inferredRootNotice(config, cwd);
+		if (rootNotice !== null) err(rootNotice);
 		if (command === "print-config" || values["print-config"]) {
 			console.log(JSON.stringify(projectResolvedConfig(config), null, 2));
 			process.exitCode = 0;
@@ -738,17 +876,11 @@ async function main(argv = process.argv.slice(2)) {
 			process.exitCode = 0;
 			return;
 		}
-		if (command === "watch") {
-			process.exitCode = await runWatch(config, { failOnDegraded: values["fail-on-degraded"] === true });
-			return;
-		}
-		console.error(`[animus] Unknown command '${command}'`);
-		console.error(USAGE);
-		process.exitCode = 2;
+		process.exitCode = await runWatch(config, { failOnDegraded: values["fail-on-degraded"] === true });
 	} catch (error) {
-		console.error(`[animus] ${String(error.message ?? error)}`);
+		console.error(`[animus] ${String(readThrownMessage(error) ?? error)}`);
 		process.exitCode = exitCodeFor(error);
 	}
 }
 //#endregion
-export { EXIT_ENVIRONMENT, EXIT_EXTRACTION, EXIT_OK, EXIT_USAGE, exitCodeFor, main };
+export { EXIT_ENVIRONMENT, EXIT_EXTRACTION, EXIT_INSTALL, EXIT_OK, EXIT_USAGE, exitCodeFor, main };