heximon 0.9.0 → 0.10.0

package/dist/bin.mjs

@@ -1,21 +1,27 @@
 #!/usr/bin/env node
-import { c as RegistryAccess, d as ClackPrompter, f as PromptCancelledError, l as RegistryAccessStatus, n as CreateDefaults, r as createCommand, t as skillsCommand, u as CliEnvironment } from "./skills-command-W72zUEYD.mjs";
+import { _ as StdoutRedirect, d as RegistryAccessStatus, f as CommandOutput, g as CliEntry, i as createCommand, m as PromptRefusedError, n as ProjectRoot, p as CommandFailure, r as CreateDefaults, t as skillsCommand, u as RegistryAccess, v as CliDiagnosticCode, x as PromptCancelledError, y as CliDiagnostics } from "./skills-command-Czsv_c74.mjs";
 import { createRequire, register } from "node:module";
 import { cancel, confirm, intro, isCancel, log, outro, select, spinner } from "@clack/prompts";
 import process from "node:process";
+import { defineCommand } from "citty";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { AstNodeType, CompileEnvironment, CompileMode, DeployPlatform, DiagnosticCode, DiagnosticRenderMode, DiagnosticRenderer, DiagnosticSeverity, ImportKind, ReexportIndex, RuntimeConfigFile, RuntimeSingletons, TerminalStyle, UpgradeBaselineFile } from "@heximon/compiler";
 import { spawn } from "node:child_process";
-import { defineCommand, runMain } from "citty";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "pathe";
 import tab from "@bomb.sh/tab/citty";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { AstNodeType, CompileEnvironment, CompileMode, DeployPlatform, DiagnosticCode, DiagnosticRenderMode, DiagnosticRenderer, DiagnosticSeverity, ImportKind, ReexportIndex, RuntimeConfigFile, RuntimeSingletons, TerminalStyle, UpgradeBaselineFile } from "@heximon/compiler";
 import { ConfigLoader, LibraryEmitter, LibraryFactoryPreflight, LibraryFreshness, ProjectCompiler, RuntimeConfigLoader, SourceModuleResolution, SourceParser, WorkspaceTopologyReader } from "@heximon/compiler/project";
 import { NodeCompileSeam } from "@heximon/node/compiler";
 import { TransactionCensus, TransactionCensusPolicy } from "@heximon/cqrs/compiler";
-import { BoundaryProvenanceAuditor, BoundaryProvenanceStatus, CredentialSelection, DatabaseConfigDetector, DeployDiagnosticSeverity, DeployLedger, DeployManifestStore, DeployRunner, DeployStrategyUnavailableError, DeployTargetResolver, DeployableServiceReader, DotenvCascade, DrizzleKitRunner, EnvFileReader, EnvFileUnreadableError, HostManagedDeployUnsupportedError, ImportScanner, MigrationInspector, MigrationTargetComposer, PackageCopyAuditor, PeerClosureAuditor, PlatformTracingAuditor, PlatformTracingStatus, WorkspaceConsumerLocator } from "@heximon/deploy";
+import { BoundaryProvenanceAuditor, BoundaryProvenanceStatus, CredentialSelection, DatabaseConfigDetector, DeployDiagnosticSeverity, DeployLedger, DeployManifestStore, DeployRunner, DeployStrategyUnavailableError, DeployTargetResolver, DeployableServiceReader, DotenvCascade, DrizzleKitRunner, EnvFileReader, EnvFileUnreadableError, HostManagedDeployUnsupportedError, ImportScanner, MigrationInspector, MigrationTargetComposer, PackageCopyAuditor, PeerClosureAuditor, PlatformTracingAuditor, PlatformTracingStatus, SecretMask, WorkspaceConsumerLocator } from "@heximon/deploy";
 import { RouteCensus, RouteScopeGap } from "@heximon/http/compiler";
 import { pathToFileURL } from "node:url";
 import { homedir } from "node:os";
+//#region src/check-json-document.ts
+/** The stable codes of the failures `heximon check` raises itself, beside the compiler's own. */
+const CheckDiagnosticCode = { 
+/** A consumed workspace library changed since its last `vp pack`, so the compile read an old manifest. */
+StaleLibrary: "check.stale-library" };
+//#endregion
 //#region src/compile-diagnostics.ts
 /**
 * Renders compile diagnostics to stderr with the same codeframe layout the dev server shows — a box-drawing
@@ -63,29 +69,19 @@ var CompileModeResolver = class {
 		}
 	};
 	/**
-	* Resolve one command's compile mode.
+	* Resolve one command's compile mode, or throw the refusal.
 	*
-	* @param commandName - The verb, for the refusal messages (`routes`, `graph`, `check`).
 	* @param rootDir - The absolute project root the shape is detected from.
 	* @param args - The parsed `--library` / `--app` flags.
 	* @param sourceDirectories - The resolved `--src` directories, checked against the library single-root rule.
-	* @returns The resolved mode, or `undefined` when the command must stop — the reason is already on stderr
-	*   and `process.exitCode` is set.
+	* @returns The resolved mode.
+	* @throws CommandFailure with {@link CliDiagnosticCode.InvalidOptions} when no mode can honour the flags.
 	*/
-	static resolve(commandName, rootDir, args, sourceDirectories) {
-		if (args.library === true && args.app === true) {
-			process.stderr.write(`heximon ${commandName}: --library and --app are mutually exclusive — pass at most one.\n`);
-			process.exitCode = 1;
-			return;
-		}
+	static resolve(rootDir, args, sourceDirectories) {
+		if (args.library === true && args.app === true) throw CommandFailure.of(CliDiagnosticCode.InvalidOptions, "--library and --app are mutually exclusive — pass at most one.");
 		const forcedMode = args.library === true ? CompileMode.Library : args.app === true ? CompileMode.App : void 0;
 		const mode = forcedMode ?? (LibraryEmitter.isLibraryPackage(rootDir) ? CompileMode.Library : CompileMode.App);
-		if (mode === CompileMode.Library && (sourceDirectories?.length ?? 0) > 1) {
-			process.stderr.write(`heximon ${commandName}: a library compile reads a single source directory, so it cannot honour a multi-directory --src. Pass one directory, or --app to read this project as an application.
-`);
-			process.exitCode = 1;
-			return;
-		}
+		if (mode === CompileMode.Library && (sourceDirectories?.length ?? 0) > 1) throw CommandFailure.of(CliDiagnosticCode.InvalidOptions, "a library compile reads a single source directory, so it cannot honour a multi-directory --src. Pass one directory, or --app to read this project as an application.");
 		return {
 			mode,
 			forced: forcedMode !== void 0
@@ -97,6 +93,65 @@ var CompileModeResolver = class {
 	}
 };
 //#endregion
+//#region src/config-sidecar.ts
+/**
+* Loads the `heximon.config.ts` sidecar for a command. A sidecar that throws is the same failure in every
+* command: one {@link CliDiagnosticCode.ConfigUnreadable} diagnostic whose `file` is the sidecar.
+*/
+var ConfigSidecar = class ConfigSidecar {
+	/** The fix hint of every config failure. */
+	static hint = "Fix the error in the config file, then run the command again.";
+	/**
+	* Load the sidecar.
+	*
+	* @param rootDir - The absolute project root.
+	* @param environment - The `$env` name to resolve; `NODE_ENV` when omitted.
+	* @returns The resolved config, or `undefined` when the project has no sidecar.
+	* @throws CommandFailure with {@link CliDiagnosticCode.ConfigUnreadable} when the sidecar throws.
+	*/
+	static async load(rootDir, environment) {
+		try {
+			return await ConfigLoader.load(rootDir, environment);
+		} catch (error) {
+			throw new CommandFailure([await ConfigSidecar.diagnosticOf(rootDir, error, DiagnosticSeverity.Error)]);
+		}
+	}
+	/**
+	* Run work that loads the sidecar inside another library (a deploy target, a Nitro host). When the work
+	* throws, the sidecar is loaded again: if it throws too, the shared failure replaces the error.
+	*
+	* @param rootDir - The absolute project root.
+	* @param environment - The `$env` name the work resolves.
+	* @param work - The work.
+	* @returns What the work returned.
+	*/
+	static async during(rootDir, environment, work) {
+		try {
+			return await work();
+		} catch (error) {
+			if (!(error instanceof CommandFailure)) await ConfigSidecar.load(rootDir, environment);
+			throw error;
+		}
+	}
+	/**
+	* The diagnostic of a sidecar that threw.
+	*
+	* @param rootDir - The absolute project root.
+	* @param error - What the load threw.
+	* @param severity - `error` when the command stops; `warning` when it goes on without the config.
+	* @param consequence - What the command does without the config, added to the message.
+	* @returns The diagnostic, with `file` set when the sidecar file is found.
+	*/
+	static async diagnosticOf(rootDir, error, severity, consequence) {
+		const file = await ConfigLoader.resolveFile(rootDir);
+		const reason = error instanceof Error ? error.message : String(error);
+		return CliDiagnostics.of(severity, CliDiagnosticCode.ConfigUnreadable, `heximon.config.ts could not be loaded${consequence === void 0 ? "" : `, ${consequence}`}: ${reason}`, {
+			hint: ConfigSidecar.hint,
+			...file === void 0 ? {} : { file }
+		});
+	}
+};
+//#endregion
 //#region src/project-compile-session.ts
 /**
 * The from-disk compile prologue every inspection command shares (`check`, `graph`, `routes`, `workflows`):
@@ -144,9 +199,10 @@ var ProjectCompileSession = class ProjectCompileSession {
 	*
 	* @param options - The project root, the `$env` name, and the resolved source directories.
 	* @returns The session the caller compiles through.
+	* @throws CommandFailure with `cli.config-unreadable` when the sidecar throws.
 	*/
 	static async open(options) {
-		const config = await ConfigLoader.load(options.rootDir, options.environment);
+		const config = await ConfigSidecar.load(options.rootDir, options.environment);
 		const strategy = NodeCompileSeam.resolveStrategy(config?.platform);
 		return new ProjectCompileSession({
 			rootDir: options.rootDir,
@@ -519,9 +575,10 @@ const checkCommand = defineCommand({
 			description: "Project root directory.",
 			default: "."
 		},
+		json: CommandOutput.jsonFlag,
 		format: {
 			type: "string",
-			description: "Output format: 'pretty' (default) or 'json'.",
+			description: "Output format: 'pretty' (default) or 'json' (the same as --json).",
 			default: "pretty"
 		},
 		strict: {
@@ -557,120 +614,123 @@ const checkCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const rootDir = resolve(process.cwd(), args.cwd);
-		const asJson = args.format === "json";
-		const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
-		const resolved = CompileModeResolver.resolve("check", rootDir, args, sourceDirectories);
-		if (resolved === void 0) return;
-		const { mode } = resolved;
-		const verifyBaseline = args["verify-baseline"] === true;
-		if (verifyBaseline && args.update === true) {
-			process.stderr.write("heximon check: --verify-baseline reports what the committed baseline has not acknowledged, and --update acknowledges everything — pass one or the other.\n");
-			process.exitCode = 1;
-			return;
-		}
-		if (!asJson) intro(`heximon check — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
-		const session = await ProjectCompileSession.open({
-			rootDir,
-			environment: args.env,
-			...sourceDirectories === void 0 ? {} : { sourceDirectories }
-		});
-		let checked;
-		if (mode === CompileMode.Library) {
-			const emitted = session.compileLibrary({ pruneVerdicts: true });
-			const staleLibraries = await session.staleLibraryDiagnostics();
-			checked = staleLibraries.length > 0 ? {
-				diagnostics: staleLibraries,
-				files: [],
-				...emitted.prunedVerdicts === void 0 ? {} : { prunedVerdicts: emitted.prunedVerdicts }
-			} : {
-				diagnostics: emitted.diagnostics,
-				files: emitted.files,
-				...emitted.prunedVerdicts === void 0 ? {} : { prunedVerdicts: emitted.prunedVerdicts }
-			};
-		} else {
-			const output = session.compile(true, { verifyBaseline });
-			const staleLibraries = await session.staleLibraryDiagnostics();
-			if (staleLibraries.length > 0) checked = {
-				diagnostics: staleLibraries,
-				files: []
-			};
-			else {
-				session.compiler.writeTypeVerdicts(output);
-				session.compiler.healTsconfigInclude(session.typeVerdictTarget());
-				const emitted = args.emit || session.config?.debug === true;
-				if (emitted) {
-					session.compiler.write(session.outputDirectory, output.files);
-					await session.compiler.formatOnDisk(rootDir, session.outputDirectory, output.files);
-				}
-				checked = {
-					diagnostics: output.diagnostics,
-					files: output.files,
-					...emitted ? { emittedTo: session.outputDirectory } : {}
-				};
-			}
-		}
-		const blockingErrors = checked.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error && diagnostic.escalatedFrom === void 0 && !UpgradeBaseline.isBreaking(diagnostic.code)).length;
-		const rebaselined = mode === CompileMode.App && args.update && blockingErrors === 0 ? UpgradeBaseline.update(rootDir, checked.files) : void 0;
-		if (rebaselined?.changed === true && checked.diagnostics.some((diagnostic) => UpgradeBaseline.isBreaking(diagnostic.code))) session.compiler.writeTypeVerdicts(session.compile(true, { verifyBaseline }));
-		const diagnostics = rebaselined !== void 0 ? checked.diagnostics.filter((diagnostic) => !UpgradeBaseline.isBreaking(diagnostic.code)) : checked.diagnostics;
-		const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error).length;
-		const warningCount = diagnostics.length - errorCount;
-		const failed = errorCount > 0 || args.strict && warningCount > 0;
-		if (asJson) {
-			const census = TransactionCensusReport.read(checked.files);
-			process.stdout.write(`${JSON.stringify({
-				ok: !failed,
-				mode,
-				errors: errorCount,
-				warnings: warningCount,
-				diagnostics,
-				...census === void 0 ? {} : { transactionCensus: census },
-				...checked.prunedVerdicts === void 0 ? {} : { prunedVerdicts: checked.prunedVerdicts },
-				...checked.emittedTo === void 0 ? {} : { emittedTo: checked.emittedTo },
-				...args.update === true ? { upgradeBaseline: rebaselined === void 0 ? {
-					written: false,
-					blockingErrors
+		const commandOutput = CommandOutput.resolve("check", args);
+		await commandOutput.run(async () => {
+			const rootDir = ProjectRoot.resolve(args.cwd);
+			const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
+			const resolved = CompileModeResolver.resolve(rootDir, args, sourceDirectories);
+			const { mode } = resolved;
+			const verifyBaseline = args["verify-baseline"] === true;
+			if (verifyBaseline && args.update === true) throw CommandFailure.of(CliDiagnosticCode.InvalidOptions, "--verify-baseline reports what the committed baseline has not acknowledged, and --update acknowledges everything — pass one or the other.");
+			if (!commandOutput.isJson()) intro(`heximon check — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
+			const session = await ProjectCompileSession.open({
+				rootDir,
+				environment: args.env,
+				...sourceDirectories === void 0 ? {} : { sourceDirectories }
+			});
+			let checked;
+			if (mode === CompileMode.Library) {
+				const emitted = session.compileLibrary({ pruneVerdicts: true });
+				const staleLibraries = await session.staleLibraryDiagnostics();
+				checked = staleLibraries.length > 0 ? {
+					diagnostics: staleLibraries,
+					files: [],
+					staleLibraries: true,
+					...emitted.prunedVerdicts === void 0 ? {} : { prunedVerdicts: emitted.prunedVerdicts }
 				} : {
-					written: true,
-					changed: rebaselined.changed,
-					path: rebaselined.target
-				} } : {}
-			})}\n`);
-		} else {
-			if (checked.emittedTo !== void 0) log.info(`Wrote the generated wiring to ${checked.emittedTo}`);
-			if (checked.prunedVerdicts !== void 0) log.info(`Removed the stale DI verdict mirror ${checked.prunedVerdicts} — it was written by an app-mode compile of this package, and a library compile emits none to replace it.`);
-			if (mode === CompileMode.Library && (args.emit === true || session.config?.debug === true)) log.warn(`${args.emit === true ? "`--emit`" : "`debug: true`"} writes app wiring only. A library's generated factory is written by \`vp pack\`.`);
-			if (mode === CompileMode.Library && verifyBaseline) log.warn(`${UpgradeBaselineFile.fileName} is an app-level artifact — a library's durable surface is verified by each app that composes it, so there is nothing here to verify.`);
-			if (mode === CompileMode.Library && args.update === true) log.warn(`${UpgradeBaselineFile.fileName} is an app-level artifact — a library's durable surface is baselined by each app that composes it, so there is nothing here to update.`);
-			else if (rebaselined !== void 0) log.success(rebaselined.changed ? `Updated ${UpgradeBaselineFile.fileName} — commit it to acknowledge the durable-surface changes.` : `${UpgradeBaselineFile.fileName} already up to date.`);
-			else if (args.update === true && blockingErrors > 0) log.warn(`${UpgradeBaselineFile.fileName} NOT updated — this compile has ${blockingErrors} unrelated error${blockingErrors === 1 ? "" : "s"}, so its durable surface is only partly analyzed and baselining it would acknowledge less than the app really has. Fix those first, then re-run.`);
-			else if (args.update === true) log.info("Nothing durable to baseline — no workflows, queue channels or other durable surface found.");
-			const census = TransactionCensusReport.read(checked.files);
-			const censusSummary = census === void 0 ? void 0 : TransactionCensusReport.summarize(census);
-			if (census !== void 0 && censusSummary !== void 0) {
-				const sections = [censusSummary];
-				const composed = TransactionCensusReport.composedWraps(census);
-				const unwrapped = TransactionCensusReport.unwrapped(census);
-				if (composed.length > 0) sections.push(`Composed, wrapped on the database the package handed over:\n${composed.map((line) => `  ${line}`).join("\n")}`);
-				if (unwrapped.length > 0) sections.push(`Not wrapped:\n${unwrapped.map((line) => `  ${line}`).join("\n")}`);
-				log.info(sections.join("\n"));
+					diagnostics: emitted.diagnostics,
+					files: emitted.files,
+					...emitted.prunedVerdicts === void 0 ? {} : { prunedVerdicts: emitted.prunedVerdicts }
+				};
+			} else {
+				const output = session.compile(true, { verifyBaseline });
+				const staleLibraries = await session.staleLibraryDiagnostics();
+				if (staleLibraries.length > 0) checked = {
+					diagnostics: staleLibraries,
+					files: [],
+					staleLibraries: true
+				};
+				else {
+					session.compiler.writeTypeVerdicts(output);
+					session.compiler.healTsconfigInclude(session.typeVerdictTarget());
+					const emitted = args.emit || session.config?.debug === true;
+					if (emitted) {
+						session.compiler.write(session.outputDirectory, output.files);
+						await session.compiler.formatOnDisk(rootDir, session.outputDirectory, output.files);
+					}
+					checked = {
+						diagnostics: output.diagnostics,
+						files: output.files,
+						...emitted ? { emittedTo: session.outputDirectory } : {}
+					};
+				}
 			}
-			if (mode === CompileMode.App && UpgradeBaseline.hasDurableSurface(checked.files) && !existsSync(join(rootDir, UpgradeBaselineFile.fileName))) log.info(`Durable surface found but no committed ${UpgradeBaselineFile.fileName} — run \`heximon check --update\` once and commit it to arm the upgrade-safety gate.`);
-			if (diagnostics.length > 0) CompileDiagnostics.renderToStderr(rootDir, diagnostics);
-			if (failed) {
-				const parts = [`${errorCount} error${errorCount === 1 ? "" : "s"}`];
-				if (warningCount > 0) parts.push(`${warningCount} warning${warningCount === 1 ? "" : "s"}`);
-				outro(`Check failed — ${parts.join(", ")}.`);
+			const blockingErrors = checked.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error && diagnostic.escalatedFrom === void 0 && !UpgradeBaseline.isBreaking(diagnostic.code)).length;
+			const rebaselined = mode === CompileMode.App && args.update && blockingErrors === 0 ? UpgradeBaseline.update(rootDir, checked.files) : void 0;
+			if (rebaselined?.changed === true && checked.diagnostics.some((diagnostic) => UpgradeBaseline.isBreaking(diagnostic.code))) session.compiler.writeTypeVerdicts(session.compile(true, { verifyBaseline }));
+			const diagnostics = rebaselined !== void 0 ? checked.diagnostics.filter((diagnostic) => !UpgradeBaseline.isBreaking(diagnostic.code)) : checked.diagnostics;
+			const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error).length;
+			const warningCount = diagnostics.length - errorCount;
+			const failed = errorCount > 0 || args.strict && warningCount > 0;
+			if (commandOutput.isJson()) {
+				const census = TransactionCensusReport.read(checked.files);
+				const document = {
+					ok: !failed,
+					mode,
+					errors: errorCount,
+					warnings: warningCount,
+					diagnostics: CliDiagnostics.fromCompiler(diagnostics).map((diagnostic) => checked.staleLibraries === true ? {
+						...diagnostic,
+						code: CheckDiagnosticCode.StaleLibrary
+					} : diagnostic),
+					...census === void 0 ? {} : { transactionCensus: census },
+					...checked.prunedVerdicts === void 0 ? {} : { prunedVerdicts: checked.prunedVerdicts },
+					...checked.emittedTo === void 0 ? {} : { emittedTo: checked.emittedTo },
+					...args.update === true ? { upgradeBaseline: rebaselined === void 0 ? {
+						written: false,
+						blockingErrors
+					} : {
+						written: true,
+						changed: rebaselined.changed,
+						path: rebaselined.target
+					} } : {}
+				};
+				commandOutput.emit(document);
 			} else {
-				const closing = mode === CompileMode.Library ? "Library compiled." : "Verdicts refreshed.";
-				if (warningCount > 0) {
-					log.warn(`${warningCount} warning${warningCount === 1 ? "" : "s"} — not failing (pass --strict to fail on warnings too).`);
-					outro(closing);
-				} else outro(`No issues — ${closing.toLowerCase()}`);
+				if (checked.emittedTo !== void 0) log.info(`Wrote the generated wiring to ${checked.emittedTo}`);
+				if (checked.prunedVerdicts !== void 0) log.info(`Removed the stale DI verdict mirror ${checked.prunedVerdicts} — it was written by an app-mode compile of this package, and a library compile emits none to replace it.`);
+				if (mode === CompileMode.Library && (args.emit === true || session.config?.debug === true)) log.warn(`${args.emit === true ? "`--emit`" : "`debug: true`"} writes app wiring only. A library's generated factory is written by \`vp pack\`.`);
+				if (mode === CompileMode.Library && verifyBaseline) log.warn(`${UpgradeBaselineFile.fileName} is an app-level artifact — a library's durable surface is verified by each app that composes it, so there is nothing here to verify.`);
+				if (mode === CompileMode.Library && args.update === true) log.warn(`${UpgradeBaselineFile.fileName} is an app-level artifact — a library's durable surface is baselined by each app that composes it, so there is nothing here to update.`);
+				else if (rebaselined !== void 0) log.success(rebaselined.changed ? `Updated ${UpgradeBaselineFile.fileName} — commit it to acknowledge the durable-surface changes.` : `${UpgradeBaselineFile.fileName} already up to date.`);
+				else if (args.update === true && blockingErrors > 0) log.warn(`${UpgradeBaselineFile.fileName} NOT updated — this compile has ${blockingErrors} unrelated error${blockingErrors === 1 ? "" : "s"}, so its durable surface is only partly analyzed and baselining it would acknowledge less than the app really has. Fix those first, then re-run.`);
+				else if (args.update === true) log.info("Nothing durable to baseline — no workflows, queue channels or other durable surface found.");
+				const census = TransactionCensusReport.read(checked.files);
+				const censusSummary = census === void 0 ? void 0 : TransactionCensusReport.summarize(census);
+				if (census !== void 0 && censusSummary !== void 0) {
+					const sections = [censusSummary];
+					const composed = TransactionCensusReport.composedWraps(census);
+					const unwrapped = TransactionCensusReport.unwrapped(census);
+					if (composed.length > 0) sections.push(`Composed, wrapped on the database the package handed over:\n${composed.map((line) => `  ${line}`).join("\n")}`);
+					if (unwrapped.length > 0) sections.push(`Not wrapped:\n${unwrapped.map((line) => `  ${line}`).join("\n")}`);
+					log.info(sections.join("\n"));
+				}
+				if (mode === CompileMode.App && UpgradeBaseline.hasDurableSurface(checked.files) && !existsSync(join(rootDir, UpgradeBaselineFile.fileName))) log.info(`Durable surface found but no committed ${UpgradeBaselineFile.fileName} — run \`heximon check --update\` once and commit it to arm the upgrade-safety gate.`);
+				if (diagnostics.length > 0) CompileDiagnostics.renderToStderr(rootDir, diagnostics);
+				if (failed) {
+					const parts = [`${errorCount} error${errorCount === 1 ? "" : "s"}`];
+					if (warningCount > 0) parts.push(`${warningCount} warning${warningCount === 1 ? "" : "s"}`);
+					outro(`Check failed — ${parts.join(", ")}.`);
+				} else {
+					const closing = mode === CompileMode.Library ? "Library compiled." : "Verdicts refreshed.";
+					if (warningCount > 0) {
+						log.warn(`${warningCount} warning${warningCount === 1 ? "" : "s"} — not failing (pass --strict to fail on warnings too).`);
+						outro(closing);
+					} else outro(`No issues — ${closing.toLowerCase()}`);
+				}
 			}
-		}
-		if (failed) process.exitCode = 1;
+			if (failed) process.exitCode = 1;
+		});
 	}
 });
 //#endregion
@@ -711,10 +771,13 @@ var CliSpinner = class {
 * message rather than hanging on a prompt no one can answer). Optional creds (e.g. a Cloudflare token when
 * `wrangler login` already authenticates) are never prompted, so a logged-in deploy is not interrupted.
 *
+* Under `--json` the prompter refuses every prompt: the resolver then fails once, with one `cli.option-required`
+* diagnostic for each required credential that is not set.
+*
 * This whole ladder is CLI-specific. A non-CLI caller (a dashboard) resolves the same `CredentialSpec`s its own way
 * — from a vault / secret store — and hands `DeployRunner` an equivalent map; it never constructs this resolver.
 */
-var CredentialResolver = class {
+var CredentialResolver = class CredentialResolver {
 	/**
 	* Resolve the given credential specs into a value map.
 	*
@@ -722,10 +785,12 @@ var CredentialResolver = class {
 	* @param options - Interactivity, the prompter, and the environment source.
 	* @returns The resolved `envVar → value` map (holds secrets — never log it).
 	* @throws PromptCancelledError when the operator cancels an interactive prompt.
+	* @throws CommandFailure when the prompter refused one or more prompts (`--json`).
 	*/
 	static async resolve(specs, options) {
 		const env = options.env ?? process.env;
 		const values = /* @__PURE__ */ new Map();
+		const refused = [];
 		for (const spec of specs) {
 			const fromEnv = env[spec.envVar];
 			if (fromEnv !== void 0 && fromEnv.length > 0) {
@@ -733,13 +798,47 @@ var CredentialResolver = class {
 				continue;
 			}
 			if (spec.required && options.interactive && options.prompter !== void 0) {
-				const label = `${spec.name} (${spec.envVar})`;
-				const prompted = spec.secret ? await options.prompter.secret(label) : await options.prompter.text(label);
+				const label = CredentialResolver.labelOf(spec);
+				let prompted;
+				try {
+					prompted = spec.secret ? await options.prompter.secret(label) : await options.prompter.text(label);
+				} catch (error) {
+					if (!(error instanceof PromptRefusedError)) throw error;
+					refused.push(spec);
+					continue;
+				}
 				if (prompted.length > 0) values.set(spec.envVar, prompted);
 			}
 		}
+		if (refused.length > 0) throw new CommandFailure(refused.map((spec) => CredentialResolver.missing(spec)));
 		return values;
 	}
+	/**
+	* The prompt label of one credential: its name and its environment variable.
+	*
+	* @param spec - The credential.
+	* @returns The label, for example `Cloudflare API token (CLOUDFLARE_API_TOKEN)`.
+	*/
+	static labelOf(spec) {
+		return `${spec.name} (${spec.envVar})`;
+	}
+	/**
+	* Map a prompt label back to the environment variable that answers it, for a refusing prompter.
+	*
+	* @param specs - The credentials the run resolves.
+	* @returns The map function; an unknown label gives the label itself.
+	*/
+	static optionFor(specs) {
+		const envVarByLabel = new Map(specs.map((spec) => [CredentialResolver.labelOf(spec), spec.envVar]));
+		return (message) => envVarByLabel.get(message) ?? message;
+	}
+	/** The `cli.option-required` diagnostic of one required credential that is not set. */
+	static missing(spec) {
+		return CliDiagnostics.error(CliDiagnosticCode.OptionRequired, `${spec.name} is not set, and the command never prompts for it under --json.`, {
+			hint: `Set ${spec.envVar}.`,
+			option: spec.envVar
+		});
+	}
 };
 //#endregion
 //#region src/deploy-command-failure.ts
@@ -764,6 +863,48 @@ var DeployCommandFailure = class {
 		}
 		return false;
 	}
+	/**
+	* The `--json` diagnostic of an expected halt. A cancelled prompt has none: `--json` never prompts.
+	*
+	* @param error - The error {@link report} accepted.
+	* @param codes - The codes of the command.
+	* @returns The error diagnostic, or `undefined` when the error has no code in `codes`.
+	*/
+	static diagnosticOf(error, codes) {
+		const code = error instanceof DeployStrategyUnavailableError ? codes.StrategyUnavailable : error instanceof HostManagedDeployUnsupportedError ? codes.HostManagedUnsupported : error instanceof EnvFileUnreadableError ? codes.EnvFileUnreadable : void 0;
+		return code === void 0 || !(error instanceof Error) ? void 0 : CliDiagnostics.error(code, error.message);
+	}
+};
+//#endregion
+//#region src/deploy-json-document.ts
+/**
+* The stable codes of the `heximon deploy --json` diagnostics. A flag conflict uses
+* `cli.invalid-options`, and a missing answer (`--yes`, a credential variable) uses `cli.option-required`.
+*/
+const DeployDiagnosticCode = {
+	/**
+	* A finding of the deploy run (preflight, migrations, build, infrastructure, provisioning, ship), at its own
+	* severity. A dry run that goes on past an error finding reports it as a warning, so `ok` stays `true`.
+	*/
+	Finding: "deploy.finding",
+	/** The run stopped before the upload. Work that ran before the stop is not rolled back. */
+	Halted: "deploy.halted",
+	/** The vendor rejected the upload, so the artifact is not live. */
+	ShipFailed: "deploy.ship-failed",
+	/** The app shipped, but the `--verify` liveness probe got no 2xx answer. */
+	NotLive: "deploy.not-live",
+	/** The app shipped, but a migration after the ship failed to apply. */
+	MigrationFailed: "deploy.migration-failed",
+	/** `--migrate` found no database config to apply. */
+	NoMigrationConfig: "deploy.no-migration-config",
+	/** `--destroy` on a platform that has no teardown step. */
+	DestroyUnsupported: "deploy.destroy-unsupported",
+	/** No deploy strategy is installed for the platform. */
+	StrategyUnavailable: "deploy.strategy-unavailable",
+	/** The `--env-file` file cannot be read. */
+	EnvFileUnreadable: "deploy.env-file-unreadable",
+	/** A Nitro or Nuxt build uses a preset that the deploy cannot ship. */
+	HostManagedUnsupported: "deploy.host-managed-unsupported"
 };
 //#endregion
 //#region src/deploy-command.ts
@@ -818,6 +959,8 @@ var DeployArgumentGuards = class DeployArgumentGuards {
 * failure, which a local test cannot stage.
 */
 var DeployReport = class DeployReport {
+	/** The hint of an error finding that a dry run went on past. */
+	static dryRunFindingHint = "The dry run went on, but a deploy without --dry-run stops on this finding.";
 	/**
 	* Print the whole outcome and decide the command's exit.
 	*
@@ -837,8 +980,7 @@ var DeployReport = class DeployReport {
 			return false;
 		}
 		if (outcome.halted || outcome.result === void 0) {
-			const completed = DeployReport.completedBeforeHalt(outcome);
-			cancel(completed.length === 0 ? "Halted before ship — nothing changed." : `Halted before ship — nothing was uploaded, but earlier work already completed and was NOT rolled back: ${completed.join("; ")}.`);
+			cancel(DeployReport.haltMessage(outcome));
 			return false;
 		}
 		for (const message of outcome.result.messages) log.message(message);
@@ -866,6 +1008,112 @@ var DeployReport = class DeployReport {
 	static hasFailedMigration(outcome) {
 		return (outcome.migrations ?? []).some((migrated) => migrated.diagnostics.some((diagnostic) => diagnostic.severity === DeployDiagnosticSeverity.Error));
 	}
+	/**
+	* The `--json` diagnostics of an outcome: each finding of the runner, each missing credential, and one
+	* closing error when {@link render} fails the run.
+	*
+	* A run that succeeds exits 0, so it has no error diagnostic: a dry run goes on past a finding that would
+	* stop a real deploy, and that finding is a warning here, with a hint that says so.
+	*
+	* @param outcome - What the runner reported.
+	* @param succeeded - What {@link render} returned for the outcome.
+	* @returns The diagnostics, in the order the text report prints them.
+	*/
+	static diagnostics(outcome, succeeded) {
+		const diagnostics = outcome.diagnostics.map((diagnostic) => DeployReport.finding(diagnostic, succeeded));
+		for (const credential of outcome.missingCredentials) diagnostics.push({
+			...CliDiagnostics.error(CliDiagnosticCode.OptionRequired, `${credential.name} is not set.`, {
+				hint: `Set ${credential.envVar}.`,
+				option: credential.envVar
+			}),
+			severity: outcome.halted ? DiagnosticSeverity.Error : DiagnosticSeverity.Warning
+		});
+		for (const diagnostic of outcome.verification?.diagnostics ?? []) diagnostics.push(DeployReport.finding(diagnostic, succeeded));
+		const closing = DeployReport.closingDiagnostic(outcome);
+		if (closing !== void 0) diagnostics.push(closing);
+		return diagnostics;
+	}
+	/**
+	* The `ship` section of the `--json` document.
+	*
+	* @param outcome - What the runner reported.
+	* @param run - The facts the command recorded around the runner.
+	* @returns The section.
+	*/
+	static ship(outcome, run) {
+		return {
+			halted: outcome.halted,
+			...run,
+			missingCredentials: outcome.missingCredentials.map((credential) => ({
+				name: credential.name,
+				envVar: credential.envVar
+			})),
+			...outcome.targetEnsure === void 0 ? {} : { targetBootstrap: DeployReport.resources(outcome.targetEnsure) },
+			...outcome.provision === void 0 ? {} : { provision: DeployReport.resources(outcome.provision) },
+			migrations: (outcome.migrations ?? []).map((migrated) => ({
+				target: migrated.target,
+				phase: migrated.phase,
+				applied: migrated.applied,
+				failed: migrated.diagnostics.some((diagnostic) => diagnostic.severity === DeployDiagnosticSeverity.Error)
+			})),
+			...outcome.result === void 0 ? {} : { result: {
+				platform: outcome.result.platform,
+				shipped: outcome.result.shipped,
+				failed: outcome.result.failed === true,
+				...outcome.result.url === void 0 ? {} : { url: outcome.result.url },
+				messages: outcome.result.messages
+			} },
+			...outcome.verification === void 0 ? {} : { verification: {
+				url: outcome.verification.url,
+				live: outcome.verification.live
+			} },
+			completedBeforeHalt: outcome.halted ? DeployReport.completedBeforeHalt(outcome) : []
+		};
+	}
+	/**
+	* The error that closes a failed run, in the same order of checks as {@link render}; `undefined` when
+	* the run succeeded.
+	*/
+	static closingDiagnostic(outcome) {
+		if (outcome.result?.failed === true) return CliDiagnostics.error(DeployDiagnosticCode.ShipFailed, `The ship to ${outcome.result.platform} failed, so the artifact is not live.`);
+		if (outcome.halted || outcome.result === void 0) return CliDiagnostics.error(DeployDiagnosticCode.Halted, DeployReport.haltMessage(outcome));
+		if (outcome.verification !== void 0 && !outcome.verification.live) return CliDiagnostics.error(DeployDiagnosticCode.NotLive, `Deployed to ${outcome.result.platform}, but ${outcome.verification.url} does not respond.`);
+		if (DeployReport.hasFailedMigration(outcome)) return CliDiagnostics.error(DeployDiagnosticCode.MigrationFailed, `Deployed to ${outcome.result.platform}, but a migration failed to apply.`);
+	}
+	/**
+	* The halt line. Only the UPLOAD is known not to have happened: target bootstrap, provisioning and a
+	* pre-ship migration run earlier and are never rolled back, so the line names them instead of denying them.
+	*/
+	static haltMessage(outcome) {
+		const completed = DeployReport.completedBeforeHalt(outcome);
+		return completed.length === 0 ? "Halted before ship — nothing changed." : `Halted before ship — nothing was uploaded, but earlier work already completed and was NOT rolled back: ${completed.join("; ")}.`;
+	}
+	/**
+	* One runner finding as a `deploy.finding` diagnostic, at its own severity. In a run that succeeds, an
+	* error finding is a warning, because the run went on past it.
+	*/
+	static finding(diagnostic, succeeded) {
+		if (diagnostic.severity !== DeployDiagnosticSeverity.Error) return {
+			severity: DiagnosticSeverity.Warning,
+			code: DeployDiagnosticCode.Finding,
+			message: diagnostic.message
+		};
+		return {
+			severity: succeeded ? DiagnosticSeverity.Warning : DiagnosticSeverity.Error,
+			code: DeployDiagnosticCode.Finding,
+			message: diagnostic.message,
+			...succeeded ? { hint: DeployReport.dryRunFindingHint } : {}
+		};
+	}
+	/** Copy a phase's resource outcome into its document shape. */
+	static resources(result) {
+		return {
+			created: result.created,
+			existing: result.existing,
+			failed: result.failed,
+			messages: result.messages
+		};
+	}
 	/** The runner's own findings, at the severity each carries. */
 	static logDiagnostics(diagnostics) {
 		for (const diagnostic of diagnostics ?? []) if (diagnostic.severity === DeployDiagnosticSeverity.Error) log.error(diagnostic.message);
@@ -923,18 +1171,70 @@ var DeployReport = class DeployReport {
 		return false;
 	}
 };
+/**
+* Builds the `heximon deploy --json` document. The run fields are set as the run reaches them, so a
+* failure document still says how far the run got.
+*/
+var DeployDocument = class {
+	args;
+	target;
+	credentials;
+	/**
+	* @param args - The parsed deploy flags.
+	*/
+	constructor(args) {
+		this.args = args;
+	}
+	/** Record the resolved target. */
+	resolved(target) {
+		this.target = {
+			platform: target.platformName ?? "node",
+			targetClass: target.targetClass,
+			hostManaged: target.hostManaged === true,
+			...target.artifactDir === void 0 ? {} : { artifactDir: target.artifactDir }
+		};
+	}
+	/** Record the names of the resolved credential variables. */
+	resolvedCredentials(credentials) {
+		this.credentials = [...credentials.keys()];
+	}
+	/**
+	* The document of the run.
+	*
+	* @param ok - Whether the command exits 0.
+	* @param diagnostics - The diagnostics of the run.
+	* @param sections - The `ship` or `destroy` section, once the run has one.
+	* @returns The document.
+	*/
+	document(ok, diagnostics, sections = {}) {
+		return {
+			ok,
+			diagnostics,
+			action: this.args.destroy ? "destroy" : "ship",
+			environment: this.args.env,
+			dryRun: this.args["dry-run"],
+			...this.target === void 0 ? {} : { target: this.target },
+			...this.credentials === void 0 ? {} : { credentials: this.credentials },
+			...sections
+		};
+	}
+};
 /** The `--destroy` teardown and the pre-ship discovery/migration composition the ship path runs. */
-var DeployPhases = class {
+var DeployPhases = class DeployPhases {
+	/** The halt line of a `--migrate` run that found no database config. */
+	static noMigrationConfig = "--migrate found no database config to apply — expected a `*.config.ts` that `export default`s a Drizzle config (see `heximon migrations status`), or apply migrations manually before deploying.";
 	/**
-	* Confirm and run the teardown.
+	* Confirm and run the teardown, and record its document.
 	*
 	* @returns Whether the command should exit non-zero.
 	*/
-	static async destroy(args, target, rootDir, credentials, interactive) {
+	static async destroy(args, target, rootDir, credentials, commandOutput, report) {
 		const platformName = target.platformName ?? "node";
+		const interactive = commandOutput.isInteractive();
+		const question = `Remove the deployed app on ${platformName} (env: ${args.env})? This cannot be undone.`;
 		if (interactive) {
 			const answer = await confirm({
-				message: `Remove the deployed app on ${platformName} (env: ${args.env})? This cannot be undone.`,
+				message: question,
 				initialValue: false
 			});
 			if (isCancel(answer)) {
@@ -946,6 +1246,7 @@ var DeployPhases = class {
 				return false;
 			}
 		} else if (!args.yes) {
+			commandOutput.assertCanPrompt("--yes", question);
 			cancel("Refusing to --destroy non-interactively without --yes.");
 			return true;
 		}
@@ -965,12 +1266,21 @@ var DeployPhases = class {
 			throw teardownError;
 		}
 		removing?.stop(args["dry-run"] ? "Dry run — nothing removed." : "Teardown step complete.");
+		const destroy = {
+			platform: teardown.result?.platform ?? teardown.platformName ?? "node",
+			unsupported: teardown.unsupported,
+			destroyed: teardown.result?.destroyed === true,
+			messages: teardown.result?.messages ?? []
+		};
 		if (teardown.unsupported) {
-			cancel(`Platform ${teardown.platformName ?? "node (default)"} has nothing to remove (no destroy step).`);
+			const message = `Platform ${teardown.platformName ?? "node (default)"} has nothing to remove (no destroy step).`;
+			cancel(message);
+			commandOutput.emit(report.document(false, [CliDiagnostics.error(DeployDiagnosticCode.DestroyUnsupported, message)], { destroy }));
 			return true;
 		}
 		for (const message of teardown.result?.messages ?? []) log.message(message);
 		outro(teardown.result?.destroyed === true ? `Removed from ${teardown.result.platform}.` : `Dry run — nothing removed (${teardown.result?.platform ?? target.platformName ?? "node"}).`);
+		commandOutput.emit(report.document(true, [], { destroy }));
 		return false;
 	}
 	/**
@@ -1046,7 +1356,7 @@ var DeployPhases = class {
 			};
 		} else if (composed.notes.length > 0) log.warn("--migrate will apply 0 databases this run — every detected database config is applied by its own mechanism (see the notes above). Nothing is migrated by this deploy.");
 		else {
-			cancel("--migrate found no database config to apply — expected a `*.config.ts` that `export default`s a Drizzle config (see `heximon migrations status`), or apply migrations manually before deploying.");
+			cancel(DeployPhases.noMigrationConfig);
 			return null;
 		}
 		if (args.migrations !== void 0) log.info("--migrations <dir> is superseded by the auto-detected database config(s) under --migrate.");
@@ -1070,6 +1380,7 @@ const deployCommand = defineCommand({
 			description: "Project root directory.",
 			default: "."
 		},
+		json: CommandOutput.jsonFlag,
 		env: {
 			type: "string",
 			description: "Deploy environment (production / staging / preview:<id>).",
@@ -1141,101 +1452,588 @@ const deployCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const deployArgs = args;
-		const rootDir = resolve(process.cwd(), deployArgs.cwd);
-		const environment = deployArgs.env;
-		const interactive = CliEnvironment.isInteractive();
-		intro(`heximon deploy · ${environment}`);
-		const incoherence = DeployArgumentGuards.incoherence(deployArgs);
-		if (incoherence !== void 0) {
-			cancel(incoherence);
-			process.exitCode = 1;
-			return;
-		}
-		try {
-			const target = await DeployTargetResolver.resolve(rootDir, environment, deployArgs.platform);
-			log.info(`Platform: ${target.platformName ?? "node (default)"} · target class: ${target.targetClass}`);
-			if (target.hostManaged) log.info(`Host-managed build detected (${target.artifactDir}) — shipping it, skipping \`vp build\`.`);
-			const profileMismatch = DeployArgumentGuards.profileMismatch(deployArgs.profile, target.platformName);
-			if (profileMismatch !== void 0) {
-				cancel(profileMismatch);
+		const commandOutput = CommandOutput.resolve("deploy", args);
+		await commandOutput.run(async () => {
+			const deployArgs = args;
+			const rootDir = ProjectRoot.resolve(deployArgs.cwd);
+			const environment = deployArgs.env;
+			const interactive = commandOutput.isInteractive();
+			const report = new DeployDocument(deployArgs);
+			intro(`heximon deploy · ${environment}`);
+			const incoherence = DeployArgumentGuards.incoherence(deployArgs);
+			if (incoherence !== void 0) {
+				cancel(incoherence);
 				process.exitCode = 1;
+				commandOutput.emit(report.document(false, [CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, incoherence)]));
 				return;
 			}
-			const specs = CredentialSelection.inPlay(target.strategy.requiredCredentials(), { provisioning: deployArgs.provision });
-			const credentials = await CredentialResolver.resolve(specs, {
-				interactive,
-				prompter: interactive ? new ClackPrompter() : void 0
-			});
-			if (credentials.size > 0) log.success(`Resolved ${credentials.size} credential(s).`);
-			if (deployArgs.destroy) {
-				if (await DeployPhases.destroy(deployArgs, target, rootDir, credentials, interactive)) process.exitCode = 1;
-				return;
-			}
-			let secrets;
-			if (deployArgs["env-file"] !== void 0) {
-				secrets = await EnvFileReader.read(resolve(rootDir, deployArgs["env-file"]));
-				log.info(`Loaded ${secrets.size} secret(s) from ${deployArgs["env-file"]}.`);
-			}
-			if (!(deployArgs["skip-build"] || target.hostManaged === true)) {
-				const injectable = DeployLedger.injectableEntries(await DeployLedger.read(rootDir, environment));
-				if (injectable.size > 0) log.info(`Injecting ${injectable.size} deploy-ledger value(s) into the build: ${[...injectable.keys()].join(", ")}.`);
-			}
-			DeployPhases.logHarvest(await DeployPhases.harvest(rootDir), deployArgs.migrate);
-			const migrations = await DeployPhases.composeMigrations(deployArgs, rootDir, secrets);
-			if (migrations === null) {
-				process.exitCode = 1;
-				return;
-			}
-			const progress = CliSpinner.begin(interactive, "Preparing the deploy…");
-			const onProgress = (event) => {
-				if (progress === void 0) log.info(event.message);
-				else progress.message(event.message);
-			};
-			let outcome;
 			try {
-				outcome = await DeployRunner.run({
-					target,
-					rootDir,
-					environment,
-					credentials,
-					dryRun: deployArgs["dry-run"],
-					skipBuild: deployArgs["skip-build"] || target.hostManaged === true,
-					...target.artifactDir === void 0 ? {} : { artifactDir: target.artifactDir },
-					provision: deployArgs.provision,
-					...secrets === void 0 ? {} : { secrets },
-					...deployArgs.create === void 0 ? {} : { createTarget: {
-						name: deployArgs.create,
-						...deployArgs.team === void 0 ? {} : { team: deployArgs.team }
-					} },
-					verify: deployArgs.verify,
-					...deployArgs.profile === void 0 ? {} : { profile: deployArgs.profile },
-					onProgress,
-					...migrations === void 0 ? {} : { migrations }
+				const target = await ConfigSidecar.during(rootDir, environment, () => DeployTargetResolver.resolve(rootDir, environment, deployArgs.platform));
+				report.resolved(target);
+				log.info(`Platform: ${target.platformName ?? "node (default)"} · target class: ${target.targetClass}`);
+				if (target.hostManaged) log.info(`Host-managed build detected (${target.artifactDir}) — shipping it, skipping \`vp build\`.`);
+				const profileMismatch = DeployArgumentGuards.profileMismatch(deployArgs.profile, target.platformName);
+				if (profileMismatch !== void 0) {
+					cancel(profileMismatch);
+					process.exitCode = 1;
+					commandOutput.emit(report.document(false, [CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, profileMismatch)]));
+					return;
+				}
+				const specs = CredentialSelection.inPlay(target.strategy.requiredCredentials(), { provisioning: deployArgs.provision });
+				const credentials = await CredentialResolver.resolve(specs, {
+					interactive: interactive || commandOutput.isJson() && !deployArgs["dry-run"],
+					prompter: commandOutput.prompter(CredentialResolver.optionFor(specs))
 				});
-			} catch (runError) {
-				progress?.stop("Deploy failed — see the error below.");
-				throw runError;
+				report.resolvedCredentials(credentials);
+				if (credentials.size > 0) log.success(`Resolved ${credentials.size} credential(s).`);
+				if (deployArgs.destroy) {
+					if (await DeployPhases.destroy(deployArgs, target, rootDir, credentials, commandOutput, report)) process.exitCode = 1;
+					return;
+				}
+				let secrets;
+				if (deployArgs["env-file"] !== void 0) {
+					secrets = await EnvFileReader.read(resolve(rootDir, deployArgs["env-file"]));
+					log.info(`Loaded ${secrets.size} secret(s) from ${deployArgs["env-file"]}.`);
+				}
+				const buildSkipped = deployArgs["skip-build"] || target.hostManaged === true;
+				let ledgerValues = [];
+				if (!buildSkipped) {
+					const injectable = DeployLedger.injectableEntries(await DeployLedger.read(rootDir, environment));
+					ledgerValues = [...injectable.keys()];
+					if (injectable.size > 0) log.info(`Injecting ${injectable.size} deploy-ledger value(s) into the build: ${ledgerValues.join(", ")}.`);
+				}
+				DeployPhases.logHarvest(await DeployPhases.harvest(rootDir), deployArgs.migrate);
+				const migrations = await DeployPhases.composeMigrations(deployArgs, rootDir, secrets);
+				if (migrations === null) {
+					process.exitCode = 1;
+					commandOutput.emit(report.document(false, [CliDiagnostics.error(DeployDiagnosticCode.NoMigrationConfig, DeployPhases.noMigrationConfig)]));
+					return;
+				}
+				const progress = CliSpinner.begin(interactive, "Preparing the deploy…");
+				const phases = [];
+				const onProgress = (event) => {
+					phases.push(event.phase);
+					if (progress === void 0) log.info(event.message);
+					else progress.message(event.message);
+				};
+				let outcome;
+				try {
+					outcome = await DeployRunner.run({
+						target,
+						rootDir,
+						environment,
+						credentials,
+						dryRun: deployArgs["dry-run"],
+						skipBuild: buildSkipped,
+						...target.artifactDir === void 0 ? {} : { artifactDir: target.artifactDir },
+						provision: deployArgs.provision,
+						...secrets === void 0 ? {} : { secrets },
+						...deployArgs.create === void 0 ? {} : { createTarget: {
+							name: deployArgs.create,
+							...deployArgs.team === void 0 ? {} : { team: deployArgs.team }
+						} },
+						verify: deployArgs.verify,
+						...deployArgs.profile === void 0 ? {} : { profile: deployArgs.profile },
+						onProgress,
+						...migrations === void 0 ? {} : { migrations }
+					});
+				} catch (runError) {
+					progress?.stop("Deploy failed — see the error below.");
+					throw runError;
+				}
+				progress?.stop(outcome.halted ? "Stopped — details below." : "Deploy steps complete.");
+				const succeeded = DeployReport.render(outcome, interactive);
+				if (!succeeded) process.exitCode = 1;
+				commandOutput.emit(report.document(succeeded, DeployReport.diagnostics(outcome, succeeded), { ship: DeployReport.ship(outcome, {
+					phases,
+					buildSkipped,
+					ledgerValues,
+					migrationTargets: migrations?.apply === true ? migrations.targets.map((migrationTarget) => migrationTarget.name) : []
+				}) }));
+			} catch (error) {
+				if (DeployCommandFailure.report(error)) {
+					const diagnostic = DeployCommandFailure.diagnosticOf(error, DeployDiagnosticCode);
+					if (diagnostic !== void 0) commandOutput.emit(report.document(false, [diagnostic]));
+					return;
+				}
+				if (error instanceof CommandFailure && commandOutput.isJson()) {
+					commandOutput.emit(report.document(false, error.diagnostics));
+					return;
+				}
+				throw error;
 			}
-			progress?.stop(outcome.halted ? "Stopped — details below." : "Deploy steps complete.");
-			if (!DeployReport.render(outcome, interactive)) process.exitCode = 1;
+		});
+	}
+});
+//#endregion
+//#region src/doctor-json-document.ts
+/** Which audit set one `heximon doctor` run ran. */
+const DoctorMode = {
+	/** The default run: the audits of an app and the libraries it consumes. */
+	App: "app",
+	/** `--self`: the pre-publish check of the current library package. */
+	Self: "self"
+};
+/** The verdict on one audited package in a {@link DoctorJsonDocument}. */
+const DoctorPackageStatus = {
+	/** The packed manifest matches the local source of the package. */
+	Fresh: "fresh",
+	/**
+	* The local source changed since the last pack, some recorded source is gone, or a file the bundle read outside
+	* the source changed or is gone.
+	*/
+	Stale: "stale",
+	/** The packed manifest has no provenance stamp, so nothing was compared. */
+	NoProvenance: "no-provenance",
+	/** The package has no local source (a published package), so nothing was compared. */
+	NoSource: "no-source",
+	/** The package resolves to more than one physical copy. */
+	Fork: "fork"
+};
+/** The outcome of the physical-copy census in a {@link DoctorJsonDocument}. */
+const DoctorCopyCensusStatus = {
+	/** Every probed package resolves to one copy. */
+	SingleCopies: "single-copies",
+	/** At least one probed package resolves to more than one copy. */
+	Forked: "forked",
+	/** The census ran but found no `node_modules` to resolve from, so it could not look. */
+	NothingProbed: "nothing-probed",
+	/** `--self` found no pnpm workspace, so the census did not run. */
+	NotRun: "not-run"
+};
+/**
+* The stable codes of the `heximon doctor` diagnostics. A `heximon.config.ts` that `--self` cannot load is the
+* shared `cli.config-unreadable`, as a warning: the run goes on without its `expectedOpenPeers`.
+*/
+const DoctorDiagnosticCode = {
+	/** `@heximon/*` cannot be read from GitHub Packages. Error. */
+	RegistryAccessFailed: "doctor.registry-access-failed",
+	/** A packed library no longer matches its local source. Error. */
+	StalePackage: "doctor.stale-package",
+	/** A package resolves to more than one physical copy. Error when it fails the run, else warning. */
+	PackageFork: "doctor.package-fork",
+	/** The copy census found nothing to resolve from. Warning. */
+	CopiesNotProbed: "doctor.copies-not-probed",
+	/** The deployed wrangler config does not carry the tracing directives. Warning. */
+	PlatformTracingNotCarried: "doctor.platform-tracing-not-carried",
+	/** A `@heximon/*` peer of the dependency closure is declared nowhere in `package.json`. Warning. */
+	PeerPivotUndeclared: "doctor.peer-pivot-undeclared",
+	/** An `expectedOpenPeers` name matches no undeclared peer. Warning. */
+	StalePeerAcknowledgement: "doctor.stale-peer-acknowledgement"
+};
+//#endregion
+//#region src/doctor-audit.ts
+/** Runs the `heximon doctor` audits, and owns the verdicts that the exit status and both renderers read. */
+var DoctorAudit = class DoctorAudit {
+	/**
+	* Run every audit of one mode. Read-only.
+	*
+	* @param rootDir - The absolute project root.
+	* @param self - Run the `--self` pre-publish check instead of the app audits.
+	* @returns The audit result.
+	*/
+	static async run(rootDir, self) {
+		const registry = await new RegistryAccess().probe();
+		return self ? DoctorAudit.runSelf(rootDir, registry) : DoctorAudit.runApp(rootDir, registry);
+	}
+	/** Whether the registry probe failed. */
+	static isRegistryFailed(result) {
+		return result.registry.status !== RegistryAccessStatus.Ok;
+	}
+	/** Whether the run has a finding that exits 1. */
+	static isFailure(result) {
+		if (DoctorAudit.isRegistryFailed(result)) return true;
+		if (result.mode === DoctorMode.App) return DoctorAudit.staleCount(result.boundaries) > 0;
+		return DoctorAudit.gatingForks(result).length > 0 || result.selfReport?.status === BoundaryProvenanceStatus.Stale;
+	}
+	/** The census reports of packages that resolve to more than one copy. */
+	static forkedReports(audit) {
+		return audit.reports.filter((report) => report.copies.length > 1);
+	}
+	/**
+	* The forks that fail a `--self` run: forks of a runtime-reachable package. A default run has none, because
+	* its census is reported and never fails the run.
+	*/
+	static gatingForks(result) {
+		if (result.mode === DoctorMode.App || result.copyAudit === void 0) return [];
+		if (result.copyAudit.originsProbed === 0) return [];
+		const gatingPackages = result.gatingPackages;
+		return DoctorAudit.forkedReports(result.copyAudit).filter((report) => gatingPackages === void 0 || gatingPackages.has(report.packageName));
+	}
+	/** How many reports are stale. */
+	static staleCount(reports) {
+		return reports.filter((report) => report.status === BoundaryProvenanceStatus.Stale).length;
+	}
+	/** The closing sentence of the run. */
+	static summary(result) {
+		if (result.mode === DoctorMode.App) {
+			if (result.boundaries.length === 0) return "No consumed Heximon library packages found — no staleness audit to run.";
+			const staleCount = DoctorAudit.staleCount(result.boundaries);
+			return staleCount > 0 ? `${staleCount} stale package(s) — rebuild them before trusting this app's build.` : `${result.boundaries.length} package(s) audited — no staleness detected.`;
+		}
+		const parts = [];
+		const forked = DoctorAudit.gatingForks(result).length > 0;
+		if (forked) {
+			const hasConsumers = (result.workspaceConsumers?.consumers.length ?? 0) > 0;
+			parts.push(hasConsumers ? "Forked against a workspace consumer — equalize the two packages' installed peer contexts (a one-sided cover can flip the fork, not remove it) and reinstall." : "Forked within this package's own resolution (no workspace consumers found to compare against) — align the versions its own dependency tree resolves and reinstall.");
+		}
+		if (result.selfReport === null) parts.push("This directory is not a packed Heximon library (no dist/heximon.manifest.json) — the peer-closure and copy census above still ran; run `vp pack` to enable the staleness check too.");
+		else if (result.selfReport.status === BoundaryProvenanceStatus.Stale || !forked) parts.push(DoctorAudit.selfProvenanceSummary(result.selfReport));
+		return parts.join(" ");
+	}
+	/**
+	* The package names a fork of which is RUNTIME-reachable from the library at `rootDir`: the library itself,
+	* its installed `@heximon/*` dependency closure ({@link PeerClosureReport.closurePackages}), every named peer
+	* pivot of that closure, the curated {@link RuntimeSingletons}, and every installed boundary package
+	* ({@link PackageCopyAuditor.installedBoundaryPackages}). A fork of any other name is confined to build-time
+	* tooling (for example a devDependency-only bundler plugin), so it is reported and does not fail the run.
+	*/
+	static runtimeReachablePackageNames(rootDir, closureReport) {
+		const names = new Set(RuntimeSingletons.all());
+		const libraryName = DoctorAudit.readPackageName(rootDir);
+		if (libraryName !== null) names.add(libraryName);
+		for (const packageName of PackageCopyAuditor.installedBoundaryPackages(rootDir)) names.add(packageName);
+		if (closureReport !== null) {
+			for (const packageName of closureReport.closurePackages) names.add(packageName);
+			for (const pivot of closureReport.pivots) names.add(pivot.packageName);
+		}
+		return names;
+	}
+	/**
+	* The `--self` sentence for the own-dist verdict.
+	*
+	* Only {@link BoundaryProvenanceStatus.Fresh} compared anything. The other non-stale verdicts mean the
+	* comparison did not run, so they must never read as a pass.
+	*/
+	static selfProvenanceSummary(report) {
+		switch (report.status) {
+			case BoundaryProvenanceStatus.Fresh: return "This package's dist is current with its src/.";
+			case BoundaryProvenanceStatus.NoProvenance: return "Its packed manifest predates the provenance stamp, so nothing was compared — repack (`vp pack`) to enable the staleness check.";
+			case BoundaryProvenanceStatus.NoSource: return "It ships no local src/, so its packed manifest was not compared with anything.";
+			case BoundaryProvenanceStatus.Stale: return "Your dist is STALE — repack (`vp pack`) before publishing or consuming this package.";
+		}
+	}
+	/** The default run: the copy census, the platform-tracing check, then the staleness audit. */
+	static async runApp(rootDir, registry) {
+		const copyAudit = PackageCopyAuditor.audit(rootDir);
+		const platformTracing = await PlatformTracingAuditor.audit(rootDir);
+		const boundaries = await ConfigSidecar.during(rootDir, void 0, () => BoundaryProvenanceAuditor.audit(rootDir));
+		return {
+			mode: DoctorMode.App,
+			rootDir,
+			registry,
+			copyAudit,
+			platformTracing,
+			boundaries
+		};
+	}
+	/** The `--self` run: the peer-closure roster, the library-side census, then the own-dist staleness check. */
+	static async runSelf(rootDir, registry) {
+		let configError;
+		let configDiagnostic;
+		let expectedOpenPeers = [];
+		try {
+			expectedOpenPeers = (await ConfigLoader.load(rootDir))?.expectedOpenPeers ?? [];
 		} catch (error) {
-			if (DeployCommandFailure.report(error)) return;
-			throw error;
+			configError = error instanceof Error ? error.message : String(error);
+			configDiagnostic = await ConfigSidecar.diagnosticOf(rootDir, error, DiagnosticSeverity.Warning, "so its `expectedOpenPeers` acknowledgements are not applied");
+		}
+		const closureReport = PeerClosureAuditor.audit(rootDir, expectedOpenPeers);
+		const workspaceConsumers = WorkspaceConsumerLocator.locate(rootDir);
+		const census = workspaceConsumers === null ? {} : {
+			copyAudit: PackageCopyAuditor.auditLibrary(rootDir, workspaceConsumers.consumers),
+			gatingPackages: DoctorAudit.runtimeReachablePackageNames(rootDir, closureReport)
+		};
+		const selfReport = await ConfigSidecar.during(rootDir, void 0, () => BoundaryProvenanceAuditor.auditSelf(rootDir));
+		return {
+			mode: DoctorMode.Self,
+			rootDir,
+			registry,
+			...configError === void 0 ? {} : { configError },
+			...configDiagnostic === void 0 ? {} : { configDiagnostic },
+			closureReport,
+			workspaceConsumers,
+			...census,
+			selfReport
+		};
+	}
+	/** The `name` field of a directory's `package.json`, or `null` when absent, unreadable or malformed. */
+	static readPackageName(directory) {
+		try {
+			const parsed = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+			if (typeof parsed === "object" && parsed !== null && "name" in parsed) {
+				const { name } = parsed;
+				return typeof name === "string" ? name : null;
+			}
+		} catch {
+			return null;
 		}
+		return null;
 	}
-});
+};
+/** Renders a {@link DoctorAuditResult} as the `heximon doctor --json` document. */
+var DoctorJsonReport = class DoctorJsonReport {
+	/** The fix of a fork: no single command removes one. */
+	static forkHint = "Deduplicate to one copy (align versions, or hoist it).";
+	/** Shell words that need no quotes. */
+	static plainShellWord = /^[\w./@+:=,-]+$/;
+	/**
+	* Build the document of one run.
+	*
+	* @param result - The audit result.
+	* @returns The document. Its `ok` is `false` exactly when {@link DoctorAudit.isFailure} is `true`.
+	*/
+	static toJson(result) {
+		const packages = DoctorJsonReport.packages(result);
+		const diagnostics = [
+			...DoctorJsonReport.registryDiagnostics(result),
+			...DoctorJsonReport.modeDiagnostics(result),
+			...DoctorJsonReport.packageDiagnostics(packages)
+		];
+		const common = {
+			ok: !DoctorAudit.isFailure(result),
+			diagnostics,
+			mode: result.mode,
+			rootDir: result.rootDir,
+			registry: DoctorJsonReport.registry(result.registry),
+			packages,
+			packageCopies: DoctorJsonReport.copyCensus(result),
+			summary: DoctorAudit.summary(result)
+		};
+		if (result.mode === DoctorMode.App) {
+			const tracing = result.platformTracing;
+			return {
+				...common,
+				platformTracing: {
+					status: tracing.status,
+					...tracing.wranglerConfigPath === void 0 ? {} : { wranglerConfigPath: tracing.wranglerConfigPath },
+					tracingNotEnabled: tracing.tracingNotEnabled,
+					...tracing.droppedSamplerRatio === void 0 ? {} : { droppedSamplerRatio: tracing.droppedSamplerRatio }
+				}
+			};
+		}
+		const closure = result.closureReport;
+		return {
+			...common,
+			...closure === null ? {} : { peerClosure: {
+				closurePackages: closure.closurePackages,
+				pivots: closure.pivots.map((pivot) => DoctorJsonReport.pivot(pivot)),
+				uncovered: closure.uncovered.map((pivot) => DoctorJsonReport.pivot(pivot)),
+				expectedOpen: closure.expectedOpen.map((pivot) => DoctorJsonReport.pivot(pivot)),
+				staleExpectedOpen: closure.staleExpectedOpen
+			} },
+			packed: result.selfReport !== null
+		};
+	}
+	/** The registry section. */
+	static registry(report) {
+		return {
+			registry: RegistryAccess.gitHubPackagesRegistry,
+			probePackage: RegistryAccess.probePackage,
+			status: report.status,
+			...report.detail === void 0 ? {} : { detail: report.detail },
+			...report.status === RegistryAccessStatus.Ok ? {} : { instructions: RegistryAccess.fixInstructions(report.status) }
+		};
+	}
+	/** The census section. */
+	static copyCensus(result) {
+		const workspace = result.mode === DoctorMode.Self && result.workspaceConsumers !== null ? {
+			workspaceRoot: result.workspaceConsumers.workspaceRoot,
+			consumers: result.workspaceConsumers.consumers.map((consumer) => consumer.name)
+		} : {};
+		if (result.copyAudit === void 0) return {
+			status: DoctorCopyCensusStatus.NotRun,
+			originsProbed: 0,
+			packagesProbed: 0,
+			forkedPackages: 0,
+			...workspace
+		};
+		const forkedPackages = result.copyAudit.originsProbed === 0 ? 0 : DoctorAudit.forkedReports(result.copyAudit).length;
+		let status = DoctorCopyCensusStatus.SingleCopies;
+		if (result.copyAudit.originsProbed === 0) status = DoctorCopyCensusStatus.NothingProbed;
+		else if (forkedPackages > 0) status = DoctorCopyCensusStatus.Forked;
+		return {
+			status,
+			originsProbed: result.copyAudit.originsProbed,
+			packagesProbed: result.copyAudit.packagesProbed,
+			forkedPackages,
+			...workspace
+		};
+	}
+	/** Every audited package, in the order of the text report: the forks first, then the staleness verdicts. */
+	static packages(result) {
+		const packages = [];
+		if (result.copyAudit !== void 0 && result.copyAudit.originsProbed > 0) {
+			const gating = new Set(DoctorAudit.gatingForks(result));
+			for (const report of DoctorAudit.forkedReports(result.copyAudit)) packages.push(DoctorJsonReport.forkEntry(report, gating.has(report)));
+		}
+		if (result.mode === DoctorMode.App) for (const report of result.boundaries) packages.push(DoctorJsonReport.staleness(report, false));
+		else if (result.selfReport !== null) packages.push(DoctorJsonReport.staleness(result.selfReport, true));
+		return packages;
+	}
+	/** One fork entry. */
+	static forkEntry(report, failing) {
+		return {
+			name: report.packageName,
+			status: DoctorPackageStatus.Fork,
+			reason: `${String(report.copies.length)} physical copies. Class identity is the DI token, so these bind nominally yet split at runtime.`,
+			hint: DoctorJsonReport.forkHint,
+			self: false,
+			failing,
+			copies: report.copies.map((copy) => ({
+				directory: copy.directory,
+				...copy.version === void 0 ? {} : { version: copy.version },
+				origins: copy.origins
+			}))
+		};
+	}
+	/** One staleness entry. `self` marks the package that `--self` audits. */
+	static staleness(report, self) {
+		const freshness = report;
+		const repack = `cd ${DoctorJsonReport.shellWord(report.packageDirectory)} && vp pack`;
+		const details = {
+			self,
+			...report.packageVersion === void 0 ? {} : { version: report.packageVersion },
+			directory: report.packageDirectory,
+			...report.manifestSourceHash === void 0 ? {} : { manifestSourceHash: report.manifestSourceHash },
+			...report.recomputedSourceHash === void 0 ? {} : { recomputedSourceHash: report.recomputedSourceHash },
+			...report.missingSource === void 0 ? {} : { missingSource: report.missingSource },
+			...freshness.currentSource === void 0 ? {} : { currentSource: freshness.currentSource },
+			...report.manifestBundleInputHash === void 0 ? {} : { manifestBundleInputHash: report.manifestBundleInputHash },
+			...report.recomputedBundleInputHash === void 0 ? {} : { recomputedBundleInputHash: report.recomputedBundleInputHash },
+			...report.missingBundleInputs === void 0 ? {} : { missingBundleInputs: report.missingBundleInputs }
+		};
+		switch (report.status) {
+			case BoundaryProvenanceStatus.Fresh: return {
+				name: report.specifier,
+				status: DoctorPackageStatus.Fresh,
+				reason: `The packed manifest matches the local source (${String(report.manifestSourceHash)}).`,
+				failing: false,
+				...details
+			};
+			case BoundaryProvenanceStatus.Stale: return {
+				name: report.specifier,
+				status: DoctorPackageStatus.Stale,
+				reason: DoctorJsonReport.staleReason(freshness),
+				hint: self ? "Repack (`vp pack`) before publishing or consuming it." : `Rebuild it (\`vp pack\` in ${report.packageDirectory}) before trusting this app's build.`,
+				fix: repack,
+				failing: true,
+				...details
+			};
+			case BoundaryProvenanceStatus.NoProvenance: return {
+				name: report.specifier,
+				status: DoctorPackageStatus.NoProvenance,
+				reason: "The packed manifest predates the provenance stamp, so nothing was compared.",
+				hint: "Repack (`vp pack`) to enable the staleness check.",
+				fix: repack,
+				failing: false,
+				...details
+			};
+			case BoundaryProvenanceStatus.NoSource: return {
+				name: report.specifier,
+				status: DoctorPackageStatus.NoSource,
+				reason: "A published package with no local src/, so its provenance is display-only.",
+				failing: false,
+				...details
+			};
+		}
+	}
+	/** Why a stale report is stale, in the words and the order of the text report. */
+	static staleReason(report) {
+		if (report.currentSource !== void 0) return `The source folders it was packed from (${(report.missingSource ?? []).join(", ")}) no longer exist, and its source is now in ${report.currentSource}.`;
+		if (report.missingBundleInputs !== void 0) return `Files its bundle read outside its source (${report.missingBundleInputs.join(", ")}) are no longer on disk.`;
+		if (report.recomputedBundleInputHash !== void 0) return `A file its bundle read outside its source changed: the bundle inputs (${report.recomputedBundleInputHash}) no longer match the packed manifest (${String(report.manifestBundleInputHash)}).`;
+		if (report.missingSource !== void 0 && report.missingSource.length > 0) return `The source it was packed from (${report.missingSource.join(", ")}) is no longer on disk.`;
+		return `Its src/ (${String(report.recomputedSourceHash)}) no longer matches the packed manifest (${String(report.manifestSourceHash)}).`;
+	}
+	/** The registry diagnostic, when the probe failed. */
+	static registryDiagnostics(result) {
+		if (!DoctorAudit.isRegistryFailed(result)) return [];
+		return [CliDiagnostics.error(DoctorDiagnosticCode.RegistryAccessFailed, `@heximon/* cannot be read from GitHub Packages (${result.registry.status}).`, { hint: RegistryAccess.fixInstructions(result.registry.status) })];
+	}
+	/** The advisory diagnostics of the mode: the census, the tracing check, the roster and the sidecar. */
+	static modeDiagnostics(result) {
+		const diagnostics = [];
+		if (result.mode === DoctorMode.Self && result.configDiagnostic !== void 0) diagnostics.push(result.configDiagnostic);
+		if (result.mode === DoctorMode.Self && result.closureReport !== null) {
+			for (const pivot of result.closureReport.uncovered) diagnostics.push(DoctorJsonReport.warning(DoctorDiagnosticCode.PeerPivotUndeclared, `${pivot.packageName} is a peer of ${pivot.declaredBy.join(", ")}, and this package's package.json declares it nowhere.`, "Equalize the installed peer sets of this package's consumers, or acknowledge the name in `expectedOpenPeers` (heximon.config.ts)."));
+			for (const name of result.closureReport.staleExpectedOpen) diagnostics.push(DoctorJsonReport.warning(DoctorDiagnosticCode.StalePeerAcknowledgement, `expectedOpenPeers names ${name}, which matches no undeclared peer.`, "Remove the name from `expectedOpenPeers` (heximon.config.ts)."));
+		}
+		if (result.copyAudit !== void 0 && result.copyAudit.originsProbed === 0) diagnostics.push(DoctorJsonReport.warning(DoctorDiagnosticCode.CopiesNotProbed, "The copy census found no resolvable node_modules from this directory, so no fork check ran.", "Install the dependencies, then run heximon doctor again."));
+		if (result.mode === DoctorMode.App && result.platformTracing.status === PlatformTracingStatus.NotCarried) diagnostics.push(DoctorJsonReport.tracingDiagnostic(result.platformTracing));
+		return diagnostics;
+	}
+	/** One diagnostic per failing or forked package, in package order. */
+	static packageDiagnostics(packages) {
+		const diagnostics = [];
+		for (const entry of packages) if (entry.status === DoctorPackageStatus.Stale) diagnostics.push(CliDiagnostics.error(DoctorDiagnosticCode.StalePackage, `${entry.name}: ${entry.reason}`, entry.hint === void 0 ? {} : { hint: entry.hint }));
+		else if (entry.status === DoctorPackageStatus.Fork) {
+			const message = `${entry.name} resolves to ${String(entry.copies?.length ?? 0)} physical copies.`;
+			diagnostics.push(entry.failing ? CliDiagnostics.error(DoctorDiagnosticCode.PackageFork, message, { hint: DoctorJsonReport.forkHint }) : DoctorJsonReport.warning(DoctorDiagnosticCode.PackageFork, message, DoctorJsonReport.forkHint));
+		}
+		return diagnostics;
+	}
+	/** The platform-tracing warning. */
+	static tracingDiagnostic(report) {
+		const target = report.wranglerConfigPath ?? "the committed wrangler config";
+		const hints = [];
+		if (report.tracingNotEnabled) hints.push(`Add "observability": { "traces": { "enabled": true } } to ${target} by hand.`);
+		if (report.droppedSamplerRatio !== void 0) hints.push(`Set observability.traces.head_sampling_rate to ${String(report.droppedSamplerRatio)} in ${target} by hand.`);
+		return DoctorJsonReport.warning(DoctorDiagnosticCode.PlatformTracingNotCarried, "otel.exporter \"platform\" writes its tracing directives into a generated wrangler config, but this host-managed Cloudflare build produced none, so the deployed worker does not get them.", hints.join(" "));
+	}
+	/** One warning diagnostic. */
+	static warning(code, message, hint) {
+		return {
+			severity: DiagnosticSeverity.Warning,
+			code,
+			message,
+			...hint === "" ? {} : { hint }
+		};
+	}
+	/** One pivot, copied out of the deploy report. */
+	static pivot(pivot) {
+		return {
+			packageName: pivot.packageName,
+			declaredBy: pivot.declaredBy
+		};
+	}
+	/** A path as one POSIX shell word: as it is when it is plain, else in single quotes. */
+	static shellWord(path) {
+		return DoctorJsonReport.plainShellWord.test(path) ? path : `'${path.replaceAll("'", "'\\''")}'`;
+	}
+};
 //#endregion
 //#region src/doctor-command.ts
-/** The rendering layer behind {@link doctorCommand}: every audit's output, and the verdicts the exit reads. */
+/** The text renderer behind {@link doctorCommand}: every audit of a {@link DoctorAuditResult} as clack lines. */
 var DoctorReport = class DoctorReport {
+	/**
+	* Print the whole report of one run, ending with its summary as the outro.
+	*
+	* @param result - The audit result.
+	*/
+	static render(result) {
+		if (DoctorAudit.isRegistryFailed(result)) log.error(RegistryAccess.fixInstructions(result.registry.status));
+		else log.success("✔ GitHub Packages — @heximon/* readable");
+		if (result.mode === DoctorMode.Self) {
+			if (result.configError !== void 0) log.warn(`heximon.config.ts could not be loaded, so its \`expectedOpenPeers\` acknowledgements are not applied — every open pivot below is reported: ${result.configError}`);
+			DoctorReport.logPeerClosureRoster(result.closureReport);
+			if (result.copyAudit === void 0) log.info("Package copies — no pnpm workspace found from this directory; census not run.");
+			else DoctorReport.logCopyAudit(result.copyAudit, DoctorAudit.gatingForks(result));
+			if (result.selfReport !== null) DoctorReport.logBoundary(result.selfReport, true);
+		} else {
+			DoctorReport.logCopyAudit(result.copyAudit);
+			DoctorReport.logPlatformTracing(result.platformTracing);
+			for (const report of result.boundaries) DoctorReport.logBoundary(report);
+		}
+		outro(DoctorAudit.summary(result));
+	}
 	/** Renders one audited boundary as a status line. `self` reframes the wording for the current package. */
 	static boundaryLine(report, self = false) {
 		const name = self ? `${report.specifier} (this package)` : report.specifier;
 		const version = report.packageVersion === void 0 ? "" : ` v${report.packageVersion}`;
 		switch (report.status) {
 			case BoundaryProvenanceStatus.Fresh: return self ? `✔ ${name}${version} — dist is current with src/ (${report.manifestSourceHash})` : `✔ ${name}${version} — up to date (${report.manifestSourceHash})`;
-			case BoundaryProvenanceStatus.Stale: return self && report.missingSource === void 0 ? `✖ ${name}${version} — STALE: your src/ (${report.recomputedSourceHash}) no longer matches your own dist manifest (${report.manifestSourceHash}). Repack (\`vp pack\`) before publishing or consuming it.` : LibraryFreshness.staleLine(self ? name : report.specifier, report);
+			case BoundaryProvenanceStatus.Stale: return self && report.missingSource === void 0 && !LibraryFreshness.isBundleStale(report) ? `✖ ${name}${version} — STALE: your src/ (${report.recomputedSourceHash}) no longer matches your own dist manifest (${report.manifestSourceHash}). Repack (\`vp pack\`) before publishing or consuming it.` : LibraryFreshness.staleLine(self ? name : report.specifier, report);
 			case BoundaryProvenanceStatus.NoProvenance: return `● ${name}${version} — manifest predates the provenance stamp; repack to enable the check.`;
 			case BoundaryProvenanceStatus.NoSource: return `● ${name}${version} — published package (no local src/); provenance is display-only.`;
 		}
@@ -1248,38 +2046,20 @@ var DoctorReport = class DoctorReport {
 		else log.info(line);
 	}
 	/**
-	* The `--self` outro sentence for a NON-stale own-dist verdict.
-	*
-	* Only {@link BoundaryProvenanceStatus.Fresh} actually compared anything. The other two verdicts mean the
-	* comparison did not run at all, and summarising them as "dist is current with its src/" would report a
-	* check that never happened as a pass — the one thing a pre-publish gate must never do.
-	*/
-	static selfProvenanceSummary(report) {
-		switch (report.status) {
-			case BoundaryProvenanceStatus.Fresh: return "This package's dist is current with its src/.";
-			case BoundaryProvenanceStatus.NoProvenance: return "Its packed manifest predates the provenance stamp, so nothing was compared — repack (`vp pack`) to enable the staleness check.";
-			case BoundaryProvenanceStatus.NoSource: return "It ships no local src/, so its packed manifest was not compared with anything.";
-			case BoundaryProvenanceStatus.Stale: return "Your dist is STALE — repack (`vp pack`) before publishing or consuming this package.";
-		}
-	}
-	/**
 	* Logs the physical-copy census: a line per forked package naming every copy and who resolves to it, or one
 	* summary line when nothing forked. The summary always states how many origins were probed — an audit that
-	* could not look at anything must not read as a clean bill of health. `gatingPackages`, when given, scopes
-	* which forks count as GATING ({@link DoctorReport.runtimeReachablePackageNames}) — every fork is still
-	* printed above either way, and a fork outside the set gets one extra line noting it is reported, not gated.
-	*
-	* @returns Whether any GATING fork was found (any fork at all, when `gatingPackages` is omitted).
+	* could not look at anything must not read as a clean bill of health. `gatingForks`, given by `--self`, are
+	* the forks that fail the run ({@link DoctorAudit.gatingForks}); every fork is printed either way.
 	*/
-	static logCopyAudit(audit, gatingPackages) {
-		const forked = audit.reports.filter((report) => report.copies.length > 1);
+	static logCopyAudit(audit, gatingForks) {
+		const forked = DoctorAudit.forkedReports(audit);
 		if (audit.originsProbed === 0) {
 			log.warn("Package copies — nothing probed (no resolvable node_modules from this directory), so no fork check ran.");
-			return false;
+			return;
 		}
 		if (forked.length === 0) {
 			log.success(`Package copies — ${String(audit.packagesProbed)} package(s) probed from ${String(audit.originsProbed)} origin(s); each resolves to a single copy.`);
-			return false;
+			return;
 		}
 		for (const report of forked) {
 			const copies = report.copies.map((copy) => {
@@ -1287,17 +2067,15 @@ var DoctorReport = class DoctorReport {
 			}).join("\n");
 			log.error(`${report.packageName} — ${String(report.copies.length)} physical copies:\n${copies}\n    Class identity is the DI token, so these bind nominally yet split at runtime. Deduplicate to one copy (align versions, or hoist it).`);
 		}
-		const gatingForks = gatingPackages === void 0 ? forked : forked.filter((report) => gatingPackages.has(report.packageName));
-		if (gatingPackages !== void 0 && gatingForks.length === 0) {
-			log.info(`${String(forked.length)} forked package(s) across ${String(audit.originsProbed)} origin(s) sit outside this package's runtime closure (build-time tooling) — reported, not gated.`);
-			return false;
-		}
-		if (gatingPackages === void 0) {
+		if (gatingForks === void 0) {
 			log.info(`${String(forked.length)} forked package(s) across ${String(audit.originsProbed)} origin(s). Reported, not gated — this does not fail the command.`);
-			return true;
+			return;
+		}
+		if (gatingForks.length === 0) {
+			log.info(`${String(forked.length)} forked package(s) across ${String(audit.originsProbed)} origin(s) sit outside this package's runtime closure (build-time tooling) — reported, not gated.`);
+			return;
 		}
 		log.info(`${String(forked.length)} forked package(s) across ${String(audit.originsProbed)} origin(s), ${String(gatingForks.length)} within this package's runtime closure — reported, and gating this command's exit code.`);
-		return true;
 	}
 	/**
 	* Logs the `@heximon/*` peer-pivot roster ({@link PeerClosureAuditor}): an info line for pivots acknowledged
@@ -1337,40 +2115,6 @@ var DoctorReport = class DoctorReport {
 		if (report.droppedSamplerRatio !== void 0) lines.push(`    \`otel.samplerRatio\` (${String(report.droppedSamplerRatio)}) maps onto the generated config's \`observability.traces.head_sampling_rate\` only, so it does nothing here — carry it in the same section by hand.`);
 		log.warn(lines.join("\n"));
 	}
-	/**
-	* The package names a fork of which is RUNTIME-reachable from the library at `rootDir`: the library itself,
-	* every package its installed `@heximon/*` dependency closure actually resolved
-	* ({@link PeerClosureReport.closurePackages}), every named peer pivot of that closure
-	* ({@link PeerClosureReport.pivots}), the curated {@link RuntimeSingletons}, and every installed boundary
-	* package ({@link PackageCopyAuditor.installedBoundaryPackages}) — a fork of a non-`@heximon` boundary
-	* package (e.g. a consumed `@acme/*` library) is exactly as much a DI-identity split as a fork of a
-	* framework package, since the rule is not scope-specific. A fork of a name outside this set is confined to
-	* build-time tooling (e.g. a devDependency-only bundler/pack plugin) and must be reported, never gated.
-	*/
-	static runtimeReachablePackageNames(rootDir, closureReport) {
-		const names = new Set(RuntimeSingletons.all());
-		const libraryName = DoctorReport.readPackageName(rootDir);
-		if (libraryName !== null) names.add(libraryName);
-		for (const packageName of PackageCopyAuditor.installedBoundaryPackages(rootDir)) names.add(packageName);
-		if (closureReport !== null) {
-			for (const packageName of closureReport.closurePackages) names.add(packageName);
-			for (const pivot of closureReport.pivots) names.add(pivot.packageName);
-		}
-		return names;
-	}
-	/** The `name` field of a directory's `package.json`, or `null` when absent/unreadable/malformed. */
-	static readPackageName(directory) {
-		try {
-			const parsed = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
-			if (typeof parsed === "object" && parsed !== null && "name" in parsed) {
-				const { name } = parsed;
-				return typeof name === "string" ? name : null;
-			}
-		} catch {
-			return null;
-		}
-		return null;
-	}
 };
 /**
 * `heximon doctor` — three read-only audits.
@@ -1413,6 +2157,9 @@ var DoctorReport = class DoctorReport {
 * Compile-free and filesystem-local (the `heximon.config.ts` sidecar is loaded only to read
 * `expectedOpenPeers`); exits non-zero when this package forks a runtime-reachable package against a
 * workspace consumer OR its own dist is stale.
+*
+* `--json` prints the same audit result as one `DoctorJsonDocument` on stdout, with each finding as a
+* diagnostic. Both modes exit 1 exactly when the document has `ok: false`.
 */
 const doctorCommand = defineCommand({
 	meta: {
@@ -1425,6 +2172,7 @@ const doctorCommand = defineCommand({
 			description: "Project root directory.",
 			default: "."
 		},
+		json: CommandOutput.jsonFlag,
 		self: {
 			type: "boolean",
 			description: "Library pre-publish check: this package's own peer-closure roster (advisory), its copy census against workspace consumers, and its packed manifest vs its own src/. Exits non-zero on a fork of a runtime-reachable package (its dependency closure, a named pivot, a curated runtime singleton, an installed boundary package, or itself) or a stale dist — a fork confined to build-time tooling is reported but does not gate.",
@@ -1432,112 +2180,107 @@ const doctorCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const rootDir = resolve(process.cwd(), args.cwd);
-		intro(`heximon doctor — ${basename(rootDir)}`);
-		const registryReport = await new RegistryAccess().probe();
-		const registryFailed = registryReport.status !== RegistryAccessStatus.Ok;
-		if (registryFailed) log.error(RegistryAccess.fixInstructions(registryReport.status));
-		else log.success("✔ GitHub Packages — @heximon/* readable");
-		if (args.self) {
-			const expectedOpenPeers = await ConfigLoader.load(rootDir).then((sidecar) => sidecar?.expectedOpenPeers ?? []).catch((error) => {
-				log.warn(`heximon.config.ts could not be loaded, so its \`expectedOpenPeers\` acknowledgements are not applied — every open pivot below is reported: ${error instanceof Error ? error.message : String(error)}`);
-				return [];
-			});
-			const closureReport = PeerClosureAuditor.audit(rootDir, expectedOpenPeers);
-			DoctorReport.logPeerClosureRoster(closureReport);
-			const workspaceConsumers = WorkspaceConsumerLocator.locate(rootDir);
-			let forked = false;
-			if (workspaceConsumers === null) log.info("Package copies — no pnpm workspace found from this directory; census not run.");
-			else forked = DoctorReport.logCopyAudit(PackageCopyAuditor.auditLibrary(rootDir, workspaceConsumers.consumers), DoctorReport.runtimeReachablePackageNames(rootDir, closureReport));
-			const selfReport = await BoundaryProvenanceAuditor.auditSelf(rootDir);
-			const outroParts = [];
-			let exitFailure = forked || registryFailed;
-			if (forked) {
-				const hasConsumers = (workspaceConsumers?.consumers.length ?? 0) > 0;
-				outroParts.push(hasConsumers ? "Forked against a workspace consumer — equalize the two packages' installed peer contexts (a one-sided cover can flip the fork, not remove it) and reinstall." : "Forked within this package's own resolution (no workspace consumers found to compare against) — align the versions its own dependency tree resolves and reinstall.");
-			}
-			if (selfReport === null) outroParts.push("This directory is not a packed Heximon library (no dist/heximon.manifest.json) — the peer-closure and copy census above still ran; run `vp pack` to enable the staleness check too.");
-			else {
-				DoctorReport.logBoundary(selfReport, true);
-				if (selfReport.status === BoundaryProvenanceStatus.Stale) {
-					exitFailure = true;
-					outroParts.push(DoctorReport.selfProvenanceSummary(selfReport));
-				} else if (!forked) outroParts.push(DoctorReport.selfProvenanceSummary(selfReport));
-			}
-			if (exitFailure) process.exitCode = 1;
-			outro(outroParts.join(" "));
-			return;
-		}
-		DoctorReport.logCopyAudit(PackageCopyAuditor.audit(rootDir));
-		DoctorReport.logPlatformTracing(await PlatformTracingAuditor.audit(rootDir));
-		const reports = await BoundaryProvenanceAuditor.audit(rootDir);
-		if (reports.length === 0) {
-			if (registryFailed) process.exitCode = 1;
-			outro("No consumed Heximon library packages found — no staleness audit to run.");
-			return;
-		}
-		for (const report of reports) DoctorReport.logBoundary(report);
-		const staleCount = reports.filter((report) => report.status === BoundaryProvenanceStatus.Stale).length;
-		if (staleCount > 0 || registryFailed) process.exitCode = 1;
-		if (staleCount > 0) outro(`${staleCount} stale package(s) — rebuild them before trusting this app's build.`);
-		else outro(`${reports.length} package(s) audited — no staleness detected.`);
+		const commandOutput = CommandOutput.resolve("doctor", args);
+		await commandOutput.run(async () => {
+			const rootDir = ProjectRoot.resolve(args.cwd);
+			if (!commandOutput.isJson()) intro(`heximon doctor — ${basename(rootDir)}`);
+			const result = await DoctorAudit.run(rootDir, args.self);
+			if (DoctorAudit.isFailure(result)) process.exitCode = 1;
+			if (commandOutput.isJson()) commandOutput.emit(DoctorJsonReport.toJson(result));
+			else DoctorReport.render(result);
+		});
 	}
 });
 //#endregion
+//#region src/graph-json-document.ts
+/** The stable codes of the failures `heximon graph` raises itself. */
+const GraphDiagnosticCode = {
+	/** The compile threw before the command could read a module graph. */
+	ReadFailed: "graph.read-failed",
+	/** The `--out` file could not be written. */
+	OutWriteFailed: "graph.out-write-failed"
+};
+//#endregion
 //#region src/json-output-target.ts
 /**
-* Where a JSON-emitting inspection command (`routes`, `graph`) sends its payload: an `--out` file, stdout under
-* `--json`, or nowhere when neither flag was passed. One owner for that whole decision — both commands hand it
-* a payload and never branch on the flags themselves.
+* The `--out` file of an inspection command (`routes`, `graph`): it gets the same document the command prints
+* on stdout under `--json`. {@link CommandOutput} owns stdout; this class owns only the file.
 */
 var JsonOutputTarget = class JsonOutputTarget {
 	filePath;
-	toStdout;
 	/**
 	* @param filePath - The absolute `--out` path, or `undefined` when no file was requested.
-	* @param toStdout - Whether the payload is printed on stdout instead.
 	*/
-	constructor(filePath, toStdout) {
+	constructor(filePath) {
 		this.filePath = filePath;
-		this.toStdout = toStdout;
 	}
 	/**
-	* Resolve the destination. `--out` wins and redirects the payload off stdout into a file; a relative path
-	* resolves against the current directory (where the command was typed), not the `--cwd` project root.
+	* Resolve the file. A relative path resolves against the current directory (where the command was typed),
+	* not the `--cwd` project root.
 	*
 	* @param outOption - The raw `--out` argument, when the caller passed one.
-	* @param asJson - Whether `--json` was passed, i.e. whether stdout should carry the payload.
+	* @returns The target; a blank or missing `--out` requests no file.
 	*/
-	static resolve(outOption, asJson) {
+	static resolve(outOption) {
 		const requested = outOption?.trim();
-		const filePath = requested === void 0 || requested === "" ? void 0 : resolve(process.cwd(), requested);
-		return new JsonOutputTarget(filePath, filePath === void 0 && asJson);
+		return new JsonOutputTarget(requested === void 0 || requested === "" ? void 0 : resolve(process.cwd(), requested));
 	}
-	/** Whether the payload goes to a file — the caller's cue to report where it landed. */
+	/** Whether a file was requested — the caller's cue to report where it landed. */
 	isFile() {
 		return this.filePath !== void 0;
 	}
 	/**
-	* Emit the payload. A file gets indented JSON with its parent directory created, so a run can target a
-	* not-yet-existing CI artifact directory and consecutive runs diff line by line; stdout gets the compact
-	* single line `jq` and pipes expect.
+	* Run the body of a command. A failure it throws is written to the file as a `{ ok: false, diagnostics }`
+	* document before it propagates, so the file never keeps the document of an earlier run.
 	*
-	* @returns `false` only when a requested file write failed (the reason is reported on stderr) — the caller's
-	* cue to exit non-zero. A target that emits nowhere reports success.
+	* @param body - The work of the command.
 	*/
-	emit(payload) {
-		if (this.filePath === void 0) {
-			if (this.toStdout) process.stdout.write(`${JSON.stringify(payload)}\n`);
-			return true;
+	async run(body) {
+		try {
+			await body();
+		} catch (error) {
+			this.write({
+				ok: false,
+				diagnostics: error instanceof CommandFailure ? error.diagnostics : [CliDiagnostics.error(CliDiagnosticCode.UnexpectedError, error instanceof Error ? error.message : String(error))]
+			});
+			throw error;
 		}
+	}
+	/**
+	* Write the document to the file, and record it as the stdout document of the run. When the write fails, the
+	* recorded document gets `ok: false` and one more error diagnostic that names the file.
+	*
+	* @param document - The document of the run.
+	* @param commandOutput - The output owner of the run.
+	* @param writeFailureCode - The diagnostic code of a failed write.
+	* @returns Whether the file was written; `true` when no file was requested.
+	*/
+	publish(document, commandOutput, writeFailureCode) {
+		const failure = this.write(document);
+		commandOutput.emit(failure === void 0 ? document : {
+			...document,
+			ok: false,
+			diagnostics: [...document.diagnostics, CliDiagnostics.error(writeFailureCode, `Could not write ${this.filePath}: ${failure}`, { option: "--out" })]
+		});
+		return failure === void 0;
+	}
+	/**
+	* Write indented JSON to the file, with its parent directory created, so a run can target a CI artifact
+	* directory that does not exist yet and consecutive runs diff line by line.
+	*
+	* @returns The reason of a failed write (also written to stderr), or `undefined` when the write worked or
+	*   no file was requested.
+	*/
+	write(document) {
+		if (this.filePath === void 0) return;
 		try {
 			mkdirSync(dirname(this.filePath), { recursive: true });
-			writeFileSync(this.filePath, `${JSON.stringify(payload, null, 2)}\n`);
-			return true;
+			writeFileSync(this.filePath, `${JSON.stringify(document, null, 2)}\n`);
+			return;
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
 			process.stderr.write(`Could not write ${this.filePath} — ${reason}\n`);
-			return false;
+			return reason;
 		}
 	}
 };
@@ -1572,16 +2315,13 @@ var ModuleGraphReport = class ModuleGraphReport {
 		return lines.join("\n");
 	}
 	/**
-	* The serializable `--json` shape: the raw module view plus (when present) the boundary summaries.
+	* The graph fields of the `--json` document: the raw module view plus (when present) the boundary summaries.
 	*
 	* @param view - The compile's module-graph projection.
 	* @param boundaries - The cross-package boundary summaries, when `--boundaries` asked for them.
-	* @param ok - Whether the compile that produced `view` was clean. A graph built from a failed compile has
-	*   unresolved edges, so a consumer reading only `ok` must not read it as a complete answer.
 	*/
-	static toJson(view, boundaries = [], ok = true) {
+	static toJson(view, boundaries = []) {
 		return {
-			ok,
 			modules: view.modules,
 			...boundaries.length > 0 ? { boundaries } : {}
 		};
@@ -1647,11 +2387,7 @@ const graphCommand = defineCommand({
 			description: "The heximon.config.ts `$env` name to resolve (matches `vp dev`). Default development.",
 			default: "development"
 		},
-		json: {
-			type: "boolean",
-			description: "Emit the graph as JSON on stdout instead of a tree.",
-			default: false
-		},
+		json: CommandOutput.jsonFlag,
 		boundaries: {
 			type: "boolean",
 			description: "Also list the cross-package boundary nodes the app composes.",
@@ -1659,7 +2395,7 @@ const graphCommand = defineCommand({
 		},
 		out: {
 			type: "string",
-			description: "Write the JSON payload to this file instead of stdout, creating missing parent directories — the CI-artifact target."
+			description: "Also write the JSON document to this file, creating missing parent directories — the CI-artifact target."
 		},
 		src: {
 			type: "string",
@@ -1669,73 +2405,85 @@ const graphCommand = defineCommand({
 		app: CompileModeResolver.flags.app
 	},
 	async run({ args }) {
-		const rootDir = resolve(process.cwd(), args.cwd);
-		const asJson = args.json;
-		const withBoundaries = args.boundaries;
-		const jsonOutput = JsonOutputTarget.resolve(args.out, asJson);
-		const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
-		const resolved = CompileModeResolver.resolve("graph", rootDir, args, sourceDirectories);
-		if (resolved === void 0) return;
-		if (!asJson) intro(`heximon graph — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
-		let output;
-		try {
-			const session = await ProjectCompileSession.open({
-				rootDir,
-				environment: args.env,
-				...sourceDirectories === void 0 ? {} : { sourceDirectories }
+		const commandOutput = CommandOutput.resolve("graph", args);
+		const outFile = JsonOutputTarget.resolve(args.out);
+		await commandOutput.run(async () => {
+			const rootDir = ProjectRoot.resolve(args.cwd);
+			await outFile.run(async () => {
+				const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
+				const resolved = CompileModeResolver.resolve(rootDir, args, sourceDirectories);
+				if (!commandOutput.isJson()) intro(`heximon graph — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
+				let output;
+				try {
+					const session = await ProjectCompileSession.open({
+						rootDir,
+						environment: args.env,
+						...sourceDirectories === void 0 ? {} : { sourceDirectories }
+					});
+					output = resolved.mode === CompileMode.Library ? session.compileLibrary() : session.compile();
+				} catch (error) {
+					GraphCommand.reportFailure(error instanceof CommandFailure ? error.diagnostics : [CliDiagnostics.error(GraphDiagnosticCode.ReadFailed, error instanceof Error ? error.message : String(error))], commandOutput, outFile);
+					return;
+				}
+				GraphCommand.report(output, {
+					commandOutput,
+					outFile,
+					withBoundaries: args.boundaries,
+					libraryMode: resolved.mode === CompileMode.Library
+				});
 			});
-			output = resolved.mode === CompileMode.Library ? session.compileLibrary() : session.compile();
-		} catch (error) {
-			GraphCommand.reportFailure(error, asJson, jsonOutput);
-			process.exitCode = 1;
-			return;
-		}
-		if (!GraphCommand.report(output, {
-			asJson,
-			withBoundaries,
-			jsonOutput,
-			libraryMode: resolved.mode === CompileMode.Library
-		})) process.exitCode = 1;
+		});
 	}
 });
-/** Output helpers for {@link graphCommand}: the module tree / JSON body and the boundary projection. */
+/** Output helpers for {@link graphCommand}: the module tree / JSON document and the boundary projection. */
 var GraphCommand = class GraphCommand {
 	/**
-	* Print the resolved graph — the JSON payload to its target, and a module-nested tree unless `--json`.
+	* Report the resolved graph: the JSON document to stdout under `--json` and to the `--out` file, and a
+	* module-nested tree unless `--json`. A failed compile or a failed `--out` write sets exit status 1.
 	*
-	* @returns Whether the run succeeded; `false` for a failed compile or a failed `--out` write.
+	* @param output - The compile facts.
+	* @param options - The output owners, and what to print.
 	*/
 	static report(output, options) {
 		const view = output.moduleGraph ?? { modules: [] };
 		const boundaries = options.withBoundaries ? GraphCommand.boundarySummaries(output) : [];
 		const errors = output.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error).length;
-		const written = options.jsonOutput.emit({
-			...ModuleGraphReport.toJson(view, boundaries, errors === 0),
+		const document = {
+			ok: errors === 0,
+			diagnostics: CliDiagnostics.fromCompiler(output.diagnostics),
+			...ModuleGraphReport.toJson(view, boundaries),
 			errors
-		});
-		if (options.asJson) return written && errors === 0;
-		if (written && options.jsonOutput.isFile()) log.success(`Graph JSON written to ${options.jsonOutput.filePath}.`);
+		};
+		const written = options.outFile.publish(document, options.commandOutput, GraphDiagnosticCode.OutWriteFailed);
+		if (!written || errors > 0) process.exitCode = 1;
+		if (options.commandOutput.isJson()) return;
+		if (written && options.outFile.isFile()) log.success(`Graph JSON written to ${options.outFile.filePath}.`);
 		log.message(ModuleGraphReport.renderTree(view, boundaries));
 		if (options.libraryMode === true) log.info("These nodes are this package's PUBLISHED ROOTS, each folded over the local sub-modules it owns. A package's own sub-modules are not separately composable, so they carry no node of their own.");
 		const moduleCount = view.modules.length;
 		const summary = `${moduleCount} module${moduleCount === 1 ? "" : "s"}`;
 		if (errors > 0) outro(`${summary} — ${errors} compile error${errors === 1 ? "" : "s"}; the graph may be incomplete.`);
 		else outro(`${summary}.`);
-		return written && errors === 0;
 	}
 	/**
-	* Report a config-load / compile failure: `{ ok: false, error }` to the JSON target, and a clack error +
-	* outro unless `--json`. The failure payload goes to `--out` too, so re-running replaces the previous
-	* artifact rather than leaving a stale success.
+	* Report a config-load / compile failure: a {@link CliFailureDocument} to stdout under `--json` and to the
+	* `--out` file, and a clack error + outro unless `--json`. The file gets the failure too, so a new run
+	* replaces the previous artifact rather than leaving a stale success. Sets exit status 1.
+	*
+	* @param diagnostics - The diagnostics of the failure.
+	* @param commandOutput - The stdout owner of the run.
+	* @param outFile - The `--out` file.
 	*/
-	static reportFailure(error, asJson, jsonOutput) {
-		const message = error instanceof Error ? error.message : String(error);
-		jsonOutput.emit({
+	static reportFailure(diagnostics, commandOutput, outFile) {
+		const document = {
 			ok: false,
-			error: message
-		});
-		if (asJson) return;
-		log.error(`Could not read the app's module graph:\n${message}`);
+			diagnostics
+		};
+		outFile.publish(document, commandOutput, GraphDiagnosticCode.OutWriteFailed);
+		process.exitCode = 1;
+		if (commandOutput.isJson()) return;
+		const messages = diagnostics.map((diagnostic) => diagnostic.message);
+		log.error(`Could not read the app's module graph:\n${messages.join("\n")}`);
 		outro("No graph to show.");
 	}
 	/** Project the compile's cross-package boundary nodes into display summaries. */
@@ -1749,12 +2497,45 @@ var GraphCommand = class GraphCommand {
 	}
 };
 //#endregion
+//#region src/migrations-json-document.ts
+/** The stable codes of the failures and warnings `heximon migrations` raises itself. */
+const MigrationsDiagnosticCode = {
+	/** No drizzle-kit config was detected, and `--config` was not given. */
+	NoConfig: "migrations.no-config",
+	/** A candidate config file could not be loaded. A warning beside {@link NoConfig}; `file` names it. */
+	ConfigLoadFailed: "migrations.config-load-failed",
+	/** The `--env-file` cannot be read. */
+	EnvFileUnreadable: "migrations.env-file-unreadable",
+	/** `drizzle-kit` exited with a non-zero status for one database. */
+	DrizzleKitFailed: "migrations.drizzle-kit-failed",
+	/** `drizzle-kit` could not start, for example because it is not installed. The run stops there. */
+	DrizzleKitNotStarted: "migrations.drizzle-kit-not-started",
+	/** A Cloudflare D1 database was not migrated: `wrangler d1 migrations apply` applies it. A warning. */
+	D1ApplySkipped: "migrations.d1-apply-skipped"
+};
+/** What happened to one database in a `generate`, `migrate` or `push` run. */
+const MigrationsStepStatus = {
+	/** `drizzle-kit` exited 0. */
+	Succeeded: "succeeded",
+	/** `drizzle-kit` exited with a non-zero status. */
+	Failed: "failed",
+	/** `drizzle-kit` could not start. The run stopped, and the databases after this one have no entry. */
+	NotStarted: "not-started",
+	/** The command did not run `drizzle-kit` for this database; {@link MigrationsStepEntry.reason} says why. */
+	Skipped: "skipped"
+};
+//#endregion
 //#region src/migrations-command.ts
 /**
-* The plumbing every `heximon migrations` subcommand shares: the `.env` + detection prologue, the config
-* selection, one captured `drizzle-kit` invocation, and the throw-to-cancel guard.
+* The plumbing every `heximon migrations` subcommand shares: the output mode, the `.env` + detection prologue,
+* the config selection, one captured `drizzle-kit` invocation, and the diagnostics of the `--json` document.
 */
 var MigrationsRunner = class MigrationsRunner {
+	commandOutput;
+	rootDir;
+	detection;
+	args;
+	mask;
 	/** The flags every `heximon migrations` subcommand accepts. */
 	static baseArgs = {
 		cwd: {
@@ -1774,42 +2555,80 @@ var MigrationsRunner = class MigrationsRunner {
 		config: {
 			type: "string",
 			description: "Target one drizzle-kit config file, bypassing auto-detection."
-		}
+		},
+		json: CommandOutput.jsonFlag
 	};
 	/** The `select` sentinel for "run every detected database". */
 	static allDatabasesValue = "__all__";
+	/** The message of the "no drizzle-kit config" halt. */
+	static noConfigMessage = "No drizzle-kit config found — expected a `*.config.ts` that `export default`s a Drizzle config (e.g. src/database/database.config.ts), or pass --config <path>.";
+	/** The password of a URL with userinfo (`scheme://user:password@host`), as the `secret` group. */
+	static urlPassword = /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]*:(?<secret>[^\s@/]+)@/dgiu;
+	/** The value of a `password` query parameter (`?password=…`, `&password=…`), as the `secret` group. */
+	static queryPassword = /[?&]password=(?<secret>[^&#\s]+)/dgiu;
+	/** Every diagnostic of the run, in the order the run raised them. */
+	diagnostics = [];
 	/**
-	* Resolve the project root, load the `.env` cascade into `process.env` (so the spawned `drizzle-kit`
-	* inherits `DATABASE_URL`), and detect the app's drizzle-kit config file(s). An explicit `--env-file`
-	* overlays the cascade.
+	* @param mask - The credentials of the run: each `--env-file` value of at least
+	*   {@link SecretMask.minimumFragmentLength} characters, and the `dbCredentials` secrets of each config at any
+	*   length. drizzle-kit can echo them, and its output reaches the terminal and the `--json` document.
 	*/
-	static async prepare(args) {
-		const rootDir = resolve(process.cwd(), args.cwd);
-		const overlay = args["env-file"] === void 0 ? void 0 : await EnvFileReader.read(resolve(rootDir, args["env-file"]));
-		DotenvCascade.loadInto(rootDir, args.env, overlay);
-		return {
-			rootDir,
-			detection: await DatabaseConfigDetector.detect(rootDir)
-		};
+	constructor(commandOutput, rootDir, detection, args, mask) {
+		this.commandOutput = commandOutput;
+		this.rootDir = rootDir;
+		this.detection = detection;
+		this.args = args;
+		this.mask = mask;
+	}
+	/**
+	* The options of one `drizzle-kit` call. They carry no mask: {@link redact} masks the original captured output
+	* with the registered secrets and the URL rules together.
+	*/
+	drizzleKitOptions() {
+		return { rootDir: this.rootDir };
+	}
+	/**
+	* Run one subcommand: resolve the output mode, print the intro, load the `.env` cascade, detect the
+	* configs, then run the body.
+	*
+	* @param subcommand - The subcommand verb (`generate`, `migrate`, …).
+	* @param args - The parsed arguments.
+	* @param body - The work of the subcommand. It records its `--json` document on the runner's output.
+	*/
+	static async execute(subcommand, args, body) {
+		const commandOutput = CommandOutput.resolve(`migrations ${subcommand}`, args);
+		await commandOutput.run(async () => {
+			const rootDir = ProjectRoot.resolve(args.cwd);
+			await MigrationsRunner.guard(commandOutput, async () => {
+				intro(`heximon migrations ${subcommand}`);
+				await body(await MigrationsRunner.prepare(commandOutput, args, rootDir));
+			});
+		});
 	}
 	/**
 	* Choose which detected config(s) to act on: an explicit `--config` wins; a single detected config is used
 	* silently; multiple prompt an interactive `select`, or — in a non-TTY run — fan out to ALL of them, which
-	* is named out loud because that is several databases the operator never chose. Reports the failure itself
-	* (no config / cancelled) and returns `undefined` so the caller just returns.
+	* is named out loud because that is several databases the operator never chose. Under `--json` several
+	* configs fail with {@link CliDiagnosticCode.OptionRequired}, because `--json` never chooses for the caller.
+	* Reports a text-mode failure itself (no config / cancelled) and returns `undefined` so the caller just
+	* returns.
 	*/
-	static async selectConfigs(rootDir, detection, args, interactive) {
-		if (args.config !== void 0) {
-			const path = resolve(rootDir, args.config);
-			return [await DatabaseConfigDetector.classifyFile(rootDir, path) ?? MigrationsRunner.syntheticConfig(path)];
-		}
-		const { configs } = detection;
+	async selectConfigs() {
+		if (this.args.config !== void 0) {
+			const path = resolve(this.rootDir, this.args.config);
+			const classified = await DatabaseConfigDetector.classifyFile(this.rootDir, path);
+			if (classified !== null) MigrationsRunner.registerCredentials(this.mask, classified);
+			return [classified ?? MigrationsRunner.syntheticConfig(path)];
+		}
+		const { configs } = this.detection;
 		if (configs.length === 0) {
-			MigrationsRunner.reportNoConfig(detection);
+			if (this.commandOutput.isJson()) throw new CommandFailure(MigrationsRunner.noConfigDiagnostics(this.detection));
+			MigrationsRunner.reportNoConfig(this.detection);
 			return;
 		}
 		if (configs.length === 1) return configs;
-		if (!interactive) {
+		if (this.commandOutput.isJson()) throw new CommandFailure([this.selectionRefusal(configs)]);
+		if (!this.commandOutput.isInteractive()) {
 			log.warn(`${configs.length} databases detected and no TTY to choose between them — acting on ALL of them: ${configs.map((config) => config.name).join(", ")}. Pass --config <path> to target one.`);
 			return configs;
 		}
@@ -1832,34 +2651,158 @@ var MigrationsRunner = class MigrationsRunner {
 		return configs.filter((config) => config.path === choice);
 	}
 	/**
-	* Run one captured `drizzle-kit` invocation behind a spinner, relaying its output.
+	* Run one captured `drizzle-kit` invocation behind a spinner, relaying its output. A failure also records
+	* an error diagnostic.
 	*
-	* @returns `true` on exit code 0, else `false` (the output is logged either way).
+	* @param config - The database the invocation acts on.
+	* @param label - The progress label, for example `Applying migrations for database.config.ts`.
+	* @param invoke - Starts the invocation.
+	* @returns The entry of the database. A `not-started` status means the caller stops its loop.
 	*/
-	static async runStep(interactive, label, invoke) {
-		const progress = CliSpinner.begin(interactive, `${label}…`);
+	async runStep(config, label, invoke) {
+		const progress = CliSpinner.begin(this.commandOutput.isInteractive(), `${label}…`);
 		let result;
 		try {
 			result = await invoke();
 		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
 			progress?.stop(`${label} — failed to start.`);
-			throw error;
+			log.error(reason);
+			this.diagnostics.push(CliDiagnostics.error(MigrationsDiagnosticCode.DrizzleKitNotStarted, `${label}: drizzle-kit could not start. ${reason}`, { hint: "Add drizzle-kit to the devDependencies of the app, then run the command again." }));
+			return {
+				...this.viewOf(config),
+				status: MigrationsStepStatus.NotStarted,
+				reason
+			};
 		}
-		const output = [result.stdout.trim(), result.stderr.trim()].filter((part) => part.length > 0);
+		const stdout = this.redact(result.stdout);
+		const stderr = this.redact(result.stderr);
+		const output = [stdout.trim(), stderr.trim()].filter((part) => part.length > 0);
+		const drizzleKit = {
+			exitCode: result.exitCode,
+			stdout,
+			stderr
+		};
 		if (result.exitCode === 0) {
 			progress?.stop(`${label} — done.`);
 			if (output.length > 0) log.message(output.join("\n"));
-			return true;
+			return {
+				...this.viewOf(config),
+				status: MigrationsStepStatus.Succeeded,
+				drizzleKit
+			};
 		}
 		progress?.stop(`${label} — failed (exit ${result.exitCode}).`);
 		if (output.length > 0) log.error(output.join("\n"));
-		return false;
+		this.diagnostics.push(CliDiagnostics.error(MigrationsDiagnosticCode.DrizzleKitFailed, `${label}: drizzle-kit exited with status ${result.exitCode}.`, { hint: "Read the drizzle-kit output in the drizzleKit field of the database entry." }));
+		return {
+			...this.viewOf(config),
+			status: MigrationsStepStatus.Failed,
+			drizzleKit
+		};
+	}
+	/**
+	* Record a database that `migrate` does not apply.
+	*
+	* @param config - The skipped database.
+	* @param reason - Why it is skipped, and what applies it.
+	* @param warning - A warning diagnostic to record beside the entry, when the operator must act.
+	* @returns The entry of the database.
+	*/
+	skip(config, reason, warning) {
+		if (warning !== void 0) this.diagnostics.push(warning);
+		return {
+			...this.viewOf(config),
+			status: MigrationsStepStatus.Skipped,
+			reason
+		};
+	}
+	/** The `.sql` files in the migrations folder of a config, relative to that folder, sorted. */
+	async sqlFilesOf(config) {
+		return (await MigrationInspector.collectSqlFiles(resolve(this.rootDir, MigrationsRunner.migrationsDirectoryOf(config)))).map((file) => file.relativePath);
+	}
+	/** The JSON view of one config. */
+	viewOf(config) {
+		return {
+			name: config.name,
+			configPath: config.path,
+			dialect: config.dialect,
+			...config.driver === void 0 ? {} : { driver: config.driver },
+			applyMode: config.applyMode,
+			migrationsDirectory: MigrationsRunner.migrationsDirectoryOf(config)
+		};
+	}
+	/** Whether the run recorded no error diagnostic. */
+	isSuccessful() {
+		return !this.diagnostics.some((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error);
+	}
+	/**
+	* The `--json` document of the run.
+	*
+	* @param databases - One entry for each database the run acted on.
+	* @returns The document, with `ok` from the recorded diagnostics.
+	*/
+	document(databases) {
+		return {
+			ok: this.isSuccessful(),
+			diagnostics: [...this.diagnostics],
+			rootDir: this.rootDir,
+			databases
+		};
+	}
+	/** The migrations folder of a config: its `out`, else the drizzle-kit default. */
+	static migrationsDirectoryOf(config) {
+		return config.out ?? DatabaseConfigDetector.defaultOutDirectory;
+	}
+	/**
+	* Load the `.env` cascade into `process.env` (so the spawned `drizzle-kit` inherits `DATABASE_URL`), and
+	* detect the app's drizzle-kit config file(s). An explicit `--env-file` overlays the cascade.
+	*
+	* @param rootDir - The project root {@link ProjectRoot.resolve} accepted.
+	*/
+	static async prepare(commandOutput, args, rootDir) {
+		const overlay = args["env-file"] === void 0 ? void 0 : await MigrationsRunner.readEnvFile(resolve(rootDir, args["env-file"]));
+		DotenvCascade.loadInto(rootDir, args.env, overlay);
+		const mask = new SecretMask();
+		const detection = await DatabaseConfigDetector.detect(rootDir);
+		for (const value of overlay?.values() ?? []) if (value.length >= SecretMask.minimumFragmentLength) mask.register(value);
+		for (const config of detection.configs) MigrationsRunner.registerCredentials(mask, config);
+		return new MigrationsRunner(commandOutput, rootDir, detection, args, mask);
+	}
+	/** Register the `dbCredentials` secrets of one config, and the password inside each URL among them. */
+	static registerCredentials(mask, config) {
+		for (const credential of config.credentials ?? []) {
+			mask.register(credential);
+			for (const match of credential.matchAll(MigrationsRunner.urlPassword)) mask.register(match.groups?.["secret"] ?? "");
+		}
+	}
+	/**
+	* Hide the registered secrets, the password of any URL with userinfo, and any `password` query parameter in
+	* captured output. Every range is found on the original text and replaced in one step, so no rule changes the
+	* text another rule reads.
+	*/
+	redact(text) {
+		return this.mask.redactWithPatterns(text, [MigrationsRunner.urlPassword, MigrationsRunner.queryPassword]);
+	}
+	/** Read the `--env-file`; an unreadable file is an expected failure with its own code. */
+	static async readEnvFile(path) {
+		try {
+			return await EnvFileReader.read(path);
+		} catch (error) {
+			if (error instanceof EnvFileUnreadableError) throw CommandFailure.of(MigrationsDiagnosticCode.EnvFileUnreadable, error.message);
+			throw error;
+		}
 	}
 	/**
 	* Wrap a subcommand body so a thrown error (e.g. an unreadable `--env-file`) becomes a clean cancel +
-	* non-zero exit rather than an unhandled stack trace.
+	* non-zero exit rather than an unhandled stack trace. Under `--json` the error reaches
+	* {@link CommandOutput.run}, which prints it as the failure document.
 	*/
-	static async guard(body) {
+	static async guard(commandOutput, body) {
+		if (commandOutput.isJson()) {
+			await body();
+			return;
+		}
 		try {
 			await body();
 		} catch (error) {
@@ -1867,6 +2810,14 @@ var MigrationsRunner = class MigrationsRunner {
 			cancel(error instanceof Error ? error.message : String(error));
 		}
 	}
+	/** The `--json` refusal of the database `select`, naming every choice. */
+	selectionRefusal(configs) {
+		const paths = configs.map((config) => relative(this.rootDir, config.path));
+		return CliDiagnostics.error(CliDiagnosticCode.OptionRequired, `${configs.length} databases were detected (${paths.join(", ")}), and --json never chooses one.`, {
+			hint: `Pass --config <path> with one of: ${paths.join(", ")}. Run once for each database to act on all.`,
+			option: "--config"
+		});
+	}
 	/**
 	* A stand-in for an explicit `--config` that could not be classified (unloadable / not a drizzle config):
 	* the command still drives `drizzle-kit` on it and surfaces drizzle-kit's own error, trusting the flag.
@@ -1887,9 +2838,18 @@ var MigrationsRunner = class MigrationsRunner {
 	*/
 	static reportNoConfig(detection) {
 		process.exitCode = 1;
-		cancel("No drizzle-kit config found — expected a `*.config.ts` that `export default`s a Drizzle config (e.g. src/database/database.config.ts), or pass --config <path>.");
+		cancel(MigrationsRunner.noConfigMessage);
 		for (const failure of detection.loadErrors) log.warn(`Could not load ${failure.path}: ${failure.message}`);
 	}
+	/** The `--json` diagnostics of the "no drizzle-kit config" halt: the error, then one warning per candidate. */
+	static noConfigDiagnostics(detection) {
+		return [CliDiagnostics.error(MigrationsDiagnosticCode.NoConfig, MigrationsRunner.noConfigMessage, { hint: "Add a drizzle-kit config, or pass --config <path>." }), ...detection.loadErrors.map((failure) => ({
+			severity: DiagnosticSeverity.Warning,
+			code: MigrationsDiagnosticCode.ConfigLoadFailed,
+			message: `Could not load ${failure.path}: ${failure.message}`,
+			file: failure.path
+		}))];
+	}
 };
 const generateCommand = defineCommand({
 	meta: {
@@ -1903,16 +2863,24 @@ const generateCommand = defineCommand({
 			description: "Name the migration (drizzle-kit --name)."
 		}
 	},
-	run: ({ args }) => MigrationsRunner.guard(async () => {
-		const interactive = CliEnvironment.isInteractive();
-		intro("heximon migrations generate");
-		const { rootDir, detection } = await MigrationsRunner.prepare(args);
-		const selected = await MigrationsRunner.selectConfigs(rootDir, detection, args, interactive);
+	run: ({ args }) => MigrationsRunner.execute("generate", args, async (runner) => {
+		const selected = await runner.selectConfigs();
 		if (selected === void 0) return;
-		const runner = new DrizzleKitRunner();
-		let allSucceeded = true;
-		for (const config of selected) allSucceeded = await MigrationsRunner.runStep(interactive, `Generating migration for ${config.name}`, () => runner.generate(config.path, { rootDir }, args.name)) && allSucceeded;
-		if (!allSucceeded) {
+		const drizzleKit = new DrizzleKitRunner();
+		const entries = [];
+		for (const config of selected) {
+			const filesBefore = new Set(await runner.sqlFilesOf(config));
+			const entry = await runner.runStep(config, `Generating migration for ${config.name}`, () => drizzleKit.generate(config.path, runner.drizzleKitOptions(), args.name));
+			const filesAfter = await runner.sqlFilesOf(config);
+			entries.push({
+				...entry,
+				generatedFiles: filesAfter.filter((file) => !filesBefore.has(file))
+			});
+			if (entry.status === MigrationsStepStatus.NotStarted) break;
+		}
+		const document = runner.document(entries);
+		runner.commandOutput.emit(document);
+		if (!runner.isSuccessful()) {
 			process.exitCode = 1;
 			cancel("Some migrations failed to generate — see above.");
 			return;
@@ -1926,26 +2894,37 @@ const migrateCommand = defineCommand({
 		description: "Apply pending migrations (drizzle-kit migrate)."
 	},
 	args: MigrationsRunner.baseArgs,
-	run: ({ args }) => MigrationsRunner.guard(async () => {
-		const interactive = CliEnvironment.isInteractive();
-		intro("heximon migrations migrate");
-		const { rootDir, detection } = await MigrationsRunner.prepare(args);
-		const selected = await MigrationsRunner.selectConfigs(rootDir, detection, args, interactive);
+	run: ({ args }) => MigrationsRunner.execute("migrate", args, async (runner) => {
+		const selected = await runner.selectConfigs();
 		if (selected === void 0) return;
-		const runner = new DrizzleKitRunner();
-		let allSucceeded = true;
+		const drizzleKit = new DrizzleKitRunner();
+		const entries = [];
 		for (const config of selected) {
 			if (config.applyMode === "wrangler-d1") {
-				log.warn(`${config.name}: a Cloudflare D1 database — apply it with \`wrangler d1 migrations apply <database> --remote\`, not drizzle-kit.`);
+				const message = `${config.name}: a Cloudflare D1 database — apply it with \`wrangler d1 migrations apply <database> --remote\`, not drizzle-kit.`;
+				log.warn(message);
+				entries.push(runner.skip(config, message, {
+					severity: DiagnosticSeverity.Warning,
+					code: MigrationsDiagnosticCode.D1ApplySkipped,
+					message,
+					hint: "Run `wrangler d1 migrations apply <database> --remote`.",
+					file: config.path
+				}));
 				continue;
 			}
 			if (config.applyMode === "skip") {
-				log.info(`${config.name}: Durable Object SQLite — migrations bundle in-DO at init; no CLI apply step.`);
+				const message = `${config.name}: Durable Object SQLite — migrations bundle in-DO at init; no CLI apply step.`;
+				log.info(message);
+				entries.push(runner.skip(config, message));
 				continue;
 			}
-			allSucceeded = await MigrationsRunner.runStep(interactive, `Applying migrations for ${config.name}`, () => runner.migrate(config.path, { rootDir })) && allSucceeded;
+			const entry = await runner.runStep(config, `Applying migrations for ${config.name}`, () => drizzleKit.migrate(config.path, runner.drizzleKitOptions()));
+			entries.push(entry);
+			if (entry.status === MigrationsStepStatus.NotStarted) break;
 		}
-		if (!allSucceeded) {
+		const document = runner.document(entries);
+		runner.commandOutput.emit(document);
+		if (!runner.isSuccessful()) {
 			process.exitCode = 1;
 			cancel("Some migrations failed to apply — see above.");
 			return;
@@ -1959,21 +2938,25 @@ const statusCommand = defineCommand({
 		description: "List the on-disk migrations per database."
 	},
 	args: MigrationsRunner.baseArgs,
-	run: ({ args }) => MigrationsRunner.guard(async () => {
-		const interactive = CliEnvironment.isInteractive();
-		intro("heximon migrations status");
-		const { rootDir, detection } = await MigrationsRunner.prepare(args);
-		const selected = await MigrationsRunner.selectConfigs(rootDir, detection, args, interactive);
+	run: ({ args }) => MigrationsRunner.execute("status", args, async (runner) => {
+		const selected = await runner.selectConfigs();
 		if (selected === void 0) return;
+		const entries = [];
 		for (const config of selected) {
-			const outFolder = config.out ?? DatabaseConfigDetector.defaultOutDirectory;
-			const files = await MigrationInspector.collectSqlFiles(resolve(rootDir, outFolder));
+			const outFolder = MigrationsRunner.migrationsDirectoryOf(config);
+			const files = await runner.sqlFilesOf(config);
+			entries.push({
+				...runner.viewOf(config),
+				migrations: files
+			});
 			if (files.length === 0) {
 				log.info(`${config.name}: no migrations in ${outFolder} — run \`heximon migrations generate\`.`);
 				continue;
 			}
-			log.message(`${config.name} · ${files.length} migration(s) in ${outFolder}:\n` + files.map((file) => `  ${file.relativePath}`).join("\n"));
+			log.message(`${config.name} · ${files.length} migration(s) in ${outFolder}:\n` + files.map((file) => `  ${file}`).join("\n"));
 		}
+		const document = runner.document(entries);
+		runner.commandOutput.emit(document);
 		log.info("Applied vs. pending state needs a live database query — not shown in this view.");
 		outro("Status listed.");
 	})
@@ -1990,21 +2973,20 @@ const pushCommand = defineCommand({
 			description: "Confirm the destructive push non-interactively."
 		}
 	},
-	run: ({ args }) => MigrationsRunner.guard(async () => {
-		const interactive = CliEnvironment.isInteractive();
-		intro("heximon migrations push");
-		const { rootDir, detection } = await MigrationsRunner.prepare(args);
-		const selected = await MigrationsRunner.selectConfigs(rootDir, detection, args, interactive);
+	run: ({ args }) => MigrationsRunner.execute("push", args, async (runner) => {
+		const selected = await runner.selectConfigs();
 		if (selected === void 0) return;
 		let force = args.yes === true;
 		if (!force) {
-			if (!interactive) {
+			const question = `Push schema directly to ${selected.map((config) => config.name).join(", ")}? This can DROP columns/tables.`;
+			runner.commandOutput.assertCanPrompt("--yes", question);
+			if (!runner.commandOutput.isInteractive()) {
 				process.exitCode = 1;
 				cancel("`push` is destructive (it can drop columns/tables). Re-run with --yes to confirm in a non-interactive shell.");
 				return;
 			}
 			const confirmed = await confirm({
-				message: `Push schema directly to ${selected.map((config) => config.name).join(", ")}? This can DROP columns/tables.`,
+				message: question,
 				initialValue: false
 			});
 			if (isCancel(confirmed) || confirmed !== true) {
@@ -2014,10 +2996,16 @@ const pushCommand = defineCommand({
 			}
 			force = true;
 		}
-		const runner = new DrizzleKitRunner();
-		let allSucceeded = true;
-		for (const config of selected) allSucceeded = await MigrationsRunner.runStep(interactive, `Pushing schema for ${config.name}`, () => runner.push(config.path, { rootDir }, force)) && allSucceeded;
-		if (!allSucceeded) {
+		const drizzleKit = new DrizzleKitRunner();
+		const entries = [];
+		for (const config of selected) {
+			const entry = await runner.runStep(config, `Pushing schema for ${config.name}`, () => drizzleKit.push(config.path, runner.drizzleKitOptions(), force));
+			entries.push(entry);
+			if (entry.status === MigrationsStepStatus.NotStarted) break;
+		}
+		const document = runner.document(entries);
+		runner.commandOutput.emit(document);
+		if (!runner.isSuccessful()) {
 			process.exitCode = 1;
 			cancel("Some schema pushes failed — see above.");
 			return;
@@ -2043,8 +3031,92 @@ const migrationsCommand = defineCommand({
 	}
 });
 //#endregion
+//#region src/provision-json-document.ts
+/**
+* The stable codes of the `heximon provision --json` diagnostics. `--profile` uses `cli.invalid-options`,
+* and a missing credential uses `cli.option-required`.
+*/
+const ProvisionDiagnosticCode = {
+	/** The platform has no foundational resources to provision. */
+	Unsupported: "provision.unsupported",
+	/** One or more resources failed to provision; `result.failed` names them. */
+	Failed: "provision.failed",
+	/** No deploy strategy is installed for the platform. */
+	StrategyUnavailable: "provision.strategy-unavailable",
+	/** A Nitro or Nuxt build uses a preset that the deploy cannot ship. */
+	HostManagedUnsupported: "provision.host-managed-unsupported"
+};
+//#endregion
 //#region src/provision-command.ts
 /**
+* Builds the `heximon provision --json` document. The run fields are set as the run reaches them, so a
+* failure document still says how far the run got.
+*/
+var ProvisionDocument = class ProvisionDocument {
+	environment;
+	dryRun;
+	target;
+	credentials;
+	/**
+	* @param environment - The deploy environment.
+	* @param dryRun - Whether the run creates nothing.
+	*/
+	constructor(environment, dryRun) {
+		this.environment = environment;
+		this.dryRun = dryRun;
+	}
+	/** Record the resolved target. */
+	resolved(target) {
+		this.target = {
+			platform: target.platformName ?? "node",
+			targetClass: target.targetClass,
+			hostManaged: target.hostManaged === true,
+			...target.artifactDir === void 0 ? {} : { artifactDir: target.artifactDir }
+		};
+	}
+	/** Record the names of the resolved credential variables. */
+	resolvedCredentials(credentials) {
+		this.credentials = [...credentials.keys()];
+	}
+	/**
+	* The document of the run.
+	*
+	* @param ok - Whether the command exits 0.
+	* @param diagnostics - The diagnostics of the run.
+	* @param outcome - The provisioning outcome, once the run has one.
+	* @returns The document.
+	*/
+	document(ok, diagnostics, outcome) {
+		return {
+			ok,
+			diagnostics,
+			environment: this.environment,
+			dryRun: this.dryRun,
+			...this.target === void 0 ? {} : { target: this.target },
+			...this.credentials === void 0 ? {} : { credentials: this.credentials },
+			...outcome?.result === void 0 ? {} : { result: ProvisionDocument.resultOf(outcome.result) },
+			...outcome?.savedIds === void 0 ? {} : { savedIds: {
+				path: outcome.savedIds.path,
+				names: outcome.savedIds.names
+			} }
+		};
+	}
+	/** Copy the provisioning result into its document shape. */
+	static resultOf(result) {
+		return {
+			platform: result.platform,
+			provisioned: result.provisioned.map((provisioned) => ({
+				resource: provisioned.resource,
+				id: provisioned.id,
+				...provisioned.envVar === void 0 ? {} : { envVar: provisioned.envVar }
+			})),
+			existing: result.existing,
+			failed: result.failed,
+			messages: result.messages
+		};
+	}
+};
+/**
 * `heximon provision` — the PRE-BUILD verb for resources whose id the build itself needs (a Cloudflare
 * Hyperdrive binding with an empty `id` fails the build outright, and provisioning is what mints that id).
 * It calls exactly one seam, `strategy.provisionInfrastructure(context)` — never the deploy-time
@@ -2061,6 +3133,7 @@ const provisionCommand = defineCommand({
 			description: "Project root directory.",
 			default: "."
 		},
+		json: CommandOutput.jsonFlag,
 		env: {
 			type: "string",
 			description: "Deploy environment (production / staging / preview:<id>).",
@@ -2086,61 +3159,97 @@ const provisionCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const rootDir = resolve(process.cwd(), args.cwd);
-		const environment = args.env;
-		const interactive = CliEnvironment.isInteractive();
-		intro(`heximon provision · ${environment}`);
-		if (args.profile !== void 0) {
-			cancel("--profile is not supported by `heximon provision` — provisioning talks to the Cloudflare REST API with CLOUDFLARE_API_TOKEN, which a wrangler auth profile does not carry. Set the token instead.");
-			process.exitCode = 1;
-			return;
-		}
-		try {
-			const target = await DeployTargetResolver.resolve(rootDir, environment, args.platform);
-			log.info(`Platform: ${target.platformName ?? "node (default)"} · target class: ${target.targetClass}`);
-			const specs = CredentialSelection.inPlay(target.strategy.requiredCredentials(), { provisioning: true });
-			const credentials = await CredentialResolver.resolve(specs, {
-				interactive,
-				prompter: interactive ? new ClackPrompter() : void 0
-			});
-			const progress = CliSpinner.begin(interactive, args["dry-run"] === true ? "Previewing the foundational resources…" : "Provisioning foundational resources…");
-			let outcome;
-			try {
-				outcome = await DeployRunner.provisionInfrastructure({
-					target,
-					rootDir,
-					environment,
-					credentials,
-					dryRun: args["dry-run"],
-					saveIds: args["save-ids"]
-				});
-			} catch (provisionError) {
-				progress?.stop("Provisioning failed — see the error below.");
-				throw provisionError;
-			}
-			progress?.stop("Provision steps complete.");
-			if (outcome.unsupported) {
-				cancel(`Platform ${outcome.platformName ?? "node (default)"} has no foundational resources to provision.`);
+		const commandOutput = CommandOutput.resolve("provision", args);
+		await commandOutput.run(async () => {
+			const rootDir = ProjectRoot.resolve(args.cwd);
+			const environment = args.env;
+			const dryRun = args["dry-run"];
+			const interactive = commandOutput.isInteractive();
+			const report = new ProvisionDocument(environment, dryRun);
+			intro(`heximon provision · ${environment}`);
+			if (args.profile !== void 0) {
+				const message = "--profile is not supported by `heximon provision` — provisioning talks to the Cloudflare REST API with CLOUDFLARE_API_TOKEN, which a wrangler auth profile does not carry. Set the token instead.";
+				cancel(message);
 				process.exitCode = 1;
+				commandOutput.emit(report.document(false, [CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, message, { hint: "Remove --profile and set CLOUDFLARE_API_TOKEN." })]));
 				return;
 			}
-			const result = outcome.result;
-			for (const message of result?.messages ?? []) log.message(message);
-			for (const provisioned of result?.provisioned ?? []) log.success(`Provisioned ${provisioned.resource} → id ${provisioned.id}.`);
-			if (outcome.savedIds !== void 0) log.success(`Recorded ${outcome.savedIds.names.join(", ")} in ${outcome.savedIds.path} — \`heximon deploy\` injects it into the build.`);
-			if (result !== void 0 && result.failed.length > 0) {
-				process.exitCode = 1;
-				cancel(`Provisioning failed for: ${result.failed.join(", ")} — see above.`);
-				return;
+			try {
+				const target = await ConfigSidecar.during(rootDir, environment, () => DeployTargetResolver.resolve(rootDir, environment, args.platform));
+				report.resolved(target);
+				log.info(`Platform: ${target.platformName ?? "node (default)"} · target class: ${target.targetClass}`);
+				const specs = CredentialSelection.inPlay(target.strategy.requiredCredentials(), { provisioning: true });
+				const credentials = await CredentialResolver.resolve(specs, {
+					interactive: interactive || commandOutput.isJson(),
+					prompter: commandOutput.prompter(CredentialResolver.optionFor(specs))
+				});
+				report.resolvedCredentials(credentials);
+				const progress = CliSpinner.begin(interactive, dryRun ? "Previewing the foundational resources…" : "Provisioning foundational resources…");
+				let outcome;
+				try {
+					outcome = await DeployRunner.provisionInfrastructure({
+						target,
+						rootDir,
+						environment,
+						credentials,
+						dryRun,
+						saveIds: args["save-ids"]
+					});
+				} catch (provisionError) {
+					progress?.stop("Provisioning failed — see the error below.");
+					throw provisionError;
+				}
+				progress?.stop("Provision steps complete.");
+				if (outcome.unsupported) {
+					const message = `Platform ${outcome.platformName ?? "node (default)"} has no foundational resources to provision.`;
+					cancel(message);
+					process.exitCode = 1;
+					commandOutput.emit(report.document(false, [CliDiagnostics.error(ProvisionDiagnosticCode.Unsupported, message)], outcome));
+					return;
+				}
+				const result = outcome.result;
+				for (const message of result?.messages ?? []) log.message(message);
+				for (const provisioned of result?.provisioned ?? []) log.success(`Provisioned ${provisioned.resource} → id ${provisioned.id}.`);
+				if (outcome.savedIds !== void 0) log.success(`Recorded ${outcome.savedIds.names.join(", ")} in ${outcome.savedIds.path} — \`heximon deploy\` injects it into the build.`);
+				if (result !== void 0 && result.failed.length > 0) {
+					process.exitCode = 1;
+					cancel(`Provisioning failed for: ${result.failed.join(", ")} — see above.`);
+					commandOutput.emit(report.document(false, [CliDiagnostics.error(ProvisionDiagnosticCode.Failed, `Provisioning failed for: ${result.failed.join(", ")}.`, { hint: "The result messages name the cause for each resource." })], outcome));
+					return;
+				}
+				outro(outcome.savedIds !== void 0 ? "Provisioning complete — ids recorded in the deploy ledger; deploy when ready." : "Provisioning complete — record the ids above in your config, then deploy.");
+				commandOutput.emit(report.document(true, [], outcome));
+			} catch (error) {
+				if (DeployCommandFailure.report(error)) {
+					const diagnostic = DeployCommandFailure.diagnosticOf(error, ProvisionDiagnosticCode);
+					if (diagnostic !== void 0) commandOutput.emit(report.document(false, [diagnostic]));
+					return;
+				}
+				if (error instanceof CommandFailure && commandOutput.isJson()) {
+					commandOutput.emit(report.document(false, error.diagnostics));
+					return;
+				}
+				throw error;
 			}
-			outro(outcome.savedIds !== void 0 ? "Provisioning complete — ids recorded in the deploy ledger; deploy when ready." : "Provisioning complete — record the ids above in your config, then deploy.");
-		} catch (error) {
-			if (DeployCommandFailure.report(error)) return;
-			throw error;
-		}
+		});
 	}
 });
 //#endregion
+//#region src/routes-json-document.ts
+/** The stable codes of the failures `heximon routes` raises itself. */
+const RoutesDiagnosticCode = {
+	/** The compile threw before the command could read a route census. */
+	ReadFailed: "routes.read-failed",
+	/** `--boot` could not load or boot the app. A compile error of the boot gives the compiler diagnostics instead. */
+	BootFailed: "routes.boot-failed",
+	/** `--boot` booted the app, but its live route table could not be read. */
+	TableUnreadable: "routes.table-unreadable",
+	/** `--boot` read the route table, but the booted app did not dispose cleanly; a client can still be open. */
+	DisposeFailed: "routes.dispose-failed",
+	/** The `--out` file could not be written. */
+	OutWriteFailed: "routes.out-write-failed"
+};
+//#endregion
 //#region src/route-table-report.ts
 /**
 * Renders a {@link RouteCensusRow} list as an aligned, columnar route table for the terminal —
@@ -2228,18 +3337,39 @@ var TransformBoot = class TransformBoot {
 		return process.env[TransformBoot.transformMarker] === "1";
 	}
 	/**
+	* Re-run this exact CLI invocation under `node --experimental-transform-types`, and set the exit status of
+	* the child. The child prints the whole output, `--json` document included.
+	*
+	* A child that does not start printed nothing, so this process prints the failure: a document with
+	* {@link CliDiagnosticCode.ReexecFailed} under `--json` (also written to the `--out` file), else one stderr
+	* line. A child that a signal stops has no result, so it gets a stderr line and no document.
+	*
+	* @param commandLabel - The command name for the stderr lines (`routes --boot`, `task run`).
+	* @param commandOutput - The output owner of the run.
+	* @param outFile - The `--out` file of a command that has one.
+	*/
+	static async relaunch(commandLabel, commandOutput, outFile) {
+		const exit = await TransformBoot.reexecUnderTransform(commandLabel);
+		if (exit.startError === void 0) {
+			process.exitCode = exit.exitCode;
+			return;
+		}
+		const failure = CommandFailure.of(CliDiagnosticCode.ReexecFailed, `Could not start the child process that runs the app's TypeScript source (${process.execPath}): ` + exit.startError.message, "Check that this Node.js executable can run, then run the command again.");
+		const fail = () => Promise.reject(failure);
+		await commandOutput.run(() => outFile === void 0 ? fail() : outFile.run(fail));
+	}
+	/**
 	* Re-run this exact CLI invocation under `node --experimental-transform-types`, inheriting stdio so the
 	* child's output and prompts reach the terminal directly.
 	*
 	* The child owns an interrupt: a terminal sends Ctrl-C to both processes, and the child cleans up. A
 	* `SIGTERM` or `SIGHUP` that reaches only this process is passed on, so the child never outlives it.
 	*
-	* A child that never started, or that a signal killed, reports no exit code. Both become `1` — but they
-	* are NAMED on stderr first, because the child printed nothing of its own and a bare `exit 1` after a
-	* silent run reads as "the command found a problem" rather than "the command never ran".
+	* A child that a signal killed reports no exit code. It becomes `1`, NAMED on stderr first, because a bare
+	* `exit 1` after a silent run reads as "the command found a problem" rather than "the command was stopped".
 	*
-	* @param commandLabel - The command name for the failure messages (`routes --boot`, `task run`).
-	* @returns The child process exit code (1 when it did not report one).
+	* @param commandLabel - The command name for the stderr line of a stopped child.
+	* @returns The exit code of the child (1 when it did not report one), or the error of a child that did not start.
 	*/
 	static reexecUnderTransform(commandLabel) {
 		return new Promise((resolve) => {
@@ -2263,19 +3393,24 @@ var TransformBoot = class TransformBoot {
 				process.on(signal, forward);
 				return [signal, forward];
 			});
+			let settled = false;
 			process.on("SIGINT", ignoreInterrupt);
-			const finish = (code) => {
+			const finish = (exit) => {
+				if (settled) return;
+				settled = true;
 				process.off("SIGINT", ignoreInterrupt);
 				for (const [signal, forward] of forwarded) process.off(signal, forward);
-				resolve(code);
+				resolve(exit);
 			};
 			child.once("error", (error) => {
-				process.stderr.write(`heximon ${commandLabel}: could not start the transform-enabled child (${process.execPath}): ${error.message}\n`);
-				finish(1);
+				if (child.pid === void 0) finish({
+					exitCode: 1,
+					startError: error
+				});
 			});
 			child.once("close", (code, signal) => {
-				if (signal !== null) process.stderr.write(`heximon ${commandLabel}: the transform-enabled child was killed by ${signal}.\n`);
-				finish(code ?? 1);
+				if (signal !== null && !settled) process.stderr.write(`heximon ${commandLabel}: the transform-enabled child was killed by ${signal}.\n`);
+				finish({ exitCode: code ?? 1 });
 			});
 		});
 	}
@@ -2397,14 +3532,10 @@ const routesCommand = defineCommand({
 			description: "The `.env.<mode>` overlay to load first; also the config `$env`. Default development.",
 			default: "development"
 		},
-		json: {
-			type: "boolean",
-			description: "Emit the route table as JSON on stdout instead of a table.",
-			default: false
-		},
+		json: CommandOutput.jsonFlag,
 		out: {
 			type: "string",
-			description: "Write the JSON payload to this file instead of stdout, creating missing parent directories — the CI-artifact target."
+			description: "Also write the JSON document to this file, creating missing parent directories — the CI-artifact target."
 		},
 		boot: {
 			type: "boolean",
@@ -2420,24 +3551,27 @@ const routesCommand = defineCommand({
 	},
 	async run({ args }) {
 		const asBoot = args.boot;
+		const commandOutput = CommandOutput.resolve("routes", args);
+		const outFile = JsonOutputTarget.resolve(args.out);
 		if (asBoot && !TransformBoot.isBootProcess()) {
-			process.exitCode = await TransformBoot.reexecUnderTransform("routes --boot");
-			return;
-		}
-		const rootDir = resolve(process.cwd(), args.cwd);
-		const asJson = args.json;
-		const jsonOutput = JsonOutputTarget.resolve(args.out, asJson);
-		const resolved = CompileModeResolver.resolve("routes", rootDir, args, SourceDirectories.resolve(rootDir, args.src));
-		if (resolved === void 0) return;
-		if (!asJson) intro(`heximon routes — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
-		if (asBoot) {
-			await RoutesCommand.runBoot(rootDir, args, asJson, jsonOutput);
+			if (await ProjectRoot.checkBeforeRelaunch(args.cwd, commandOutput)) await TransformBoot.relaunch("routes --boot", commandOutput, outFile);
 			return;
 		}
-		await RoutesCommand.runCompile(rootDir, args, asJson, jsonOutput, resolved.mode);
+		await commandOutput.run(async () => {
+			const rootDir = ProjectRoot.resolve(args.cwd);
+			await outFile.run(async () => {
+				const resolved = CompileModeResolver.resolve(rootDir, args, SourceDirectories.resolve(rootDir, args.src));
+				if (!commandOutput.isJson()) intro(`heximon routes — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
+				if (asBoot) {
+					await RoutesCommand.runBoot(rootDir, args, commandOutput, outFile);
+					return;
+				}
+				await RoutesCommand.runCompile(rootDir, args, commandOutput, outFile, resolved.mode);
+			});
+		});
 	}
 });
-/** Output helpers for {@link routesCommand}: the two read paths, the table / JSON body, and the failure summary. */
+/** Output helpers for {@link routesCommand}: the two read paths, the table / JSON document, and the failure summary. */
 var RoutesCommand = class RoutesCommand {
 	/**
 	* The compile-time read: run the same from-disk compile `heximon check` runs and report the route census
@@ -2449,8 +3583,8 @@ var RoutesCommand = class RoutesCommand {
 	* route table is readable without composing it into an app. The `requires` a library leaves open for its
 	* host are not diagnostics there, so nothing floods the report.
 	*/
-	static async runCompile(rootDir, args, asJson, jsonOutput, mode = CompileMode.App) {
-		let census;
+	static async runCompile(rootDir, args, commandOutput, outFile, mode = CompileMode.App) {
+		let compiled;
 		try {
 			const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
 			DotenvCascade.loadInto(rootDir, args.env);
@@ -2459,24 +3593,21 @@ var RoutesCommand = class RoutesCommand {
 				environment: args.env,
 				...sourceDirectories === void 0 ? {} : { sourceDirectories }
 			});
-			const output = mode === CompileMode.Library ? session.compileLibrary() : session.compile();
-			const failure = output.diagnostics.find((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error);
-			if (failure !== void 0) {
-				RoutesCommand.reportFailure(new Error(failure.message), asJson, jsonOutput);
-				process.exitCode = 1;
-				return;
-			}
-			const file = output.files.find((generated) => generated.path === RouteCensus.fileName);
-			census = (file === void 0 ? void 0 : RouteCensus.parse(file.content)) ?? {
-				routes: [],
-				unresolved: []
-			};
+			compiled = mode === CompileMode.Library ? session.compileLibrary() : session.compile();
 		} catch (error) {
-			RoutesCommand.reportFailure(error, asJson, jsonOutput);
-			process.exitCode = 1;
+			RoutesCommand.reportFailure(RoutesCommand.diagnosticsOf(RoutesDiagnosticCode.ReadFailed, error), commandOutput, outFile);
 			return;
 		}
-		RoutesCommand.report(census.routes, census.unresolved, asJson, jsonOutput, {
+		if (compiled.diagnostics.some((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error)) {
+			RoutesCommand.reportFailure(CliDiagnostics.fromCompiler(compiled.diagnostics), commandOutput, outFile);
+			return;
+		}
+		const file = compiled.files.find((generated) => generated.path === RouteCensus.fileName);
+		const census = (file === void 0 ? void 0 : RouteCensus.parse(file.content)) ?? {
+			routes: [],
+			unresolved: []
+		};
+		RoutesCommand.report(census.routes, census.unresolved, commandOutput, outFile, {
 			libraryMode: mode === CompileMode.Library,
 			...census.scopeEnforcement === void 0 ? {} : { scopeEnforcement: census.scopeEnforcement }
 		});
@@ -2494,17 +3625,19 @@ var RoutesCommand = class RoutesCommand {
 	* subcommand thunk while building the completion tree, so citty's lazy `Resolvable` form resolves the
 	* module anyway.
 	*/
-	static async runBoot(rootDir, args, asJson, jsonOutput) {
+	static async runBoot(rootDir, args, commandOutput, outFile) {
 		let app;
 		let inventory;
+		let testing;
 		try {
 			TransformBoot.registerSourceResolver();
 			const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
 			DotenvCascade.loadInto(rootDir, args.env);
-			const config = await ConfigLoader.load(rootDir, args.env);
-			const [{ createTestApp: bootApp }, { RouteInventory }] = await Promise.all([import("@heximon/testing"), import("@heximon/http")]);
+			const config = await ConfigSidecar.load(rootDir, args.env);
+			const [testingModule, { RouteInventory }] = await Promise.all([import("@heximon/testing"), import("@heximon/http")]);
+			testing = testingModule;
 			inventory = RouteInventory;
-			app = await bootApp({
+			app = await testingModule.createTestApp({
 				root: rootDir,
 				printWarnings: false,
 				...sourceDirectories === void 0 ? {} : { sourceDirectories },
@@ -2513,25 +3646,28 @@ var RoutesCommand = class RoutesCommand {
 				...config?.platform === void 0 ? {} : { platform: config.platform }
 			});
 		} catch (error) {
-			RoutesCommand.reportFailure(error, asJson, jsonOutput);
-			process.exitCode = 1;
+			RoutesCommand.reportFailure(testing !== void 0 && error instanceof testing.TestAppCompileError ? CliDiagnostics.fromCompiler(error.diagnostics) : RoutesCommand.diagnosticsOf(RoutesDiagnosticCode.BootFailed, error), commandOutput, outFile);
 			return;
 		}
+		let routes;
+		const failures = [];
 		try {
-			const routes = inventory.describe(app).map(RoutesCommand.toCensusRow);
-			RoutesCommand.report(routes, [], asJson, jsonOutput);
+			routes = inventory.describe(app).map(RoutesCommand.toCensusRow);
 		} catch (error) {
-			RoutesCommand.reportFailure(error, asJson, jsonOutput);
-			process.exitCode = 1;
+			failures.push(RoutesCommand.diagnosticOf(RoutesDiagnosticCode.TableUnreadable, error));
 		} finally {
 			try {
 				await app.context.drain({ timeoutMs: 5e3 });
 				await app[Symbol.asyncDispose]();
 			} catch (disposeError) {
-				process.exitCode = 1;
-				if (!asJson) log.warn(`The route table was read, but disposing the booted app failed — a client may still be open: ${disposeError instanceof Error ? disposeError.message : String(disposeError)}`);
+				failures.push(CliDiagnostics.error(RoutesDiagnosticCode.DisposeFailed, `Disposing the booted app failed — a client may still be open: ${disposeError instanceof Error ? disposeError.message : String(disposeError)}`));
 			}
 		}
+		if (routes === void 0) {
+			RoutesCommand.reportFailure(failures, commandOutput, outFile);
+			return;
+		}
+		RoutesCommand.report(routes, [], commandOutput, outFile, { failures });
 	}
 	/**
 	* Map one booted route to a census row. An entry whose {@link RouteInventoryEntry.scopes} is defined (every
@@ -2549,23 +3685,29 @@ var RoutesCommand = class RoutesCommand {
 		};
 	}
 	/**
-	* Print the resolved routes — the JSON payload to its target, and an aligned table unless `--json`.
+	* Report the resolved routes: the JSON document to stdout under `--json` and to the `--out` file, and an
+	* aligned table unless `--json`. A failure or a failed `--out` write sets exit status 1.
 	*
 	* @param options - `libraryMode` adds the one fact a package's own table cannot show: the published root's
 	*   default mount is a manifest fact a consuming host applies or replaces, so it is not folded into these
-	*   paths. `scopeEnforcement` is the census section of the same name, passed through to the JSON payload
-	*   so a CI job reads the scope-enforcer verdict from the same artifact.
+	*   paths. `scopeEnforcement` is the census section of the same name, passed through to the JSON document
+	*   so a CI job reads the scope-enforcer verdict from the same artifact. `failures` are errors that fail
+	*   the run but keep the table it read.
 	*/
-	static report(routes, unresolved, asJson, jsonOutput, options = {}) {
-		const written = jsonOutput.emit({
-			ok: true,
+	static report(routes, unresolved, commandOutput, outFile, options = {}) {
+		const failures = options.failures ?? [];
+		const document = {
+			ok: failures.length === 0,
+			diagnostics: failures,
 			routes,
 			unresolved,
 			...options.scopeEnforcement === void 0 ? {} : { scopeEnforcement: options.scopeEnforcement }
-		});
-		if (!written) process.exitCode = 1;
-		if (asJson) return;
-		if (written && jsonOutput.isFile()) log.success(`Route JSON written to ${jsonOutput.filePath}.`);
+		};
+		const written = outFile.publish(document, commandOutput, RoutesDiagnosticCode.OutWriteFailed);
+		if (!written || failures.length > 0) process.exitCode = 1;
+		if (commandOutput.isJson()) return;
+		if (written && outFile.isFile()) log.success(`Route JSON written to ${outFile.filePath}.`);
+		for (const failure of failures) log.warn(failure.message);
 		if (routes.length === 0 && unresolved.length === 0) {
 			outro(options.libraryMode === true ? "No HTTP routes — this package serves none, or its HTTP plugin is not active." : "No HTTP routes — this app serves none, or its HTTP plugin is not active.");
 			return;
@@ -2580,20 +3722,34 @@ var RoutesCommand = class RoutesCommand {
 		outro(`${routes.length} route${routes.length === 1 ? "" : "s"}; ${unresolved.length} unresolved` + (options.libraryMode === true ? "." : " — re-run with --boot to enumerate them."));
 	}
 	/**
-	* Report a compile / boot failure: `{ ok: false, error }` to the JSON target, and a clack error + outro
-	* unless `--json`. The failure payload goes to `--out` too, so re-running replaces the previous artifact
-	* rather than leaving a stale success; a failed write is treated exactly as on the success path.
+	* Report a compile / boot failure: a {@link CliFailureDocument} to stdout under `--json` and to the `--out`
+	* file, and a clack error + outro unless `--json`. The file gets the failure too, so a new run
+	* replaces the previous artifact rather than leaving a stale success. Sets exit status 1.
+	*
+	* @param diagnostics - The diagnostics of the failure: the compiler's, or one the command raised.
+	* @param commandOutput - The stdout owner of the run.
+	* @param outFile - The `--out` file.
 	*/
-	static reportFailure(error, asJson, jsonOutput) {
-		const message = error instanceof Error ? error.message : String(error);
-		if (!jsonOutput.emit({
+	static reportFailure(diagnostics, commandOutput, outFile) {
+		const document = {
 			ok: false,
-			error: message
-		})) process.exitCode = 1;
-		if (asJson) return;
-		log.error(`Could not read the app's routes:\n${message}`);
+			diagnostics
+		};
+		outFile.publish(document, commandOutput, RoutesDiagnosticCode.OutWriteFailed);
+		process.exitCode = 1;
+		if (commandOutput.isJson()) return;
+		const messages = diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error).map((diagnostic) => diagnostic.message);
+		log.error(`Could not read the app's routes:\n${messages.join("\n")}`);
 		outro("No route table to show.");
 	}
+	/** One error diagnostic of the command, with the message of what was thrown. */
+	static diagnosticOf(code, error) {
+		return CliDiagnostics.error(code, error instanceof Error ? error.message : String(error));
+	}
+	/** The diagnostics of a thrown value: those of a {@link CommandFailure}, else one with `code`. */
+	static diagnosticsOf(code, error) {
+		return error instanceof CommandFailure ? error.diagnostics : [RoutesCommand.diagnosticOf(code, error)];
+	}
 	/**
 	* The unresolved-gap block: one line per controller (or package) whose routes the census could not name.
 	* A composed package whose manifest section IS readable contributes rows instead, so nothing here is a
@@ -3460,38 +4616,52 @@ var PlatformBindingCensus = class PlatformBindingCensus {
 	}
 };
 //#endregion
-//#region src/stdout-redirect.ts
-/**
-* Sends everything written to stdout to stderr for a while, so the log lines of an app that runs in this
-* process cannot mix with the JSON the command prints. The original writer stays reachable through
-* {@link write} for that JSON.
-*/
-var StdoutRedirect = class {
-	original;
-	/** Start the redirect. A second call does nothing. */
-	start() {
-		if (this.original !== void 0) return;
-		this.original = process.stdout.write.bind(process.stdout);
-		process.stdout.write = ((...parameters) => process.stderr.write(...parameters));
-	}
-	/** Write to the real stdout, redirected or not. */
-	write(text) {
-		(this.original ?? process.stdout.write.bind(process.stdout))(text);
-	}
-	/** Stop the redirect. */
-	stop() {
-		if (this.original !== void 0) {
-			process.stdout.write = this.original;
-			this.original = void 0;
-		}
-	}
+//#region src/task-run-json-document.ts
+/** The stable codes of the failures `heximon task run --json` reports. */
+const TaskDiagnosticCode = {
+	/** The `run()` of the task threw. The run exits 2, and the document names the error. */
+	TaskFailed: "task.failed",
+	/** No module or no task of the compiled graph has the name, or the source file does not export the class. */
+	TargetNotFound: "task.target-not-found",
+	/** More than one module, or more than one task of the module, has the name. */
+	TargetAmbiguous: "task.target-ambiguous",
+	/** The named class has no `run()` method. */
+	NotATask: "task.not-a-task",
+	/** The production compile failed. The compiler diagnostics are in the same document. */
+	CompileFailed: "task.compile-failed",
+	/** The project has no app: the compile gave no module graph, or no wiring file. */
+	AppNotFound: "task.app-not-found",
+	/** A Nitro option is computed, so the command cannot read the preset or the source directories. */
+	NitroConfigComputed: "task.nitro-config-computed",
+	/** A packed library that the app imports does not have the factories a production build needs. */
+	LibraryPreflightFailed: "task.library-preflight-failed",
+	/** The graph needs bindings that only its platform has, so nothing was booted. */
+	PlatformBindingsRequired: "task.platform-bindings-required",
+	/** The `@heximon/runtime` of the project is older than the command. */
+	RuntimeOutdated: "task.runtime-outdated",
+	/** The app did not boot. The stack is on stderr. */
+	BootFailed: "task.boot-failed",
+	/** The app could not create the task. */
+	CreateFailed: "task.create-failed",
+	/** The frame of the task did not open, or a context seed threw before `run()`. */
+	StartFailed: "task.start-failed",
+	/** The task returned a value that is not JSON. */
+	ResultNotJson: "task.result-not-json",
+	/** The app did not shut down cleanly after the run. */
+	ShutdownFailed: "task.shutdown-failed"
 };
 //#endregion
 //#region src/task-target-resolver.ts
 /** Thrown when the names do not pick exactly one module and one task. The message is ready to print. */
 var TaskTargetError = class extends Error {
-	constructor(message) {
+	code;
+	/**
+	* @param code - {@link TaskDiagnosticCode.TargetNotFound} or {@link TaskDiagnosticCode.TargetAmbiguous}.
+	* @param message - The reason, with the names that come close.
+	*/
+	constructor(code, message) {
 		super(message);
+		this.code = code;
 		this.name = "TaskTargetError";
 	}
 };
@@ -3517,16 +4687,16 @@ var TaskTargetResolver = class TaskTargetResolver {
 	static resolve(graph, moduleName, taskName, boundaries = []) {
 		const moduleReferences = [...graph.modules.map((node) => node.reference), ...boundaries.map((boundary) => boundary.reference)];
 		const modules = TaskTargetResolver.distinct(moduleReferences, moduleName);
-		if (modules.length === 0) throw new TaskTargetError(`No module class named "${moduleName}" is in the compiled graph.` + TaskTargetResolver.suggestions(moduleName, moduleReferences.map((reference) => TaskTargetResolver.nameOf(reference)), "Modules in the graph"));
-		if (modules.length > 1) throw new TaskTargetError(`More than one module class is named "${moduleName}":\n` + modules.map((reference) => `  - ${reference.sourceFile}`).join("\n"));
+		if (modules.length === 0) throw new TaskTargetError(TaskDiagnosticCode.TargetNotFound, `No module class named "${moduleName}" is in the compiled graph.` + TaskTargetResolver.suggestions(moduleName, moduleReferences.map((reference) => TaskTargetResolver.nameOf(reference)), "Modules in the graph"));
+		if (modules.length > 1) throw new TaskTargetError(TaskDiagnosticCode.TargetAmbiguous, `More than one module class is named "${moduleName}":\n` + modules.map((reference) => `  - ${reference.sourceFile}`).join("\n"));
 		const module = modules[0];
 		const nodes = graph.modules.filter((node) => TaskTargetResolver.isSame(node.reference, module));
 		const libraries = boundaries.filter((boundary) => TaskTargetResolver.isSame(boundary.reference, module));
 		const isLibrary = nodes.length === 0 && libraries.length > 0;
 		const candidates = isLibrary ? libraries.flatMap((boundary) => boundary.exports.map((exported) => exported.token)) : nodes.flatMap((node) => node.providers.map((provider) => provider.token));
 		const tasks = TaskTargetResolver.distinct(candidates, taskName);
-		if (tasks.length === 0) throw new TaskTargetError((isLibrary ? `The library module ${moduleName} does not export a class named "${taskName}". \`heximon task run\` reaches the tasks that a library module exports: export the task from the module and pack the library again.` : `The module ${moduleName} does not provide a class named "${taskName}".`) + TaskTargetResolver.otherOwner(graph, boundaries, module, taskName) + TaskTargetResolver.suggestions(taskName, candidates.map((token) => TaskTargetResolver.nameOf(token)), isLibrary ? `Exports of ${moduleName}` : `Providers of ${moduleName}`));
-		if (tasks.length > 1) throw new TaskTargetError(`The module ${moduleName} ${isLibrary ? "exports" : "provides"} more than one class named "${taskName}":\n` + tasks.map((reference) => `  - ${reference.sourceFile}`).join("\n"));
+		if (tasks.length === 0) throw new TaskTargetError(TaskDiagnosticCode.TargetNotFound, (isLibrary ? `The library module ${moduleName} does not export a class named "${taskName}". \`heximon task run\` reaches the tasks that a library module exports: export the task from the module and pack the library again.` : `The module ${moduleName} does not provide a class named "${taskName}".`) + TaskTargetResolver.otherOwner(graph, boundaries, module, taskName) + TaskTargetResolver.suggestions(taskName, candidates.map((token) => TaskTargetResolver.nameOf(token)), isLibrary ? `Exports of ${moduleName}` : `Providers of ${moduleName}`));
+		if (tasks.length > 1) throw new TaskTargetError(TaskDiagnosticCode.TargetAmbiguous, `The module ${moduleName} ${isLibrary ? "exports" : "provides"} more than one class named "${taskName}":\n` + tasks.map((reference) => `  - ${reference.sourceFile}`).join("\n"));
 		return {
 			module,
 			task: tasks[0]
@@ -3687,8 +4857,25 @@ var RefusingInternalClient = class {
 		return Promise.reject(/* @__PURE__ */ new Error(`InternalClient.fetch(${JSON.stringify(input)}) is not available in \`heximon task run\`: the run boots no HTTP surface, so a task cannot call the app's own routes.`));
 	}
 };
-/** The failure a run reports to the caller; the message is ready to print. */
-var TaskRunFailure = class extends Error {};
+/** The failure a run reports to the caller; the message is ready to print on stderr. */
+var TaskRunFailure = class extends Error {
+	code;
+	/** The one-paragraph text of the `--json` diagnostic: the message without a stack trace. */
+	summary;
+	/** How to fix the failure, or where to read more. */
+	hint;
+	/**
+	* @param code - The stable code of the `--json` diagnostic.
+	* @param message - The text for stderr.
+	* @param details - The thrown value, the diagnostic text when it differs from the message, and the hint.
+	*/
+	constructor(code, message, details = {}) {
+		super(message, "cause" in details ? { cause: details.cause } : void 0);
+		this.code = code;
+		this.summary = details.summary ?? message;
+		this.hint = details.hint;
+	}
+};
 /** The task itself threw. The message is ready to print, and the thrown value is the cause. */
 var TaskRefusal = class extends TaskRunFailure {};
 /**
@@ -3710,6 +4897,8 @@ var TaskRunner = class TaskRunner {
 	static interruptShutdownMilliseconds = 5e3;
 	/** The exit code of a run whose task itself threw. Every other failure exits with `1`. */
 	static refusalExitCode = 2;
+	/** The hint of a diagnostic whose full text, with the stack trace, is on stderr. */
+	static stackHint = "The stack trace is on stderr.";
 	static wiringFilePattern = /^apps\/.+\.wiring\.js$/;
 	outputDirectory;
 	app;
@@ -3726,6 +4915,10 @@ var TaskRunner = class TaskRunner {
 	stdout = new StdoutRedirect();
 	/** The result of the task as one line of JSON, printed after the shutdown. */
 	serialized;
+	/** The diagnostics of the compile, for the `--json` document. */
+	compileDiagnostics = [];
+	/** Why the shutdown failed, when it failed. */
+	shutdownFailure;
 	disposing;
 	/** How many package specifiers the run imported, for the file names of {@link ProjectModules.import}. */
 	packageImports = 0;
@@ -3733,13 +4926,31 @@ var TaskRunner = class TaskRunner {
 		this.options = options;
 	}
 	/**
-	* Run the task.
+	* Run the task and print the text output. Everything the app logs goes to stderr: stdout carries the result
+	* alone.
 	*
 	* @returns The process exit code: `0` when the task returned, `2` when the task itself threw (stdout then
 	*   holds one `{"error":{"name":…,"message":…}}` line), `1` for every other outcome. The reason is already
 	*   on stderr.
 	*/
 	async run() {
+		let outcome;
+		this.stdout.start();
+		try {
+			outcome = await this.perform();
+		} finally {
+			this.stdout.stop();
+		}
+		if (outcome.line !== void 0) this.stdout.write(`${outcome.line}\n`);
+		return outcome.exitCode;
+	}
+	/**
+	* Run the task without a write to stdout. The caller sends stdout to stderr for the run, because the app
+	* and the host log there; the reason of a failure is already on stderr when this returns.
+	*
+	* @returns The exit code, the text line, and the `--json` document of the run.
+	*/
+	async perform() {
 		let interrupts = 0;
 		const interrupt = (signal) => {
 			interrupts += 1;
@@ -3748,35 +4959,69 @@ var TaskRunner = class TaskRunner {
 		process.on("SIGINT", interrupt);
 		process.on("SIGTERM", interrupt);
 		let exitCode = 0;
-		this.stdout.start();
+		const diagnostics = [];
+		let thrown;
 		try {
 			this.outputDirectory = mkdtempSync(join(this.options.rootDir, TaskRunner.outputDirectoryPrefix));
-			this.runtime = await TaskRunner.projectRuntime(this.outputDirectory);
-			const output = await this.compile();
+			this.runtime = await TaskRunner.during(TaskDiagnosticCode.BootFailed, () => TaskRunner.projectRuntime(this.outputDirectory));
+			const output = await TaskRunner.during(TaskDiagnosticCode.CompileFailed, () => this.compile());
 			const target = this.pickTarget(output);
 			TaskRunner.refuseBindings(output, this.platformName, this.outputDirectory);
 			this.materialize(output);
-			await this.boot(output);
-			await this.execute(target);
+			await TaskRunner.during(TaskDiagnosticCode.BootFailed, () => this.boot(output));
+			await this.runTask(target);
 		} catch (error) {
 			TaskRunner.report(error);
+			diagnostics.push(...TaskRunner.diagnosticsOf(error));
 			if (error instanceof TaskRefusal) {
 				exitCode = TaskRunner.refusalExitCode;
-				this.serialized = TaskRunner.errorLine(error.cause);
+				thrown = TaskRunner.errorOf(error.cause);
+				this.serialized = JSON.stringify({ error: thrown });
 			} else exitCode = 1;
 		} finally {
 			if (!await this.dispose() && exitCode === 0) exitCode = 1;
-			this.stdout.stop();
-			if (this.serialized !== void 0) this.stdout.write(`${this.serialized}\n`);
 			process.off("SIGINT", interrupt);
 			process.off("SIGTERM", interrupt);
 		}
-		return exitCode;
+		if (this.shutdownFailure !== void 0) diagnostics.push(CliDiagnostics.error(TaskDiagnosticCode.ShutdownFailed, this.shutdownFailure));
+		return {
+			exitCode,
+			...this.serialized === void 0 ? {} : { line: this.serialized },
+			document: {
+				ok: exitCode === 0,
+				diagnostics: [...this.compileDiagnostics, ...diagnostics],
+				module: this.options.moduleName,
+				task: this.options.taskName,
+				...thrown === void 0 ? TaskRunner.resultField(this.serialized) : { error: thrown }
+			}
+		};
+	}
+	/**
+	* Run one step of the run. A failure the step does not name itself becomes a {@link TaskRunFailure} with
+	* `code`; its stderr text stays the stack trace of the thrown value.
+	*/
+	static async during(code, step) {
+		try {
+			return await step();
+		} catch (error) {
+			if (error instanceof TaskRunFailure || error instanceof TaskTargetError || error instanceof CommandFailure) throw error;
+			throw new TaskRunFailure(code, TaskRunner.describe(error), {
+				cause: error,
+				summary: TaskRunner.messageOf(error),
+				hint: TaskRunner.stackHint
+			});
+		}
+	}
+	/** The `result` field of the document, read back from the printed result so both outputs agree. */
+	static resultField(serialized) {
+		if (serialized === void 0) return {};
+		const parsed = JSON.parse(serialized);
+		return typeof parsed === "object" && parsed !== null && "result" in parsed ? { result: parsed.result } : {};
 	}
 	/** The `@heximon/runtime` of the project, the copy the generated wiring imports. */
 	static async projectRuntime(directory) {
 		const runtime = await ProjectModules.runtime(directory);
-		if (typeof runtime.StandingWork?.suspend !== "function") throw new TaskRunFailure("The @heximon/runtime of this project is older than this command. Update @heximon/runtime and heximon to one version.");
+		if (typeof runtime.StandingWork?.suspend !== "function") throw new TaskRunFailure(TaskDiagnosticCode.RuntimeOutdated, "The @heximon/runtime of this project is older than this command. Update @heximon/runtime and heximon to one version.");
 		return runtime;
 	}
 	/**
@@ -3796,13 +5041,13 @@ var TaskRunner = class TaskRunner {
 		if (nitro.isNitroHost) {
 			const sourceDirectories = TaskRunner.sourceDirectoriesOf(nitro, this.options.isSourceExplicit === true ? this.options.sourceDirectories ?? [] : void 0);
 			const preset = nitro.preset;
-			const host = await NitroHost.open(rootDir, outputDirectory, {
+			const host = await ConfigSidecar.during(rootDir, "production", () => NitroHost.open(rootDir, outputDirectory, {
 				preset: preset.kind === "literal" ? preset.value : void 0,
 				platformFromSidecar: preset.kind === "computed",
 				aliases: this.aliases,
 				...sourceDirectories
-			});
-			if (preset.kind === "computed" && !host.hasSidecarPlatform()) throw new TaskRunFailure(`The Nitro preset is computed (${preset.reason}, in ${preset.file}), and the command does not run your config files, so it cannot read the platform: declare \`platform\` in heximon.config.ts (for example \`platform: new CloudflareWorkersStrategy()\`), or set NITRO_PRESET. Nothing was booted.`);
+			}));
+			if (preset.kind === "computed" && !host.hasSidecarPlatform()) throw new TaskRunFailure(TaskDiagnosticCode.NitroConfigComputed, `The Nitro preset is computed (${preset.reason}, in ${preset.file}), and the command does not run your config files, so it cannot read the platform: declare \`platform\` in heximon.config.ts (for example \`platform: new CloudflareWorkersStrategy()\`), or set NITRO_PRESET. Nothing was booted.`);
 			const compiled = host.compile(rootDir, outputDirectory, this.options.isSourceExplicit === true ? this.options.sourceDirectories : void 0);
 			({output, compiler} = compiled);
 			this.platformName = compiled.platformName;
@@ -3817,10 +5062,13 @@ var TaskRunner = class TaskRunner {
 			compiler = session.compiler;
 		}
 		const errors = output.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error);
-		if (output.diagnostics.length > 0) CompileDiagnostics.renderToStderr(rootDir, output.diagnostics);
-		if (errors.length > 0) throw new TaskRunFailure(`The production graph has ${errors.length} compile error${errors.length === 1 ? "" : "s"}. Nothing was booted.`);
+		if (output.diagnostics.length > 0) {
+			CompileDiagnostics.renderToStderr(rootDir, output.diagnostics);
+			this.compileDiagnostics = CliDiagnostics.fromCompiler(output.diagnostics);
+		}
+		if (errors.length > 0) throw new TaskRunFailure(TaskDiagnosticCode.CompileFailed, `The production graph has ${errors.length} compile error${errors.length === 1 ? "" : "s"}. Nothing was booted.`);
 		const findings = LibraryFactoryPreflight.inspect(compiler.consumedBoundaryPackages(), LibraryFactoryPreflight.productionBuildOptions);
-		if (findings.length > 0) throw new TaskRunFailure(LibraryFactoryPreflight.explain(findings));
+		if (findings.length > 0) throw new TaskRunFailure(TaskDiagnosticCode.LibraryPreflightFailed, LibraryFactoryPreflight.explain(findings));
 		return output;
 	}
 	/**
@@ -3829,7 +5077,7 @@ var TaskRunner = class TaskRunner {
 	*/
 	static sourceDirectoriesOf(nitro, explicit) {
 		if (explicit !== void 0) return { scanDirs: explicit };
-		for (const [name, value] of [["serverDir", nitro.serverDir], ["scanDirs", nitro.scanDirs]]) if (value.kind === "computed") throw new TaskRunFailure(`The Nitro \`${name}\` is computed (${value.reason}, in ${value.file}), and the command does not run your config files, so it cannot read the source directories. Name them with \`--src <dir>\` (repeat the option, or separate directories with commas). Nothing was booted.`);
+		for (const [name, value] of [["serverDir", nitro.serverDir], ["scanDirs", nitro.scanDirs]]) if (value.kind === "computed") throw new TaskRunFailure(TaskDiagnosticCode.NitroConfigComputed, `The Nitro \`${name}\` is computed (${value.reason}, in ${value.file}), and the command does not run your config files, so it cannot read the source directories. Name them with \`--src <dir>\` (repeat the option, or separate directories with commas). Nothing was booted.`);
 		return {
 			...nitro.serverDir.kind === "literal" ? { serverDir: nitro.serverDir.value } : {},
 			...nitro.scanDirs.kind === "literal" ? { scanDirs: nitro.scanDirs.value } : {}
@@ -3837,13 +5085,13 @@ var TaskRunner = class TaskRunner {
 	}
 	/** Pick the module and the task from the compiled graph. */
 	pickTarget(output) {
-		if (output.moduleGraph === void 0) throw new TaskRunFailure("The compile produced no module graph, so the task cannot be found.");
+		if (output.moduleGraph === void 0) throw new TaskRunFailure(TaskDiagnosticCode.AppNotFound, "The compile produced no module graph, so the task cannot be found.");
 		return TaskTargetResolver.resolve(output.moduleGraph, this.options.moduleName, this.options.taskName, output.boundaryNodes);
 	}
 	/** Refuse a graph that needs bindings only its platform has, before anything boots. */
 	static refuseBindings(output, platformName, outputDirectory) {
 		const needs = PlatformBindingCensus.collect(output, platformName, outputDirectory);
-		if (needs.length > 0) throw new TaskRunFailure(PlatformBindingCensus.explain(needs, platformName));
+		if (needs.length > 0) throw new TaskRunFailure(TaskDiagnosticCode.PlatformBindingsRequired, PlatformBindingCensus.explain(needs, platformName));
 	}
 	/** Write the generated files into the temporary directory. */
 	materialize(output) {
@@ -3856,7 +5104,7 @@ var TaskRunner = class TaskRunner {
 	/** Boot the app with no HTTP surface and without the standing work of the deployed app. */
 	async boot(output) {
 		const wiring = output.files.find((file) => TaskRunner.wiringFilePattern.test(file.path));
-		if (wiring === void 0) throw new TaskRunFailure("No app wiring file was generated. Make sure the project has a root module (a module that no other module imports).");
+		if (wiring === void 0) throw new TaskRunFailure(TaskDiagnosticCode.AppNotFound, "No app wiring file was generated. Make sure the project has a root module (a module that no other module imports).");
 		const runtime = this.runtime;
 		if (TransformBoot.isBootProcess()) TransformBoot.registerSourceResolver(new Map(output.sourceRewrites.map((rewrite) => [rewrite.filePath, rewrite.content])), this.aliases);
 		runtime.StandingWork.suspend(runtime.StandingWork.kinds().filter((kind) => !(this.options.withOutboxRelay && kind === runtime.StandingWorkKind.OutboxRelay)));
@@ -3876,17 +5124,17 @@ var TaskRunner = class TaskRunner {
 		this.app = await wiringModule.createApp(bindings);
 		this.context = await this.app.from(runtime.CoreModule).get(runtime.Context);
 	}
-	/** Run the task and print its result. */
-	async execute(target) {
+	/** Run the task and keep its result as one line of JSON. */
+	async runTask(target) {
 		const runtime = this.runtime;
 		const moduleClass = await this.importClass(target.module.sourceFile, target.module.className);
 		const taskClass = await this.importClass(target.task.sourceFile, target.task.className);
-		if (typeof taskClass.prototype.run !== "function") throw new TaskRunFailure(`${this.options.taskName} is not a task: the class has no run() method. A task extends Task.`);
+		if (typeof taskClass.prototype.run !== "function") throw new TaskRunFailure(TaskDiagnosticCode.NotATask, `${this.options.taskName} is not a task: the class has no run() method. A task extends Task.`);
 		let task;
 		try {
 			task = await this.app.from(moduleClass).get(taskClass);
 		} catch (error) {
-			throw new TaskRunFailure(`The task ${this.options.taskName} could not be created:\n${TaskRunner.describe(error)}`, { cause: error });
+			throw TaskRunner.failureOf(TaskDiagnosticCode.CreateFailed, `The task ${this.options.taskName} could not be created`, error);
 		}
 		const event = {
 			name: this.options.taskName,
@@ -3899,22 +5147,22 @@ var TaskRunner = class TaskRunner {
 				try {
 					await seeds?.apply(event, this.context);
 				} catch (error) {
-					throw new TaskRunFailure(`The task ${this.options.taskName} did not start:\n${TaskRunner.describe(error)}`, { cause: error });
+					throw TaskRunner.failureOf(TaskDiagnosticCode.StartFailed, `The task ${this.options.taskName} did not start`, error);
 				}
 				try {
 					return await task.run(event);
 				} catch (error) {
-					throw new TaskRefusal(`The task ${this.options.taskName} failed:\n${TaskRunner.describe(error)}`, { cause: error });
+					throw TaskRunner.failureOf(TaskDiagnosticCode.TaskFailed, `The task ${this.options.taskName} failed`, error, TaskRefusal);
 				}
 			});
 		} catch (error) {
 			if (error instanceof TaskRunFailure) throw error;
-			throw new TaskRunFailure(`The task ${this.options.taskName} did not start:\n${TaskRunner.describe(error)}`, { cause: error });
+			throw TaskRunner.failureOf(TaskDiagnosticCode.StartFailed, `The task ${this.options.taskName} did not start`, error);
 		}
 		try {
 			this.serialized = JSON.stringify(outcome);
 		} catch (error) {
-			throw new TaskRunFailure(`The task ran, but its result is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+			throw new TaskRunFailure(TaskDiagnosticCode.ResultNotJson, `The task ran, but its result is not JSON: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	}
 	/** The seeds the app declares for every background frame, or none. */
@@ -3934,7 +5182,7 @@ var TaskRunner = class TaskRunner {
 	async importClass(sourceFile, className) {
 		this.packageImports += 1;
 		const found = (isAbsolute(sourceFile) ? await import(pathToFileURL(sourceFile).href) : await ProjectModules.import(this.outputDirectory, `project-package-${this.packageImports}.js`, `export * from ${JSON.stringify(sourceFile)};\n`))[className];
-		if (found === void 0) throw new TaskRunFailure(`${sourceFile} does not export a class named ${className}.`);
+		if (found === void 0) throw new TaskRunFailure(TaskDiagnosticCode.TargetNotFound, `${sourceFile} does not export a class named ${className}.`);
 		return found;
 	}
 	/**
@@ -3954,7 +5202,8 @@ var TaskRunner = class TaskRunner {
 			await this.app?.shutdown();
 		} catch (error) {
 			clean = false;
-			process.stderr.write(`The task finished, but shutting the app down failed — a client may still be open: ${error instanceof Error ? error.message : String(error)}\n`);
+			this.shutdownFailure = "The task finished, but shutting the app down failed — a client may still be open: " + TaskRunner.messageOf(error);
+			process.stderr.write(`${this.shutdownFailure}\n`);
 		}
 		this.restoreStandingWork?.();
 		this.restoreStandingWork = void 0;
@@ -3988,25 +5237,46 @@ var TaskRunner = class TaskRunner {
 	static describe(error) {
 		return error instanceof Error ? error.stack ?? error.message : String(error);
 	}
+	/** The message of a thrown value: the error message, else its string form. */
+	static messageOf(error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+	/**
+	* A failure that wraps a thrown value: stderr gets the lead and the stack trace, the `--json` diagnostic the
+	* lead and the message.
+	*/
+	static failureOf(code, lead, error, Failure = TaskRunFailure) {
+		return new Failure(code, `${lead}:\n${TaskRunner.describe(error)}`, {
+			cause: error,
+			summary: `${lead}: ${TaskRunner.messageOf(error)}`,
+			hint: TaskRunner.stackHint
+		});
+	}
 	/**
-	* The one stdout line of a refused run: `{"error":{"name":…,"message":…}}`. The name is the error name, or the
-	* class name when the class leaves the generic `Error` name.
+	* The error of a refused run, as its stdout line `{"error":{"name":…,"message":…}}` names it. The name is the
+	* error name, or the class name when the class leaves the generic `Error` name.
 	*/
-	static errorLine(thrown) {
-		if (!(thrown instanceof Error)) return JSON.stringify({ error: {
+	static errorOf(thrown) {
+		if (!(thrown instanceof Error)) return {
 			name: "Error",
 			message: String(thrown)
-		} });
+		};
 		const className = thrown.constructor?.name;
-		const name = thrown.name === "Error" && className !== void 0 && className !== "" ? className : thrown.name;
-		return JSON.stringify({ error: {
-			name,
+		return {
+			name: thrown.name === "Error" && className !== void 0 && className !== "" ? className : thrown.name,
 			message: thrown.message
-		} });
+		};
+	}
+	/** The `--json` diagnostics of a failure. */
+	static diagnosticsOf(error) {
+		if (error instanceof CommandFailure) return error.diagnostics;
+		if (error instanceof TaskRunFailure) return [CliDiagnostics.error(error.code, error.summary, error.hint === void 0 ? {} : { hint: error.hint })];
+		if (error instanceof TaskTargetError) return [CliDiagnostics.error(error.code, error.message)];
+		return [CliDiagnostics.error(CliDiagnosticCode.UnexpectedError, TaskRunner.messageOf(error), { hint: TaskRunner.stackHint })];
 	}
 	/** Print a failure on stderr. */
 	static report(error) {
-		if (error instanceof TaskRunFailure || error instanceof TaskTargetError) {
+		if (error instanceof TaskRunFailure || error instanceof TaskTargetError || error instanceof CommandFailure) {
 			process.stderr.write(`${error.message}\n`);
 			return;
 		}
@@ -4092,10 +5362,46 @@ var TaskCommand = class TaskCommand {
 		process.exitCode = exitCode;
 		setTimeout(() => process.exit(exitCode), TaskCommand.exitGraceMilliseconds).unref();
 	}
-	/** Print a usage failure and set the exit code. */
-	static refuse(reason) {
-		process.stderr.write(`heximon task run: ${reason}\n`);
-		process.exitCode = 1;
+	/**
+	* Run the command in this process: the transform-enabled child, or a test. Without `--json` stdout gets the
+	* text line of the result; with it, one `--json` document. Sets the exit code.
+	*
+	* @param args - The parsed arguments.
+	* @param rawArgs - The arguments after `task run`, for every `--src`.
+	*/
+	static async runInProcess(args, rawArgs) {
+		const commandOutput = CommandOutput.resolve("task run", args);
+		await commandOutput.run(async () => {
+			const rootDir = ProjectRoot.resolve(args.cwd);
+			const parsed = TaskCommand.parsePayload(args.payload);
+			if (!parsed.ok) throw TaskCommand.invalidOption("--payload", parsed.reason);
+			const envFile = args["env-file"];
+			if (envFile !== void 0) try {
+				await TaskCommand.loadEnvironmentFile(resolve(process.cwd(), envFile));
+			} catch (error) {
+				throw TaskCommand.invalidOption("--env-file", error instanceof Error ? error.message : String(error));
+			}
+			const sourceOption = TaskCommand.sourceOption(rawArgs);
+			const sourceDirectories = SourceDirectories.resolve(rootDir, sourceOption);
+			const runner = new TaskRunner({
+				rootDir,
+				moduleName: args.module,
+				taskName: args.task,
+				withOutboxRelay: args["with-outbox-relay"] === true,
+				isSourceExplicit: sourceOption !== void 0 && sourceOption.trim() !== "",
+				...parsed.payload === void 0 ? {} : { payload: parsed.payload },
+				...sourceDirectories === void 0 ? {} : { sourceDirectories }
+			});
+			if (commandOutput.isJson()) {
+				const outcome = await runner.perform();
+				process.exitCode = outcome.exitCode;
+				commandOutput.emit(outcome.document);
+			} else process.exitCode = await runner.run();
+		});
+	}
+	/** A failure of one option; the text output prints the reason alone, as before. */
+	static invalidOption(option, reason) {
+		return new CommandFailure([CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, reason, { option })]);
 	}
 };
 const taskRunCommand = defineCommand({
@@ -4114,6 +5420,7 @@ const taskRunCommand = defineCommand({
 			description: "The class name of the task.",
 			required: true
 		},
+		json: CommandOutput.jsonFlag,
 		cwd: {
 			type: "string",
 			description: "Project root directory.",
@@ -4139,34 +5446,12 @@ const taskRunCommand = defineCommand({
 	},
 	async run({ args, rawArgs }) {
 		if (!TransformBoot.isBootProcess()) {
-			process.exitCode = await TransformBoot.reexecUnderTransform("task run");
-			return;
-		}
-		const rootDir = resolve(process.cwd(), args.cwd);
-		const parsed = TaskCommand.parsePayload(args.payload);
-		if (!parsed.ok) {
-			TaskCommand.refuse(parsed.reason);
-			return;
-		}
-		const envFile = args["env-file"];
-		if (envFile !== void 0) try {
-			await TaskCommand.loadEnvironmentFile(resolve(process.cwd(), envFile));
-		} catch (error) {
-			TaskCommand.refuse(error instanceof Error ? error.message : String(error));
+			const commandOutput = CommandOutput.resolve("task run", args);
+			if (await ProjectRoot.checkBeforeRelaunch(args.cwd, commandOutput)) await TransformBoot.relaunch("task run", commandOutput);
 			return;
 		}
-		const sourceOption = TaskCommand.sourceOption(rawArgs);
-		const sourceDirectories = SourceDirectories.resolve(rootDir, sourceOption);
-		const exitCode = await new TaskRunner({
-			rootDir,
-			moduleName: args.module,
-			taskName: args.task,
-			withOutboxRelay: args["with-outbox-relay"],
-			isSourceExplicit: sourceOption !== void 0 && sourceOption.trim() !== "",
-			...parsed.payload === void 0 ? {} : { payload: parsed.payload },
-			...sourceDirectories === void 0 ? {} : { sourceDirectories }
-		}).run();
-		TaskCommand.finish(exitCode);
+		await TaskCommand.runInProcess(args, rawArgs);
+		TaskCommand.finish(Number(process.exitCode ?? 0));
 	}
 });
 /** `heximon task` — run one-off work of the app. */
@@ -4193,6 +5478,13 @@ const WorkflowBaselineState = {
 	/** No committed snapshot for this workflow — the gate is unarmed until `heximon check --update` runs. */
 	Unarmed: "unarmed"
 };
+/** The stable codes of the failures `heximon workflows` raises itself, beside the compiler's own. */
+const WorkflowsDiagnosticCode = {
+	/** The committed `heximon.upgrade.json` exists but cannot be read, so no workflow state is known. */
+	BaselineUnreadable: "workflows.baseline-unreadable",
+	/** The Cloudflare live instances of one workflow could not be listed, so the fleet picture is incomplete. */
+	EnumerationFailed: "workflows.enumeration-failed"
+};
 /**
 * Parses, classifies, and renders the durable-workflow upgrade-safety report — pure functions over the emitted
 * baseline, the committed baseline, and the (optional) Cloudflare live-fleet inventories.
@@ -4271,16 +5563,18 @@ var WorkflowStatusReport = class WorkflowStatusReport {
 		return parts.length === 0 ? `${count} — baseline armed & in sync.` : `${count} — ${parts.join(", ")}.`;
 	}
 	/**
-	* The `--format json` body: the per-workflow entries with their inventories (`null` when skipped).
+	* The `--json` document: the per-workflow entries with their inventories (`null` when skipped).
 	*
 	* @param options - The classified entries, their inventories, and any upgrade-verdict diagnostics the
 	*   compile raised. An upgrade verdict rides the report rather than replacing it — it is the outcome of a
-	*   complete analysis — but it still makes the run report `ok: false`.
+	*   complete analysis — but it still makes the run report `ok: false`. So does each enumeration error,
+	*   which also becomes an error diagnostic.
 	*/
 	static toJson(options) {
 		const upgradeDiagnostics = options.upgradeDiagnostics ?? [];
+		const enumerationDiagnostics = [...options.enumerationErrors].map(([workflowName, reason]) => CliDiagnostics.error(WorkflowsDiagnosticCode.EnumerationFailed, `Cloudflare enumeration failed for ${workflowName}: ${reason}`, { hint: "Check CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, then run the command again." }));
 		return {
-			ok: options.enumerationErrors.size === 0 && upgradeDiagnostics.length === 0,
+			ok: enumerationDiagnostics.length === 0 && upgradeDiagnostics.length === 0,
 			workflows: options.entries.map((entry) => {
 				const enumerationError = options.enumerationErrors.get(entry.resourceName);
 				return {
@@ -4293,25 +5587,26 @@ var WorkflowStatusReport = class WorkflowStatusReport {
 				enumerated: options.cloudflareSkipped === void 0,
 				...options.cloudflareSkipped === void 0 ? {} : { skipped: options.cloudflareSkipped }
 			},
-			...upgradeDiagnostics.length === 0 ? {} : { diagnostics: upgradeDiagnostics }
+			diagnostics: [...upgradeDiagnostics, ...enumerationDiagnostics]
 		};
 	}
 	/**
-	* The `--format json` body for a run that produced NO per-workflow report — a workflow-free app, a failed
+	* The `--json` document for a run that produced NO per-workflow report — a workflow-free app, a failed
 	* compile, or an unreadable committed baseline. Same shape as {@link toJson}, so one reader covers both.
 	*
-	* @param options - Why there is no report, and whether the run itself succeeded.
+	* @param options - Why there is no report, and the diagnostics of a run that failed. `ok` is `false`
+	*   exactly when one of them is an error.
 	*/
 	static noReportJson(options) {
+		const diagnostics = options.diagnostics ?? [];
 		return {
-			ok: options.ok,
+			ok: !diagnostics.some((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error),
 			workflows: [],
 			cloudflare: {
 				enumerated: false,
 				skipped: options.reason
 			},
-			...options.error === void 0 ? {} : { error: options.error },
-			...options.diagnostics === void 0 ? {} : { diagnostics: options.diagnostics }
+			diagnostics
 		};
 	}
 	/**
@@ -4456,9 +5751,10 @@ const workflowsCommand = defineCommand({
 			description: "Project root directory.",
 			default: "."
 		},
+		json: CommandOutput.jsonFlag,
 		format: {
 			type: "string",
-			description: "Output format: 'pretty' (default) or 'json'.",
+			description: "Output format: 'pretty' (default) or 'json' (the same as --json).",
 			default: "pretty"
 		},
 		env: {
@@ -4472,91 +5768,87 @@ const workflowsCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const rootDir = resolve(process.cwd(), args.cwd);
-		const asJson = args.format === "json";
-		const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
-		if (!asJson) intro(`heximon workflows — ${basename(rootDir)}`);
-		const output = (await ProjectCompileSession.open({
-			rootDir,
-			environment: args.env,
-			...sourceDirectories === void 0 ? {} : { sourceDirectories }
-		})).compile();
-		const errors = output.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error);
-		const upgradeErrors = errors.filter((diagnostic) => UpgradeBaseline.isBreaking(diagnostic.code));
-		const blockingErrors = errors.filter((diagnostic) => !UpgradeBaseline.isBreaking(diagnostic.code));
-		if (blockingErrors.length > 0) {
-			if (asJson) process.stdout.write(`${JSON.stringify(WorkflowStatusReport.noReportJson({
-				ok: false,
-				reason: "the compile failed — no workflow report to enumerate against.",
-				error: `Compile failed — ${blockingErrors.length} error${blockingErrors.length === 1 ? "" : "s"}.`,
-				diagnostics: blockingErrors
-			}))}\n`);
-			else {
-				CompileDiagnostics.renderToStderr(rootDir, blockingErrors);
-				outro(`Compile failed — ${blockingErrors.length} error${blockingErrors.length === 1 ? "" : "s"}; no workflow report.`);
+		const commandOutput = CommandOutput.resolve("workflows", args);
+		await commandOutput.run(async () => {
+			const rootDir = ProjectRoot.resolve(args.cwd);
+			const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
+			if (!commandOutput.isJson()) intro(`heximon workflows — ${basename(rootDir)}`);
+			const output = (await ProjectCompileSession.open({
+				rootDir,
+				environment: args.env,
+				...sourceDirectories === void 0 ? {} : { sourceDirectories }
+			})).compile();
+			const errors = output.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error);
+			const upgradeErrors = errors.filter((diagnostic) => UpgradeBaseline.isBreaking(diagnostic.code));
+			const blockingErrors = errors.filter((diagnostic) => !UpgradeBaseline.isBreaking(diagnostic.code));
+			if (blockingErrors.length > 0) {
+				if (commandOutput.isJson()) commandOutput.emit(WorkflowStatusReport.noReportJson({
+					reason: "the compile failed — no workflow report to enumerate against.",
+					diagnostics: CliDiagnostics.fromCompiler(blockingErrors)
+				}));
+				else {
+					CompileDiagnostics.renderToStderr(rootDir, blockingErrors);
+					outro(`Compile failed — ${blockingErrors.length} error${blockingErrors.length === 1 ? "" : "s"}; no workflow report.`);
+				}
+				process.exitCode = 1;
+				return;
 			}
-			process.exitCode = 1;
-			return;
-		}
-		const generated = output.files.find((file) => file.path === WorkflowStatusReport.generatedBaselinePath);
-		const current = generated === void 0 ? void 0 : WorkflowStatusReport.parseGeneratedText(generated.content);
-		if (current === void 0 || current.workflows.length === 0) {
-			if (asJson) process.stdout.write(`${JSON.stringify(WorkflowStatusReport.noReportJson({
-				ok: true,
-				reason: "this app declares no workflows — nothing to enumerate."
-			}))}\n`);
-			else outro("No workflows in this app.");
-			return;
-		}
-		const committed = WorkflowsCommand.readCommittedBaseline(rootDir);
-		if (committed.state === CommittedBaselineState.Unreadable) {
-			const message = `${WorkflowStatusReport.committedBaselineFileName} exists but could not be read (${committed.reason ?? "unknown reason"}), so no workflow's upgrade-safety state is known — this is NOT an unarmed gate. Restore the committed file (e.g. from git) before deploying; \`heximon check --update\` would overwrite it with the current surface.`;
-			if (asJson) process.stdout.write(`${JSON.stringify(WorkflowStatusReport.noReportJson({
-				ok: false,
-				reason: "the committed upgrade-safety baseline is unreadable — nothing to compare against.",
-				error: message
-			}))}\n`);
-			else {
-				log.error(message);
-				outro("Upgrade-safety baseline unreadable — no workflow report.");
+			const generated = output.files.find((file) => file.path === WorkflowStatusReport.generatedBaselinePath);
+			const current = generated === void 0 ? void 0 : WorkflowStatusReport.parseGeneratedText(generated.content);
+			if (current === void 0 || current.workflows.length === 0) {
+				if (commandOutput.isJson()) commandOutput.emit(WorkflowStatusReport.noReportJson({ reason: "this app declares no workflows — nothing to enumerate." }));
+				else outro("No workflows in this app.");
+				return;
 			}
-			process.exitCode = 1;
-			return;
-		}
-		const entries = WorkflowStatusReport.classify(current.workflows, committed.document);
-		const inventories = /* @__PURE__ */ new Map();
-		const enumerationErrors = /* @__PURE__ */ new Map();
-		let cloudflareSkipped;
-		const accountId = process.env["CLOUDFLARE_ACCOUNT_ID"];
-		const apiToken = process.env["CLOUDFLARE_API_TOKEN"];
-		if (accountId === void 0 || accountId === "" || apiToken === void 0 || apiToken === "") cloudflareSkipped = "CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN are not both set — Cloudflare live-instance enumeration skipped.";
-		else {
-			const inspector = await CloudflareInspectorLoader.load(rootDir, {
-				accountId,
-				apiToken
-			});
-			if (inspector === void 0) cloudflareSkipped = "@heximon/cloudflare is not installed in this app — Cloudflare live-instance enumeration skipped.";
-			else for (const entry of entries) try {
-				inventories.set(entry.resourceName, await inspector.inspect({
-					workflowName: entry.resourceName,
-					currentFingerprint: entry.fingerprint
+			const committed = WorkflowsCommand.readCommittedBaseline(rootDir);
+			if (committed.state === CommittedBaselineState.Unreadable) {
+				const message = `${WorkflowStatusReport.committedBaselineFileName} exists but could not be read (${committed.reason ?? "unknown reason"}), so no workflow's upgrade-safety state is known — this is NOT an unarmed gate. Restore the committed file (e.g. from git) before deploying; \`heximon check --update\` would overwrite it with the current surface.`;
+				if (commandOutput.isJson()) commandOutput.emit(WorkflowStatusReport.noReportJson({
+					reason: "the committed upgrade-safety baseline is unreadable — nothing to compare against.",
+					diagnostics: [CliDiagnostics.error(WorkflowsDiagnosticCode.BaselineUnreadable, message, { hint: "Restore the committed file, for example from git, before you deploy." })]
 				}));
-			} catch (error) {
-				enumerationErrors.set(entry.resourceName, error instanceof Error ? error.message : String(error));
+				else {
+					log.error(message);
+					outro("Upgrade-safety baseline unreadable — no workflow report.");
+				}
+				process.exitCode = 1;
+				return;
 			}
-		}
-		if (asJson) process.stdout.write(`${JSON.stringify(WorkflowStatusReport.toJson({
-			entries,
-			inventories,
-			enumerationErrors,
-			cloudflareSkipped,
-			...upgradeErrors.length === 0 ? {} : { upgradeDiagnostics: upgradeErrors }
-		}))}\n`);
-		else {
-			WorkflowsCommand.report(entries, inventories, enumerationErrors, cloudflareSkipped);
-			if (upgradeErrors.length > 0) CompileDiagnostics.renderToStderr(rootDir, upgradeErrors);
-		}
-		if (enumerationErrors.size > 0 || upgradeErrors.length > 0) process.exitCode = 1;
+			const entries = WorkflowStatusReport.classify(current.workflows, committed.document);
+			const inventories = /* @__PURE__ */ new Map();
+			const enumerationErrors = /* @__PURE__ */ new Map();
+			let cloudflareSkipped;
+			const accountId = process.env["CLOUDFLARE_ACCOUNT_ID"];
+			const apiToken = process.env["CLOUDFLARE_API_TOKEN"];
+			if (accountId === void 0 || accountId === "" || apiToken === void 0 || apiToken === "") cloudflareSkipped = "CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN are not both set — Cloudflare live-instance enumeration skipped.";
+			else {
+				const inspector = await CloudflareInspectorLoader.load(rootDir, {
+					accountId,
+					apiToken
+				});
+				if (inspector === void 0) cloudflareSkipped = "@heximon/cloudflare is not installed in this app — Cloudflare live-instance enumeration skipped.";
+				else for (const entry of entries) try {
+					inventories.set(entry.resourceName, await inspector.inspect({
+						workflowName: entry.resourceName,
+						currentFingerprint: entry.fingerprint
+					}));
+				} catch (error) {
+					enumerationErrors.set(entry.resourceName, error instanceof Error ? error.message : String(error));
+				}
+			}
+			if (commandOutput.isJson()) commandOutput.emit(WorkflowStatusReport.toJson({
+				entries,
+				inventories,
+				enumerationErrors,
+				cloudflareSkipped,
+				upgradeDiagnostics: CliDiagnostics.fromCompiler(upgradeErrors)
+			}));
+			else {
+				WorkflowsCommand.report(entries, inventories, enumerationErrors, cloudflareSkipped);
+				if (upgradeErrors.length > 0) CompileDiagnostics.renderToStderr(rootDir, upgradeErrors);
+			}
+			if (enumerationErrors.size > 0 || upgradeErrors.length > 0) process.exitCode = 1;
+		});
 	}
 });
 /** Output helpers for {@link workflowsCommand}: the committed-baseline read and the pretty report. */
@@ -4643,6 +5935,6 @@ const main = defineCommand({
 	}
 });
 await tab(main);
-await runMain(main);
+await CliEntry.run(main);
 //#endregion
 export {};