@kici-dev/compiler 0.1.27 → 0.3.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.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.27";
+const version = "0.3.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
@@ -54,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,
@@ -139,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,
@@ -203,6 +203,93 @@ 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");
@@ -212,12 +299,12 @@ Environment variables:
 		});
 		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 [
-		[
-			"status",
-			"Show local dev plane status and control commands",
-			"localStatusCommand"
-		],
 		[
 			"down",
 			"Stop the local dev plane",
@@ -263,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);
@@ -295,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, {
@@ -322,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,
@@ -358,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/compile.js

@@ -1,11 +1,14 @@
 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";
@@ -16,6 +19,16 @@ import { PackageManager, detectPackageManagerSync } from "@kici-dev/core/package
 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) {
@@ -67,13 +80,16 @@ 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$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" : ""})`));
@@ -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}`));
 	}
 }

package/dist/commands/doctor.d.ts

@@ -0,0 +1,64 @@
+import { type DiagnoseResponse, type DiagnoseResult } from '@kici-dev/core';
+import { type DiagnosticsInfrastructureResponse } from '@kici-dev/engine';
+import { type GlobalConfig } from '../remote/config.js';
+import { type DashboardErrorKind } from '../remote/dashboard-client.js';
+import { type LockFile } from '../types.js';
+/** A doctor check result: a shared DiagnoseResult plus the exact fix command. */
+export interface DoctorCheckResult extends DiagnoseResult {
+    nextCommand?: string;
+}
+/** A check body before the runner stamps its measured duration. */
+export type DoctorCheckBody = Omit<DoctorCheckResult, 'durationMs'>;
+/** The outcome of the single authenticated infrastructure probe. */
+export type ProbeOutcome = {
+    ok: true;
+    infra: DiagnosticsInfrastructureResponse;
+} | {
+    ok: false;
+    kind: DashboardErrorKind;
+    message: string;
+};
+/** Is a stored token + endpoint present (regardless of expiry)? */
+export declare function hasCredentials(config: GlobalConfig): boolean;
+/** Check 1: logged in with an unexpired token. */
+export declare function checkLogin(config: GlobalConfig, now: number): DoctorCheckBody;
+/** Check 2: an active organization is selected. */
+export declare function checkActiveOrg(config: GlobalConfig): DoctorCheckBody;
+/** Check 3: the Platform accepted the stored token (live-token probe). */
+export declare function checkLiveToken(probe: ProbeOutcome | null): DoctorCheckBody;
+/** Local + git state of the compiled lock file. */
+export interface LockState {
+    exists: boolean;
+    fresh: boolean;
+    committed: boolean;
+    gitAvailable: boolean;
+    lock: LockFile | null;
+}
+/** Check 4: an orchestrator is connected for this org. */
+export declare function checkOrchestrator(probe: ProbeOutcome | null): DoctorCheckBody;
+/** Check 5: the lock file is present, fresh, and committed. */
+export declare function checkLockFile(state: LockState): DoctorCheckBody;
+/** Check 6: every workflow's runsOn labels are satisfiable by a connected agent or scaler. */
+export declare function checkLabels(lock: LockFile | null, probe: ProbeOutcome | null): DoctorCheckBody;
+export interface DoctorOptions {
+    json?: boolean;
+    kiciDir?: string;
+}
+/** Injectable seams so every path is unit-testable without real IO. */
+export interface DoctorDeps {
+    loadConfig: () => Promise<GlobalConfig>;
+    probe: (config: GlobalConfig) => Promise<ProbeOutcome | null>;
+    gatherLockState: (kiciDir: string) => Promise<LockState>;
+    now: () => number;
+}
+/** Render the funnel as a status table with a trailing next-command hint per row. */
+export declare function renderDoctorTable(response: DiagnoseResponse & {
+    checks: DoctorCheckResult[];
+}): string;
+/**
+ * Run the onboarding-funnel diagnostic and return the process exit code
+ * (0 all pass · 1 any warn · 2 any fail). The single infrastructure probe is
+ * timed and attributed to the token-live check; the local checks are instant.
+ */
+export declare function doctorCommand(options?: DoctorOptions, deps?: DoctorDeps): Promise<number>;
+//# sourceMappingURL=doctor.d.ts.map