@kici-dev/compiler 0.1.26 → 0.2.0

package/dist/auth/headless-detect.d.ts

@@ -1,3 +1,5 @@
+/** Deadline for the WSL interop probe. A healthy probe answers in single-digit ms. */
+export declare const WSL_INTEROP_PROBE_TIMEOUT_MS = 2000;
 /**
  * Detect if the current environment is headless (no browser available).
  *
@@ -5,10 +7,17 @@
  * (desktop) or the RFC 8628 device authorization flow (headless/SSH).
  *
  * Checks in order:
- * 1. SSH session (SSH_CLIENT, SSH_TTY)
- * 2. CI environments (CI, GITHUB_ACTIONS, GITLAB_CI)
- * 3. Container environments (container, DOCKER_CONTAINER)
- * 4. Linux without display server (no DISPLAY and no WAYLAND_DISPLAY)
+ * 1. SSH session (SSH_CONNECTION, SSH_CLIENT, SSH_TTY)
+ * 2. CI environments — see `isCiEnvironment` in `@kici-dev/core/ci-env` for the
+ *    opt-out convention and why a vendor marker beats `CI=false`.
+ * 3. Container environments (container, DOCKER_CONTAINER, and the
+ *    /run/.containerenv + /.dockerenv sentinel files)
+ * 4. WSL with reachable Windows interop — an interactive desktop, so not
+ *    headless. WSL without reachable interop is headless, and so is WSL whose
+ *    interop probe does not answer within the deadline (a hung Windows mount).
+ * 5. Linux without display server (no DISPLAY and no WAYLAND_DISPLAY)
  */
-export declare function isHeadless(): boolean;
+export declare function isHeadless(opts?: {
+    probeTimeoutMs?: number;
+}): Promise<boolean>;
 //# sourceMappingURL=headless-detect.d.ts.map

package/dist/auth/headless-detect.js

@@ -1,5 +1,33 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { existsSync } from "node:fs";
+import pc from "picocolors";
+import { isCiEnvironment } from "@kici-dev/core/ci-env";
+import { canAccessPowerShell, isWsl } from "wsl-utils";
 //#region src/auth/headless-detect.ts
+/** Deadline for the WSL interop probe. A healthy probe answers in single-digit ms. */
+const WSL_INTEROP_PROBE_TIMEOUT_MS = 2e3;
+/**
+* Run the Windows-interop probe under a deadline.
+*
+* `canAccessPowerShell()` does unbounded filesystem I/O against the mounted
+* Windows drive: on a wedged 9p mount it never settles, which would strand the
+* caller. The tri-state result lets the caller tell "the probe said
+* unreachable" from "the probe never answered" — only the latter is announced.
+*/
+async function probeWithDeadline(timeoutMs) {
+	const probe = canAccessPowerShell();
+	probe.catch(() => {});
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(() => resolve("timeout"), timeoutMs);
+		timer.unref?.();
+	});
+	try {
+		return await Promise.race([probe, deadline]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
 /**
 * Detect if the current environment is headless (no browser available).
 *
@@ -7,19 +35,32 @@ import "../rolldown-runtime-ClRpJifh.js";
 * (desktop) or the RFC 8628 device authorization flow (headless/SSH).
 *
 * Checks in order:
-* 1. SSH session (SSH_CLIENT, SSH_TTY)
-* 2. CI environments (CI, GITHUB_ACTIONS, GITLAB_CI)
-* 3. Container environments (container, DOCKER_CONTAINER)
-* 4. Linux without display server (no DISPLAY and no WAYLAND_DISPLAY)
+* 1. SSH session (SSH_CONNECTION, SSH_CLIENT, SSH_TTY)
+* 2. CI environments — see `isCiEnvironment` in `@kici-dev/core/ci-env` for the
+*    opt-out convention and why a vendor marker beats `CI=false`.
+* 3. Container environments (container, DOCKER_CONTAINER, and the
+*    /run/.containerenv + /.dockerenv sentinel files)
+* 4. WSL with reachable Windows interop — an interactive desktop, so not
+*    headless. WSL without reachable interop is headless, and so is WSL whose
+*    interop probe does not answer within the deadline (a hung Windows mount).
+* 5. Linux without display server (no DISPLAY and no WAYLAND_DISPLAY)
 */
-function isHeadless() {
-	if (process.env.SSH_CLIENT || process.env.SSH_TTY) return true;
-	if (process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI) return true;
-	if (process.env.container || process.env.DOCKER_CONTAINER) return true;
+async function isHeadless(opts = {}) {
+	if (process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY) return true;
+	if (isCiEnvironment()) return true;
+	if (process.env.container || process.env.DOCKER_CONTAINER || existsSync("/run/.containerenv") || existsSync("/.dockerenv")) return true;
+	if (isWsl) {
+		const reachable = await probeWithDeadline(opts.probeTimeoutMs ?? 2e3);
+		if (reachable === "timeout") {
+			console.log(pc.dim("  Windows interop probe timed out — using the device flow."));
+			return true;
+		}
+		return !reachable;
+	}
 	if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return true;
 	return false;
 }
 //#endregion
-export { isHeadless };
+export { WSL_INTEROP_PROBE_TIMEOUT_MS, isHeadless };
 
 //# sourceMappingURL=headless-detect.js.map

package/dist/cli-banner.d.ts

@@ -3,9 +3,12 @@ import type { Command } from 'commander';
  * Whether the version banner should be suppressed for the command about to run.
  *
  * Structured-output (`--json`) and quiet (`--quiet`) invocations must keep stdout
- * free of human-facing chrome so callers can parse stdout directly. Uses
- * `optsWithGlobals()` so the check stays correct if either flag is ever promoted
- * to a global option.
+ * free of human-facing chrome so callers can parse stdout directly. Walks the
+ * command chain checking each command's OWN opts (not `optsWithGlobals()`): a
+ * flag set anywhere in the chain suppresses the banner, and reading own opts
+ * avoids a parent's default value shadowing a subcommand's explicit flag —
+ * `kici run` defines `--quiet` for its routed action, which under
+ * `optsWithGlobals()` would mask `kici run remote --quiet`.
  */
 export declare function shouldSuppressBanner(actionCommand: Command): boolean;
 //# sourceMappingURL=cli-banner.d.ts.map

package/dist/cli-banner.js

@@ -4,13 +4,21 @@ import "./rolldown-runtime-ClRpJifh.js";
 * Whether the version banner should be suppressed for the command about to run.
 *
 * Structured-output (`--json`) and quiet (`--quiet`) invocations must keep stdout
-* free of human-facing chrome so callers can parse stdout directly. Uses
-* `optsWithGlobals()` so the check stays correct if either flag is ever promoted
-* to a global option.
+* free of human-facing chrome so callers can parse stdout directly. Walks the
+* command chain checking each command's OWN opts (not `optsWithGlobals()`): a
+* flag set anywhere in the chain suppresses the banner, and reading own opts
+* avoids a parent's default value shadowing a subcommand's explicit flag —
+* `kici run` defines `--quiet` for its routed action, which under
+* `optsWithGlobals()` would mask `kici run remote --quiet`.
 */
 function shouldSuppressBanner(actionCommand) {
-	const opts = actionCommand.optsWithGlobals();
-	return Boolean(opts.json) || Boolean(opts.quiet);
+	let cmd = actionCommand;
+	while (cmd) {
+		const opts = cmd.opts();
+		if (opts.json === true || opts.quiet === true) return true;
+		cmd = cmd.parent;
+	}
+	return false;
 }
 //#endregion
 export { shouldSuppressBanner };

package/dist/cli.js

@@ -7,7 +7,7 @@ import { realpathSync } from "node:fs";
 import { Argument, Command, Option } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.1.26";
+const version = "0.2.0";
 /**
 * Top-level commands that were removed, mapped to their current equivalent.
 * Consulted when the CLI hits an unknown command so the user gets a precise
@@ -16,7 +16,8 @@ const version = "0.1.26";
 */
 const RETIRED_COMMANDS = {
 	status: "`kici status` is no longer a command. Use `kici runs list` / `kici runs show <run-id>` to inspect runs, or `kici diagnostics` for orchestrator, scaler, and agent health.",
-	cancel: "`kici cancel` is no longer a command. Use `kici runs cancel <run-id>`."
+	cancel: "`kici cancel` is no longer a command. Use `kici runs cancel <run-id>`.",
+	"run local": "`kici run local` is retired. Every run is now a real routed dispatch — use `kici run <event> --local` (e.g. `kici run push --local`), which runs this machine as an ephemeral agent through the local dev plane."
 };
 /**
 * Redirect message for a retired top-level command, or undefined if the name is
@@ -43,6 +44,7 @@ function attemptedCommand(program, argv) {
 function buildProgram() {
 	const program = new Command();
 	program.name("kici").description("KiCI workflow compiler").version(version);
+	program.enablePositionalOptions();
 	program.hook("preAction", (_thisCommand, actionCommand) => {
 		if (shouldSuppressBanner(actionCommand)) return;
 		console.log(pc.gray(`kici v${version}`));
@@ -52,7 +54,7 @@ function buildProgram() {
 	} });
 	program.showSuggestionAfterError(true);
 	program.showHelpAfterError("(run `kici --help` to see all commands)");
-	program.command("compile").description("Compile workflows from .kici/workflows/ to kici.lock.json").option("--check", "Validate workflows without writing lock file", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--verbose", "Detailed output", false).option("--watch", "Watch for changes and recompile", false).action(async (options) => {
+	program.command("compile").description("Compile workflows from .kici/workflows/ to kici.lock.json").option("--check", "Validate workflows and type-check sources (tsc --noEmit) without writing lock file", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--verbose", "Detailed output", false).option("--watch", "Watch for changes and recompile", false).action(async (options) => {
 		const { compileCommand, watchCommand } = await import("./commands/index.js");
 		if (options.watch) await watchCommand({
 			kiciDir: options.kiciDir,
@@ -73,50 +75,26 @@ function buildProgram() {
 		await fixtureCommand(event, options);
 	});
 	const runCommand = program.command("run").description("Execute workflows locally or remotely");
-	runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open, schedule) — optional with --pick").description("Execute workflows locally without orchestrator infrastructure").option("-p, --pick", "Interactively pick a workflow and trigger to simulate", false).option("--workflow <name>", "Run only the specified workflow").option("--job <name>", "Run only the specified job (and its dependencies)").option("--branch <name>", "Override detected git branch").option("--sha <hash>", "Override detected git SHA").option("--payload <path>", "Path to explicit event payload JSON file").option("--concurrency <n>", "Max parallel jobs (default: CPU cores)", parseInt).option("--keep-going", "Continue after job failure", false).option("--container", "Use Podman container isolation", false).option("--env <KEY=VALUE>", "Environment variable override (repeatable)", (val, prev) => [...prev, val], []).option("--input <KEY=VALUE>", "Typed workflow-dispatch input (repeatable)", (val, prev) => [...prev, val], []).option("--quiet", "Suppress streaming output", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--files <path>", "Override changed file paths (repeatable, default: git diff)", (val, prev) => [...prev, val], []).option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--in-place", "Run against the real working directory instead of an isolated tmp checkout", false).option("--keep", "Always retain the isolated tmp checkout (default: keep only on failure)", false).option("--check", "Run in check mode: report drift, change nothing", false).option("--fail-on-drift", "In check mode, exit non-zero if any step reports drift", false).action(async (event, options) => {
-		if (options.pick && options.workflow) {
-			console.error("Error: --pick is mutually exclusive with --workflow.");
-			process.exit(2);
-		}
-		if (!options.pick && !event) {
-			const { printRunLocalUsage } = await import("./commands/index.js");
-			printRunLocalUsage();
-			process.exit(2);
-		}
-		const { runLocalCommand } = await import("./commands/index.js");
-		const { resolveCheckMode } = await import("./commands/check-mode.js");
-		let checkMode;
-		try {
-			checkMode = resolveCheckMode({
-				check: options.check,
-				failOnDrift: options.failOnDrift
-			});
-		} catch (err) {
-			console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+	runCommand.enablePositionalOptions();
+	runCommand.argument("[event]", "Event type for a routed local run (e.g. push, pr:open)").option("--local", "Route the run with this machine as the ephemeral agent", false).option("--offline", "Force the throwaway/independent plane (offline)", false).option("--connected", "Force the connected/hybrid plane (requires attachment)", false).option("--in-place", "Reuse the working tree directly instead of an isolated clone", false).option("--trusted", "Route to the trusted fleet agent profile: steps see the ambient host env (minus the agent identity). Alias: --no-sandbox", false).option("--no-sandbox", "Alias for --trusted (the bwrap sandbox is already off by default)").option("--env <KEY=VALUE>", "Per-run secret (repeatable)", (val, prev) => [...prev, val], []).option("--payload <path>", "Dispatch payload JSON { action?, client_payload? } for a routed dispatch run").option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--quiet", "Suppress the banner + streaming output", false).option("--debug", "Verbose internals", false).action(async (event, options) => {
+		const retired = retiredCommandHint(event ? `run ${event}` : void 0);
+		if (retired) {
+			process.stderr.write(pc.red(`${retired}\n`));
 			process.exit(2);
 		}
-		const success = await runLocalCommand({
+		const { runRoutedCommand } = await import("./commands/index.js");
+		const success = await runRoutedCommand({
 			event,
-			checkMode,
-			pick: options.pick,
-			workflow: options.workflow,
-			job: options.job,
-			branch: options.branch,
-			sha: options.sha,
-			payload: options.payload,
-			concurrency: options.concurrency,
-			keepGoing: options.keepGoing,
-			container: options.container,
+			local: options.local,
+			offline: options.offline,
+			connected: options.connected,
+			inPlace: options.inPlace,
+			trusted: Boolean(options.trusted) || options.sandbox === false,
 			env: options.env,
-			inputs: options.input,
-			quiet: options.quiet,
-			json: options.json,
-			junit: options.junit,
-			files: options.files,
-			debug: options.debug,
+			payload: options.payload,
 			kiciDir: options.kiciDir,
-			inPlace: options.inPlace,
-			keep: options.keep
+			quiet: options.quiet,
+			debug: options.debug
 		});
 		process.exit(success ? 0 : 1);
 	});
@@ -161,7 +139,7 @@ function buildProgram() {
 		const success = await previewCommand(event, options);
 		process.exit(success ? 0 : 1);
 	});
-	program.command("init").description("Initialize .kici/ directory with default workflows").option("--force", "Overwrite existing .kici/ directory", false).option("--skip-install", "Create files without installing dependencies", false).option("--package-manager <npm|pnpm|yarn>", "Force a package manager for the install step (default: auto-detect)").option("--mjs", "JavaScript-only mode (no TypeScript, no dependencies)", false).option("--no-agents-md", "Skip writing .kici/AGENTS.md (LLM authoring context)").option("--private-registry <url>", "Scaffold a workflow registries: entry pointing at <url>").option("--private-registry-scope <scope>", "Optional npm package scope (e.g. @my-org) for the private registry").option("--private-registry-secret <ref>", "Qualified secret reference (env:NAME) the private registry token comes from", "production:NPM_TOKEN").addOption(new Option("--use-verdaccio-local").default(false).hideHelp()).action(async (options) => {
+	program.command("init").description("Initialize .kici/ directory with default workflows").option("--force", "Overwrite existing .kici/ directory", false).option("--skip-install", "Create files without installing dependencies", false).option("--package-manager <npm|pnpm|yarn>", "Force a package manager for the install step (default: auto-detect)").option("--mjs", "JavaScript-only mode (no TypeScript, no dependencies)", false).option("--workspace", "Integrate .kici/ into the detected pnpm/npm/yarn workspace so workflows can import sibling packages", false).option("--standalone", "Force a self-contained .kici/ even inside a workspace", false).option("--no-agents-md", "Skip writing .kici/AGENTS.md (LLM authoring context)").option("--private-registry <url>", "Scaffold a workflow registries: entry pointing at <url>").option("--private-registry-scope <scope>", "Optional npm package scope (e.g. @my-org) for the private registry").option("--private-registry-secret <ref>", "Qualified secret reference (env:NAME) the private registry token comes from", "production:NPM_TOKEN").addOption(new Option("--use-verdaccio-local").default(false).hideHelp()).action(async (options) => {
 		const { initCommand } = await import("./commands/index.js");
 		const success = await initCommand({
 			...options,
@@ -174,7 +152,7 @@ function buildProgram() {
 		const success = await hookInstallCommand({ git: options.git });
 		process.exit(success ? 0 : 1);
 	});
-	program.command("login").description("Authenticate with KiCI via browser OAuth (default) or API key (--token)").option("--token <key>", "API key for direct authentication (legacy)").option("--device", "Force device authorization flow (for headless/SSH environments)").option("--platform-endpoint <url>", "Platform relay URL").option("--oidc-issuer <url>", "OIDC issuer URL (defaults to the hosted KiCI IdP unless a flag/env selects another)").option("--routing-key <key>", "Routing key for webhook source identification").addHelpText("after", `
+	program.command("login").description("Authenticate with KiCI via browser OAuth (default) or API key (--token)").option("--token <key>", "API key for direct authentication (legacy)").option("--device", "Force device authorization flow (for headless/SSH environments)").option("--platform-endpoint <url>", "Platform relay URL").option("--oidc-issuer <url>", "OIDC issuer URL (defaults to the hosted KiCI IdP unless a flag/env selects another)").option("--routing-key <key>", "Routing key for webhook source identification").option("--no-attach", "Skip the post-login prompt to attach the local dev plane").addHelpText("after", `
 Environment variables:
   KICI_BROWSER_CMD     Custom browser command (use {url} placeholder, or 'none' to suppress)
   KICI_CALLBACK_PORT   Fixed port for OAuth PKCE callback server (default: random)
@@ -188,7 +166,8 @@ Environment variables:
 			device: options.device,
 			platformEndpoint: options.platformEndpoint,
 			oidcIssuer: options.oidcIssuer,
-			routingKey: options.routingKey
+			routingKey: options.routingKey,
+			noAttachPrompt: options.attach === false
 		});
 		process.exit(success ? 0 : 1);
 	});
@@ -224,6 +203,137 @@ Environment variables:
 		const success = await orchestratorsUseCommand(name, { org: options.org });
 		process.exit(success ? 0 : 1);
 	});
+	const notificationsCommand = program.command("notifications").description("Manage the org's notification channels, subscriptions, and Slack roster");
+	const notificationsChannels = notificationsCommand.command("channels").description("Manage notification channels (Slack / email)");
+	notificationsChannels.command("list").description("List notification channels").option("--org <id>", "Target organization (overrides the active org)").option("--json", "Output as JSON").action(async (options) => {
+		const { notificationsChannelsListCommand } = await import("./commands/index.js");
+		const ok = await notificationsChannelsListCommand({
+			org: options.org,
+			json: options.json
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	notificationsChannels.command("add").description("Add a notification channel").requiredOption("--type <slack|email>", "Channel transport type").requiredOption("--name <name>", "Channel display name").option("--connection <id>", "Slack connection id (slack channels)").option("--slack-channel <id>", "Slack channel id (slack channels)").option("--from-name <name>", "Sender name (email channels)").option("--reply-to <email>", "Reply-to address (email channels)").option("--org <id>", "Target organization (overrides the active org)").action(async (options) => {
+		const { notificationsChannelsAddCommand } = await import("./commands/index.js");
+		const ok = await notificationsChannelsAddCommand({
+			org: options.org,
+			type: options.type,
+			name: options.name,
+			connection: options.connection,
+			slackChannel: options.slackChannel,
+			fromName: options.fromName,
+			replyTo: options.replyTo
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	notificationsChannels.command("remove").argument("<id>", "Channel id").description("Remove a notification channel").option("--org <id>", "Target organization (overrides the active org)").action(async (id, options) => {
+		const { notificationsChannelsRemoveCommand } = await import("./commands/index.js");
+		const ok = await notificationsChannelsRemoveCommand(id, { org: options.org });
+		process.exit(ok ? 0 : 1);
+	});
+	const notificationsSubscriptions = notificationsCommand.command("subscriptions").description("Manage notification subscriptions");
+	notificationsSubscriptions.command("list").description("List notification subscriptions").option("--org <id>", "Target organization (overrides the active org)").option("--json", "Output as JSON").action(async (options) => {
+		const { notificationsSubscriptionsListCommand } = await import("./commands/index.js");
+		const ok = await notificationsSubscriptionsListCommand({
+			org: options.org,
+			json: options.json
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	notificationsSubscriptions.command("add").description("Add a notification subscription").requiredOption("--channel <id>", "Target channel id").requiredOption("--on-status <csv>", "Statuses to notify on (e.g. failed,success)").option("--level <run|job>", "Subscription granularity", "run").option("--scope <org|team|user|actor>", "Subscription scope", "org").option("--scope-id <id>", "Scope id (required for team/user scope)").option("--repo-glob <glob>", "Match runs whose repo matches this glob").option("--workflow-glob <glob>", "Match runs whose workflow matches this glob").option("--job-glob <glob>", "Match jobs matching this glob (job level)").option("--mentions <csv>", "Literal Slack member/group ids or emails to mention").option("--recipient-override <csv>", "Override the email recipient set").option("--on-failure-class <csv>", "Only match these failure classes").option("--accumulate-for <ms>", "Digest accumulation window in milliseconds").option("--org <id>", "Target organization (overrides the active org)").action(async (options) => {
+		const { notificationsSubscriptionsAddCommand } = await import("./commands/index.js");
+		const ok = await notificationsSubscriptionsAddCommand({
+			org: options.org,
+			channel: options.channel,
+			onStatus: options.onStatus,
+			level: options.level,
+			scope: options.scope,
+			scopeId: options.scopeId,
+			repoGlob: options.repoGlob,
+			workflowGlob: options.workflowGlob,
+			jobGlob: options.jobGlob,
+			mentions: options.mentions,
+			recipientOverride: options.recipientOverride,
+			onFailureClass: options.onFailureClass,
+			accumulateFor: options.accumulateFor
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	notificationsSubscriptions.command("remove").argument("<id>", "Subscription id").description("Remove a notification subscription").option("--org <id>", "Target organization (overrides the active org)").action(async (id, options) => {
+		const { notificationsSubscriptionsRemoveCommand } = await import("./commands/index.js");
+		const ok = await notificationsSubscriptionsRemoveCommand(id, { org: options.org });
+		process.exit(ok ? 0 : 1);
+	});
+	const notificationsRoster = notificationsCommand.command("roster").description("Manage the Layer 1 Slack-identity roster (actor tagging)");
+	notificationsRoster.command("list").description("List Slack-identity roster entries").option("--org <id>", "Target organization (overrides the active org)").option("--json", "Output as JSON").action(async (options) => {
+		const { notificationsRosterListCommand } = await import("./commands/index.js");
+		const ok = await notificationsRosterListCommand({
+			org: options.org,
+			json: options.json
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	notificationsRoster.command("add").description("Add a Slack-identity roster entry").requiredOption("--connection <id>", "Slack connection id").requiredOption("--subject-kind <kici_user|git_login|email>", "What the subject keys on").requiredOption("--subject <value>", "The KiCI user sub, git login, or email").requiredOption("--value <slackIdEmailOrHandle>", "Slack member id, email, or @handle").option("--input-form <id|username|email>", "How --value should be resolved", "id").option("--org <id>", "Target organization (overrides the active org)").action(async (options) => {
+		const { notificationsRosterAddCommand } = await import("./commands/index.js");
+		const ok = await notificationsRosterAddCommand({
+			org: options.org,
+			connection: options.connection,
+			subjectKind: options.subjectKind,
+			subject: options.subject,
+			inputForm: options.inputForm,
+			value: options.value
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	notificationsRoster.command("remove").argument("<id>", "Roster entry id").description("Remove a Slack-identity roster entry").option("--org <id>", "Target organization (overrides the active org)").action(async (id, options) => {
+		const { notificationsRosterRemoveCommand } = await import("./commands/index.js");
+		const ok = await notificationsRosterRemoveCommand(id, { org: options.org });
+		process.exit(ok ? 0 : 1);
+	});
+	const localCommand = program.command("local").description("Manage the local dev orchestrator plane");
+	localCommand.command("up").description("Start (or reuse) the local dev plane").option("--offline", "Force the independent (offline) plane (does not clear the attachment record)", false).option("--connected", "Force the connected/hybrid plane (requires an attached, reachable Platform)", false).action(async (options) => {
+		const { localUpCommand } = await import("./commands/index.js");
+		const ok = await localUpCommand({
+			offline: options.offline,
+			connected: options.connected
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	localCommand.command("status").description("Show local dev plane status and control commands").option("--json", "Emit machine-readable JSON (exits 0 for every state)", false).action(async (options) => {
+		const { localStatusCommand } = await import("./commands/index.js");
+		const ok = await localStatusCommand({ json: options.json });
+		process.exit(ok ? 0 : 1);
+	});
+	for (const [name, desc, fn] of [
+		[
+			"down",
+			"Stop the local dev plane",
+			"localDownCommand"
+		],
+		[
+			"logs",
+			"Print the local dev plane orchestrator log path",
+			"localLogsCommand"
+		],
+		[
+			"attach",
+			"Attach the local dev plane to the Platform (hybrid)",
+			"localAttachCommand"
+		],
+		[
+			"detach",
+			"Detach the local dev plane from the Platform (offline)",
+			"localDetachCommand"
+		]
+	]) localCommand.command(name).description(desc).action(async () => {
+		const ok = await (await import("./commands/index.js"))[fn]();
+		process.exit(ok ? 0 : 1);
+	});
+	localCommand.command("trust-root").description("Export the offline dev-signed identity trust root ({ issuer, jwks }) to a file").argument("<file>", "Output path for the { issuer, jwks } trust-root JSON").action(async (file) => {
+		const { localTrustRootCommand } = await import("./commands/index.js");
+		const ok = await localTrustRootCommand(file);
+		process.exit(ok ? 0 : 1);
+	});
 	program.command("secrets").description("Manage secrets").command("list").description("List test-available secret contexts").action(async () => {
 		const { secretsListCommand } = await import("./commands/index.js");
 		const success = await secretsListCommand();
@@ -240,7 +350,7 @@ Environment variables:
 		process.exit(success ? 0 : 1);
 	});
 	const runsCommand = program.command("runs").description("Inspect and manage execution runs");
-	runsCommand.command("list").description("List execution runs (mirrors the dashboard Runs page)").option("--status <s>", "Filter by status").option("--workflow <w>", "Filter by workflow name").option("--branch <b>", "Filter by branch/ref").option("--repo <r>", "Filter by repository").option("--trigger <t>", "Filter by trigger type").option("--source <routingKey>", "Filter by source routing key").option("--since <ts>", "Only runs since (ISO-8601 or epoch ms)").option("--page <n>", "Page number", (v) => parseInt(v, 10)).option("--json", "Output raw JSON", false).action(async (options) => {
+	runsCommand.command("list").description("List execution runs (mirrors the dashboard Runs page)").option("--status <s>", "Filter by status").option("--workflow <w>", "Filter by workflow name").option("--branch <b>", "Filter by branch/ref").option("--repo <r>", "Filter by repository").option("--trigger <t>", "Filter by trigger type").option("--source <routingKey>", "Filter by source routing key").option("--since <ts>", "Only runs since (ISO-8601 or epoch ms)").option("--cursor <cursor>", "Keyset cursor for the next page (from a prior nextCursor)").option("--json", "Output raw JSON", false).action(async (options) => {
 		const { runsListCommand } = await import("./commands/index.js");
 		const success = await runsListCommand(options);
 		process.exit(success ? 0 : 1);
@@ -272,6 +382,20 @@ Environment variables:
 		});
 		process.exit(success ? 0 : 1);
 	});
+	const runsArtifacts = runsCommand.command("artifacts").description("List and download a run's artifacts");
+	runsArtifacts.command("list").argument("<run-id>", "Run ID whose artifacts to list").description("List the artifacts a run uploaded").option("--json", "Output raw JSON", false).action(async (runId, options) => {
+		const { runsArtifactsListCommand } = await import("./commands/index.js");
+		const success = await runsArtifactsListCommand(runId, { json: options.json });
+		process.exit(success ? 0 : 1);
+	});
+	runsArtifacts.command("download").argument("<run-id>", "Run ID whose artifacts to download").argument("[name]", "Artifact name (omit to download every artifact of the run)").description("Download one artifact, or all of them — extracts by default").option("--archive", "Save the raw .tar.gz instead of extracting", false).option("-o, --output <dir>", "Output directory (default: current directory)").action(async (runId, name, options) => {
+		const { runsArtifactsDownloadCommand } = await import("./commands/index.js");
+		const success = await runsArtifactsDownloadCommand(runId, name, {
+			archive: options.archive,
+			output: options.output
+		});
+		process.exit(success ? 0 : 1);
+	});
 	program.command("approve").argument("<run-id>", "Run ID whose approval gate to approve").description("Approve a held approval gate for a run").option("--job <name>", "Approve the hold for a specific job").option("--step <index>", "Approve a step-scoped hold (requires --job)").action(async (runId, options) => {
 		const { approveCommand } = await import("./commands/index.js");
 		const success = await approveCommand(runId, {
@@ -299,7 +423,15 @@ Environment variables:
 		const success = await endpointsCommand({ kiciDir: options.kiciDir });
 		process.exit(success ? 0 : 1);
 	});
-	program.command("diagnostics").description("Show orchestrators, scalers, and agents (mirrors the dashboard Diagnostics page)").option("--json", "Output raw JSON", false).option("--verbose", "Show extended per-agent fields", false).option("--orchestrator <id>", "Scope the tree to one connection id").action(async (options) => {
+	program.command("doctor").description("Diagnose your KiCI setup and print the exact next command for each problem").option("--json", "Output raw JSON instead of a table", false).option("--kici-dir <path>", "Path to the .kici directory", ".kici").action(async (options) => {
+		const { doctorCommand } = await import("./commands/index.js");
+		const exitCode = await doctorCommand({
+			json: options.json,
+			kiciDir: options.kiciDir
+		});
+		process.exit(exitCode);
+	});
+	program.command("diagnostics").description("Show orchestrators, scalers, and agents (mirrors the dashboard Infrastructure page)").option("--json", "Output raw JSON", false).option("--verbose", "Show extended per-agent fields", false).option("--orchestrator <id>", "Scope the tree to one connection id").action(async (options) => {
 		const { diagnosticsCommand } = await import("./commands/index.js");
 		const success = await diagnosticsCommand({
 			json: options.json,
@@ -335,7 +467,7 @@ Environment variables:
 		const success = await drainWorkerCommand({ url: options.url });
 		process.exit(success ? 0 : 1);
 	});
-	program.command("verify-attestation").argument("[artifact]", "Artifact path to digest-check against the attestation subject (optional)").description("Verify a KiCI provenance attestation bundle offline").option("--bundle <path>", "Path or URL to the attestation bundle JSON").option("--trust-root <url-or-file>", "Trusted issuer URL, or a self-contained { issuer, jwks } file (default: hosted KiCI platform)").option("--audience <aud>", "Expected token audience").option("--json", "Output structured JSON result", false).action(async (artifact, options) => {
+	program.command("verify-attestation").argument("[artifact]", "Artifact path to digest-check against the attestation subject (optional)").description("Verify a KiCI provenance attestation bundle offline").option("--bundle <path>", "Path or URL to the attestation bundle JSON").option("--trust-root <url-or-file>", "Trusted issuer URL, or a self-contained { issuer, jwks } file (default: your configured orchestrator, else the hosted KiCI platform)").option("--audience <aud>", "Expected token audience").option("--json", "Output structured JSON result", false).action(async (artifact, options) => {
 		const { verifyAttestationCommand } = await import("./commands/index.js");
 		const success = await verifyAttestationCommand(artifact, options);
 		process.exit(success ? 0 : 1);

package/dist/commands/check-mode.d.ts

@@ -1,5 +1,5 @@
 import { CheckMode } from '@kici-dev/engine';
-/** The two run-mode flags shared by `kici run local` and `kici run remote`. */
+/** The two check-mode flags accepted by `kici run remote`. */
 export interface CheckModeFlags {
     /** --check: report drift, change nothing. */
     check?: boolean;

package/dist/commands/compile.js

@@ -1,26 +1,39 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { formatError, isCompilerError } from "../errors/formatter.js";
+import { PURITY_FALLBACK_CODE, compilerError, formatError, isCompilerError } from "../errors/formatter.js";
 import "../errors/index.js";
 import { discoverWorkflows, resolveKiciDir } from "../execution/executor.js";
 import "../execution/index.js";
 import { validateConfig } from "../validation/validator.js";
+import { runTypecheck } from "../validation/typecheck.js";
 import "../validation/index.js";
-import { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile } from "../lockfile/generator.js";
+import { BREAKING_FLOOR, SCHEMA_VERSION } from "../types.js";
+import { computeLockfileHash, detectGitRoot, generateLockFile, schemaWindowWarning, serializeLockFile } from "../lockfile/generator.js";
+import { collectWorkflowPurityWarnings } from "../lockfile/purity-diagnostics.js";
 import "../lockfile/index.js";
 import path from "node:path";
 import { existsSync } from "node:fs";
 import pc from "picocolors";
-import fs from "node:fs/promises";
+import fs$1 from "node:fs/promises";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import { PackageManager, detectPackageManagerSync } from "@kici-dev/core/package-manager";
 import { execSync } from "node:child_process";
 //#region src/commands/compile.ts
 /**
+* Render an impure dynamic-value function as a `W101` compile warning naming the
+* job, the field, the impurity reason, and the ~5-10s agent-side init-job cost.
+*/
+function formatPurityWarning(w) {
+	return formatError(compilerError(PURITY_FALLBACK_CODE, `job "${w.jobName}": ${w.field} function is not pure (${w.reason}). An init job will be required, adding ~5-10s delay.`, {
+		severity: "warning",
+		suggestion: `Make the ${w.field} function pure (synchronous, referencing only its parameters) to inline it and skip the init job. See https://docs.kici.dev — dynamic values.`
+	}));
+}
+/**
 * Read the existing lock file and return its lockfileHash, if present.
 */
 async function readExistingLockfileHash(lockPath) {
 	try {
-		const content = await fs.readFile(lockPath, "utf-8");
+		const content = await fs$1.readFile(lockPath, "utf-8");
 		return JSON.parse(content).lockfileHash ?? void 0;
 	} catch {
 		return;
@@ -67,15 +80,18 @@ async function compileCommand(options) {
 		}
 		const { workflows: workflowsWithSource, workflowDir } = await discoverWorkflows(absoluteKiciDir);
 		if (options.verbose) logger.debug(pc.dim(`Found ${workflowsWithSource.length} workflow(s) in ${workflowDir}`));
-		const validation = validateConfig(workflowsWithSource.map((w) => w.workflow), workflowDir);
+		const validation = validateConfig(workflowsWithSource);
 		if (!validation.valid) {
 			for (const error of validation.errors) logger.error(formatError(error));
 			return false;
 		}
 		if (options.verbose) logger.debug(pc.dim("Validation passed"));
 		const lockJson = serializeLockFile(generateLockFile(workflowsWithSource));
+		for (const warning of collectWorkflowPurityWarnings(workflowsWithSource)) logger.warn(formatPurityWarning(warning));
+		const windowWarning = schemaWindowWarning(BREAKING_FLOOR, SCHEMA_VERSION);
+		if (windowWarning) logger.warn(pc.yellow(windowWarning));
 		if (!options.check) {
-			await fs.writeFile(lockPath, lockJson, "utf-8");
+			await fs$1.writeFile(lockPath, lockJson, "utf-8");
 			if (!options.quiet) logger.info(pc.green("✓") + ` Compiled workflows → .kici/kici.lock.json` + pc.dim(` (${workflowsWithSource.length} workflow${workflowsWithSource.length !== 1 ? "s" : ""})`));
 			try {
 				const { loadGlobalConfig } = await import("../remote/config.js");
@@ -92,7 +108,15 @@ async function compileCommand(options) {
 			} catch {
 				logger.warn(pc.yellow("Could not refresh types (Platform unreachable). Compilation succeeded."));
 			}
-		} else if (!options.quiet) logger.info(pc.green("✓") + ` Workflows are valid` + pc.dim(` (${workflowsWithSource.length} workflow${workflowsWithSource.length !== 1 ? "s" : ""})`));
+		} else {
+			const tc = await runTypecheck(absoluteKiciDir);
+			if (tc.errors.length > 0) {
+				for (const error of tc.errors) logger.error(formatError(error));
+				return false;
+			}
+			if (!tc.ran && !options.quiet) logger.info(pc.dim("Type-check skipped (no tsconfig.json — JavaScript mode)"));
+			if (!options.quiet) logger.info(pc.green("✓") + ` Workflows are valid` + pc.dim(` (${workflowsWithSource.length} workflow${workflowsWithSource.length !== 1 ? "s" : ""})`));
+		}
 		return true;
 	} catch (error) {
 		if (isCompilerError(error)) logger.error(formatError(error));

package/dist/commands/diagnostics.js

@@ -3,8 +3,9 @@ import { DashboardClient, DashboardClientError } from "../remote/dashboard-clien
 import { relativeTime } from "../remote/render.js";
 import pc from "picocolors";
 import { logger, toErrorMessage } from "@kici-dev/core";
+import { InfraAlertSeverity, normalizeInfraAlertSeverity } from "@kici-dev/engine";
 //#region src/commands/diagnostics.ts
-/** kici diagnostics — mirrors the dashboard Diagnostics page (infra tree). */
+/** kici diagnostics — mirrors the dashboard Infrastructure page (infra tree). */
 async function diagnosticsCommand(options = {}) {
 	try {
 		const client = await DashboardClient.load();
@@ -36,9 +37,20 @@ function printSummary(s) {
 	const m = s.executionMetrics;
 	console.log(pc.bold("\nDiagnostics") + pc.gray(`  runs(24h)=${m.totalRuns} success=${m.successRate}% avg=${m.avgDurationSeconds}s queued=${m.queuedJobs} running=${m.runningJobs}` + (s.orphanedConnections > 0 ? ` orphaned=${s.orphanedConnections}` : "")));
 }
+/**
+* Alert colour per known severity.
+*
+* Typed `Record<InfraAlertSeverity, …>`: adding a severity to the engine enum
+* without colouring it fails `pnpm typecheck` instead of silently inheriting
+* the warning colour.
+*/
+const ALERT_SEVERITY_COLOR = {
+	[InfraAlertSeverity.enum.warning]: pc.yellow,
+	[InfraAlertSeverity.enum.critical]: pc.red
+};
 function printAlerts(alerts) {
 	for (const a of alerts) {
-		const color = a.severity === "critical" ? pc.red : pc.yellow;
+		const color = ALERT_SEVERITY_COLOR[normalizeInfraAlertSeverity(a.severity)];
 		console.log(color(`  ! [${a.type}] ${a.message}`));
 	}
 }