@kici-dev/compiler 0.1.19 → 0.1.21

package/dist/cli.d.ts

@@ -8,4 +8,18 @@ import { Command } from 'commander';
 export declare function buildProgram(): Command;
 /** Build the program and parse argv — the bin-shim entry point. */
 export declare function runCli(argv?: string[]): void;
+/**
+ * Decide whether this module is the process entry point, tolerating a
+ * symlinked `argv[1]`. A `node_modules/.bin/kici` entry is a symlink, and when
+ * it points at this compiled `cli.js` (the compiler package declares a `kici`
+ * bin), `process.argv[1]` is the symlink path while `import.meta.url` is the
+ * real file. A plain `resolve()` comparison sees two different paths and never
+ * matches, silently skipping `runCli()` — so `kici compile` (and every other
+ * subcommand) becomes a no-op when invoked through the bin symlink.
+ * Dereference both sides with `realpathSync` so a symlinked invocation is
+ * correctly recognised as the entry point. Falls back to a plain `resolve()`
+ * comparison when `argv[1]` doesn't resolve to a real file (e.g. a virtual
+ * entry point), preserving the previous behaviour for that edge case.
+ */
+export declare function isMainEntryPoint(argv1: string | undefined, importMetaUrl: string): boolean;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -3,10 +3,11 @@ import "./chunk-BTugEXQM.js";
 import { shouldSuppressBanner } from "./cli-banner.js";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
+import { realpathSync } from "node:fs";
 import { Argument, Command, Option } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.1.19";
+const version = "0.1.21";
 /**
 * Build the kici Commander program with every command registered. Exported so
 * the surface registry can walk the real command tree without parsing argv (no
@@ -43,7 +44,7 @@ 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("--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).action(async (event, options) => {
+	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("--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);
@@ -53,8 +54,20 @@ function buildProgram() {
 			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)}`);
+			process.exit(2);
+		}
 		const success = await runLocalCommand({
 			event,
+			checkMode,
 			pick: options.pick,
 			workflow: options.workflow,
 			job: options.job,
@@ -76,10 +89,22 @@ function buildProgram() {
 		});
 		process.exit(success ? 0 : 1);
 	});
-	runCommand.command("remote").argument("[fixture]", "Fixture name or glob pattern (omit to list available)").description("Execute fixtures remotely via orchestrator").option("--workflow <name>", "Run a specific workflow directly (bypass triggers)").option("--all", "Run all available fixtures", false).option("--parallel", "Run matching fixtures concurrently", false).option("--no-wait", "Fire and forget (print runIds, don't stream)").option("--quiet", "Suppress output except final result", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--history", "Show recent run history", false).option("--routing-key <key>", "Override routing key for this run").option("--org <id>", "Target organization (overrides the active org)").option("--orchestrator <name>", "Target orchestrator cluster (overrides the per-org default)").option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--context <ctx.key=value>", "Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)", (val, prev) => [...prev, val], []).option("--env <KEY=VALUE>", "Provide a per-run secret (repeatable); uploaded encrypted to the orchestrator", (val, prev) => [...prev, val], []).action(async (fixture, options) => {
+	runCommand.command("remote").argument("[fixture]", "Fixture name or glob pattern (omit to list available)").description("Execute fixtures remotely via orchestrator").option("--workflow <name>", "Run a specific workflow directly (bypass triggers)").option("--all", "Run all available fixtures", false).option("--parallel", "Run matching fixtures concurrently", false).option("--no-wait", "Fire and forget (print runIds, don't stream)").option("--quiet", "Suppress output except final result", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--history", "Show recent run history", false).option("--routing-key <key>", "Override routing key for this run").option("--org <id>", "Target organization (overrides the active org)").option("--orchestrator <name>", "Target orchestrator cluster (overrides the per-org default)").option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--context <ctx.key=value>", "Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)", (val, prev) => [...prev, val], []).option("--env <KEY=VALUE>", "Provide a per-run secret (repeatable); uploaded encrypted to the orchestrator", (val, prev) => [...prev, val], []).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 (fixture, options) => {
 		const { runRemoteCommand } = 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)}`);
+			process.exit(2);
+		}
 		const success = await runRemoteCommand(fixture, {
 			...options,
+			checkMode,
 			envFlags: options.env
 		});
 		process.exit(success ? 0 : 1);
@@ -263,8 +288,30 @@ Environment variables:
 function runCli(argv = process.argv) {
 	buildProgram().parse(argv);
 }
-if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) runCli();
+/**
+* Decide whether this module is the process entry point, tolerating a
+* symlinked `argv[1]`. A `node_modules/.bin/kici` entry is a symlink, and when
+* it points at this compiled `cli.js` (the compiler package declares a `kici`
+* bin), `process.argv[1]` is the symlink path while `import.meta.url` is the
+* real file. A plain `resolve()` comparison sees two different paths and never
+* matches, silently skipping `runCli()` — so `kici compile` (and every other
+* subcommand) becomes a no-op when invoked through the bin symlink.
+* Dereference both sides with `realpathSync` so a symlinked invocation is
+* correctly recognised as the entry point. Falls back to a plain `resolve()`
+* comparison when `argv[1]` doesn't resolve to a real file (e.g. a virtual
+* entry point), preserving the previous behaviour for that edge case.
+*/
+function isMainEntryPoint(argv1, importMetaUrl) {
+	if (!argv1) return false;
+	const modulePath = fileURLToPath(importMetaUrl);
+	try {
+		return realpathSync(argv1) === realpathSync(modulePath);
+	} catch {
+		return resolve(argv1) === resolve(modulePath);
+	}
+}
+if (isMainEntryPoint(process.argv[1], import.meta.url)) runCli();
 //#endregion
-export { buildProgram, runCli };
+export { buildProgram, isMainEntryPoint, runCli };
 
 //# sourceMappingURL=cli.js.map

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

@@ -0,0 +1,19 @@
+import { CheckMode } from '@kici-dev/engine';
+/** The two run-mode flags shared by `kici run local` and `kici run remote`. */
+export interface CheckModeFlags {
+    /** --check: report drift, change nothing. */
+    check?: boolean;
+    /** --fail-on-drift: in check mode, exit non-zero if any step reports drift. */
+    failOnDrift?: boolean;
+}
+/**
+ * Resolve the run {@link CheckMode} from the `--check` / `--fail-on-drift` flags.
+ *
+ * - no flags -> `apply` (the unchanged default: converge).
+ * - `--check` -> `check` (report-only, changes nothing).
+ * - `--check --fail-on-drift` -> `check-fail-on-drift` (fails the run on drift).
+ *
+ * `--fail-on-drift` without `--check` is an error — it only modifies check mode.
+ */
+export declare function resolveCheckMode(flags: CheckModeFlags): CheckMode;
+//# sourceMappingURL=check-mode.d.ts.map

package/dist/commands/check-mode.js

@@ -0,0 +1,21 @@
+import "../chunk-BTugEXQM.js";
+import { CheckMode } from "@kici-dev/engine";
+//#region src/commands/check-mode.ts
+/**
+* Resolve the run {@link CheckMode} from the `--check` / `--fail-on-drift` flags.
+*
+* - no flags -> `apply` (the unchanged default: converge).
+* - `--check` -> `check` (report-only, changes nothing).
+* - `--check --fail-on-drift` -> `check-fail-on-drift` (fails the run on drift).
+*
+* `--fail-on-drift` without `--check` is an error — it only modifies check mode.
+*/
+function resolveCheckMode(flags) {
+	if (flags.failOnDrift && !flags.check) throw new Error("--fail-on-drift requires --check");
+	if (flags.check) return flags.failOnDrift ? CheckMode.enum["check-fail-on-drift"] : CheckMode.enum.check;
+	return CheckMode.enum.apply;
+}
+//#endregion
+export { resolveCheckMode };
+
+//# sourceMappingURL=check-mode.js.map

package/dist/commands/compile.js

@@ -8,8 +8,8 @@ import "../validation/index.js";
 import { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile } from "../lockfile/generator.js";
 import "../lockfile/index.js";
 import path from "node:path";
-import pc from "picocolors";
 import { existsSync } from "node:fs";
+import pc from "picocolors";
 import fs from "node:fs/promises";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import { PackageManager, detectPackageManagerSync } from "@kici-dev/core/package-manager";

package/dist/commands/run.js

@@ -294,7 +294,8 @@ async function runSingleFixture(fixture, ctx, options, config, history) {
 			},
 			workflowName: opts.workflowName,
 			inlineLockFile: overlay.inlineLockFile,
-			fullRepo: true
+			fullRepo: true,
+			...options.checkMode && { checkMode: options.checkMode }
 		});
 		if (triggerResult.status === "rejected") {
 			if (!options.quiet) logger.info(pc.red(`Rejected: ${triggerResult.reason ?? "unknown reason"}`));
@@ -481,7 +482,8 @@ async function runDirectWorkflow(workflowName, options) {
 			},
 			workflowName,
 			inlineLockFile: overlay.inlineLockFile,
-			fullRepo: true
+			fullRepo: true,
+			...options.checkMode && { checkMode: options.checkMode }
 		});
 		if (!options.quiet) logger.info(pc.green(`Run started: ${triggerResult.runId}`));
 		if (options.wait === false) return triggerResult.status === "accepted";

package/dist/commands/test.d.ts

@@ -1,4 +1,5 @@
 import { type PayloadOptions } from '../test-runner/payload-builder.js';
+import { type CheckMode } from '@kici-dev/engine';
 /** Options for the kici test command (dry-run trigger preview) */
 export interface TestOptions extends PayloadOptions {
     /** Filter to specific workflow */
@@ -38,6 +39,12 @@ export interface RemoteRunOptions extends TestOptions {
     org?: string;
     /** Target orchestrator cluster name (overrides the per-org default). */
     orchestrator?: string;
+    /**
+     * Run mode resolved from --check / --fail-on-drift, threaded onto the dispatch
+     * payload so the orchestrator runs the agent step loop in the requested mode.
+     * Defaults to `apply`.
+     */
+    checkMode?: CheckMode;
 }
 /** Result of a single remote fixture run */
 export interface RemoteRunResult {

package/dist/llm-context/llms-full.txt

@@ -2108,6 +2108,28 @@ const build = step('build', {
 
 **StepRunFn type:** `(ctx: StepContext) => Promise<void>`
 
+**With a check facet (idempotent step):**
+
+Add a `check` function to describe _desired state_ instead of a fixed action. When
+`check` is present, `run` becomes the _apply_ function and receives the drift value
+`check` returned; `summarize` (required) renders that drift for logs and the
+dashboard; `whenInSync` optionally produces the step's outputs when already in sync.
+
+```typescript
+const configureNginx = step('configure-nginx', {
+  check: async (ctx) => ((await inSync(ctx)) ? null : { want: DESIRED }),
+  summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+  run: async (ctx, drift) => {
+    await writeConfig(drift.want);
+    return { reloaded: true };
+  },
+  whenInSync: async () => ({ reloaded: false }),
+});
+```
+
+A checked step can run in apply mode (converge) or `--check` preview mode (report
+drift, change nothing). See [Idempotent steps and check mode](../idempotent-steps.md).
+
 ### Per-job resources
 
 `options.resources` declares the CPU and memory the job needs. The orchestrator's auto-scaler uses these numbers to:
@@ -4021,6 +4043,70 @@ const publish = job('publish', {
 - The step never holds platform credentials — the request is relayed through the orchestrator, which mints the token on the step's behalf.
 - Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
 
+### ctx.kici.inventory.query(selector?) / .get(agentId)
+
+Query the **host inventory** — the roster of agents in the caller's orchestrator cluster — from inside a workflow. Each host is a `HostInventoryEntry`:
+
+```typescript
+interface HostInventoryEntry {
+  agentId: string;
+  labels: string[]; // flat-string grouping/tags dimension
+  properties: Record<string, string | number | boolean>; // typed host-vars dimension
+  hostname: string | null;
+  platform: string | null;
+  arch: string | null;
+  lifecycleClass: 'static' | 'ephemeral';
+  status: 'ready' | 'unreachable' | 'stale';
+  lastSeen: string; // ISO timestamp
+}
+```
+
+Two dimensions describe a host. **Labels** are flat strings used for grouping and targeting (the same labels `runsOn` / `runsOnAll` match). **Properties** are typed host-vars (`string | number | boolean`) — the place for facts like `region`, `cores`, or `gpu`. A host reports its own properties via the agent's `KICI_PROPERTIES` config, and an operator can pre-declare them with `kici-admin host declare --prop key=value`; the two are shallow-merged (agent-reported keys win).
+
+```typescript
+// All hosts:
+const all = await ctx.kici.inventory.query();
+
+// Server-side label filter (OR-of-AND include groups, plus exclude):
+const dbHosts = await ctx.kici.inventory.query({
+  include: [[{ kind: 'exact', value: 'role:db' }]],
+});
+
+// Property filtering is client-side — plain JS in the workflow:
+const euDbHosts = dbHosts.filter((h) => h.properties.region === 'eu');
+
+// One host by id:
+const host = await ctx.kici.inventory.get('box-1'); // HostInventoryEntry | null
+```
+
+**The label selector is applied server-side** (reusing the same glob/regex matchers as `runsOnAll`). **Property filtering is client-side** — you filter the returned array in plain JavaScript, so there is no query DSL to learn.
+
+**Headline use — dynamic-job fan-out.** A dynamic-job generator can query the inventory and return one job per matching host, fanning a workflow out across a fleet:
+
+```typescript
+const migrate = job('migrate', async (ctx) => {
+  const hosts = await ctx.kici.inventory.query({
+    include: [[{ kind: 'exact', value: 'role:db' }]],
+  });
+  return hosts
+    .filter((h) => h.properties.region === 'eu')
+    .map((h) =>
+      job(`migrate-${h.agentId}`, {
+        runsOn: [h.agentId],
+        run: async (c) => {
+          await c.$`./migrate.sh`;
+        },
+      }),
+    );
+});
+```
+
+A `runsOn` of a single host's `agentId` (as in `runsOn: [h.agentId]` above) **pins the job to that host**: the orchestrator routes it to that agent only, and queues it with the pin if the host is momentarily offline — the same host-pin path `runsOnAll` uses. A `runsOn` with multiple labels or a glob/regex pattern stays ordinary label routing.
+
+`ctx.kici.inventory` is available to **both** steps and dynamic-job generators (unlike `ctx.kici.oidc.token`, which is job-bound — the inventory is cluster-scoped, not job-bound).
+
+**Determinism caveat.** The inventory is **live**: it can change between when a dynamic-job generator first runs (at dispatch) and when it re-evaluates (at agent time). Generating jobs from `inventory.query()` therefore inherits the same non-determinism contract as `infrastructure.list()` — KiCI warns when the re-evaluated job set drifts (a sibling job name changed) and hard-errors when a targeted job vanishes. Prefer stable inputs where you can, and treat a fanned-out job set as a snapshot of the roster at generation time.
+
 ### ctx.attestProvenance({ subject })
 
 Build, sign, and persist a build-provenance attestation for an artifact your step produced. KiCI assembles an in-toto SLSA v1.0 provenance statement whose build identity (`repository`, `ref`, `sha`, run/job ids) comes from the platform — not from the step — so it cannot be spoofed, signs it, and stores a verifiable bundle that the dashboard surfaces and the `kici verify-attestation` CLI checks.
@@ -5582,7 +5668,7 @@ kici run remote push-main --org xyz789ghi012
 kici run remote push-main --orchestrator us-east
 
 # Run all push-related fixtures
-kici run remote push-*
+kici run remote 'push-*'
 
 # Run everything
 kici run remote --all
@@ -5753,7 +5839,8 @@ kici login [options]
 | --------------------------- | ------- | ---------------------------------------------- |
 | `--token <key>`             | none    | API key for direct authentication (legacy)     |
 | `--device`                  | false   | Force device authorization flow (headless/SSH) |
-| `--platform-endpoint <url>` | none    | Platform API base URL                          |
+| `--platform-endpoint <url>` | none    | Platform relay URL                             |
+| `--routing-key <key>`       | none    | Routing key for webhook source identification  |
 
 **Environment variables:**
 
@@ -6042,11 +6129,10 @@ kici approve <run-id> [options]
 
 **Options:**
 
-| Option            | Default | Description                                         |
-| ----------------- | ------- | --------------------------------------------------- |
-| `--job <name>`    | none    | Approve a held job (omit for a workflow-level hold) |
-| `--step <name>`   | none    | Approve a held step (used with `--job`)             |
-| `--reason <text>` | none    | Optional note recorded with the approval            |
+| Option           | Default | Description                                          |
+| ---------------- | ------- | ---------------------------------------------------- |
+| `--job <name>`   | none    | Approve a held job (omit for a workflow-level hold)  |
+| `--step <index>` | none    | Approve a held step by its index (used with `--job`) |
 
 **Examples:**
 
@@ -6057,8 +6143,8 @@ kici approve abc123
 # Approve a held job
 kici approve abc123 --job deploy-production
 
-# Approve a held step
-kici approve abc123 --job migrate-and-deploy --step apply-migration
+# Approve a held step (steps are addressed by index)
+kici approve abc123 --job migrate-and-deploy --step 1
 ```
 
 You must be eligible for at least one unsatisfied clause (a member of a named team, or a named user) and hold the `environments:write` or `ci_trust:write` permission. The command reports whether the element was released, how many clauses remain, or that it was rejected.
@@ -6079,11 +6165,11 @@ kici reject <run-id> --reason <text> [options]
 
 **Options:**
 
-| Option            | Default | Description                                        |
-| ----------------- | ------- | -------------------------------------------------- |
-| `--reason <text>` | none    | Required. Reason recorded with the rejection       |
-| `--job <name>`    | none    | Reject a held job (omit for a workflow-level hold) |
-| `--step <name>`   | none    | Reject a held step (used with `--job`)             |
+| Option            | Default | Description                                         |
+| ----------------- | ------- | --------------------------------------------------- |
+| `--reason <text>` | none    | Required. Reason recorded with the rejection        |
+| `--job <name>`    | none    | Reject a held job (omit for a workflow-level hold)  |
+| `--step <index>`  | none    | Reject a held step by its index (used with `--job`) |
 
 **Examples:**
 
@@ -6097,15 +6183,9 @@ kici reject abc123 --job deploy-production --reason "Wrong release branch"
 List secret contexts available for test runs. Shows context names and key names (not values).
 
 ```bash
-kici secrets list [options]
+kici secrets list
 ```
 
-**Options:**
-
-| Option             | Default | Description               |
-| ------------------ | ------- | ------------------------- |
-| `--endpoint <url>` | none    | Orchestrator URL override |
-
 Each "context" corresponds to an environment configured on the orchestrator. The output lists every environment whose `allowLocalExecution` flag is `true` (the gate that lets CLI-initiated test runs resolve secrets through that environment), along with the secret key names reachable from the environment's bound scopes.
 
 Only key names are shown — secret values are never returned over this endpoint.
@@ -6122,10 +6202,9 @@ kici types [options]
 
 **Options:**
 
-| Option              | Default | Description               |
-| ------------------- | ------- | ------------------------- |
-| `--kici-dir <path>` | `.kici` | Path to .kici directory   |
-| `--endpoint <url>`  | none    | Orchestrator URL override |
+| Option              | Default | Description             |
+| ------------------- | ------- | ----------------------- |
+| `--kici-dir <path>` | `.kici` | Path to .kici directory |
 
 **Prerequisites:** Must be authenticated via `kici login`.
 
@@ -6139,9 +6218,6 @@ kici types
 
 # Use custom .kici directory
 kici types --kici-dir packages/app/.kici
-
-# Override orchestrator endpoint
-kici types --endpoint https://my-orchestrator.example.com
 ```
 
 **How it works:**
@@ -6823,7 +6899,7 @@ The lock file (`kici.lock.json`) is a JSON file with the following top-level fie
 
 | Field           | Description                                                                                                                                                                                                                                                                                                                                           |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schemaVersion` | Lock file schema version (currently 17). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
+| `schemaVersion` | Lock file schema version (currently 20). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
 | `source`        | Reference to the source file and export (e.g., `{ file: “.kici/workflows/ci.ts”, export: “#default” }`).                                                                                                                                                                                                                                              |
 | `contentHash`   | SHA-256 of the serialized lock file content (excluding itself). Changes when any workflow, trigger, or job changes.                                                                                                                                                                                                                                   |
 | `lockfileHash`  | SHA-256 of the detected package manager's lockfile, used as the dependency cache key. The lockfile is `.kici/package-lock.json` for npm, or the repo-root `pnpm-lock.yaml` / `yarn.lock` for a pnpm/yarn workspace; the hash input is prefixed with the manager name so a manager change is a guaranteed cache miss. Omitted when no lockfile exists. |
@@ -6998,12 +7074,14 @@ kici run remote
 kici run remote push-main
 
 # Run all fixtures matching a glob
-kici run remote push-*
+kici run remote 'push-*'
 
 # Run everything
 kici run remote --all
 ```
 
+The single quotes keep your shell from expanding `push-*` against local files, so the pattern reaches KiCI intact for its own fixture-glob matching.
+
 ## Fixture reference
 
 ### Event types
@@ -7099,7 +7177,7 @@ kici run remote
 kici run remote push-main
 
 # Glob matching -- run all push-related fixtures
-kici run remote push-*
+kici run remote 'push-*'
 
 # Run all fixtures sequentially
 kici run remote --all
@@ -8843,6 +8921,135 @@ Non-push triggers work too — `pr()`, `tag()`, `comment()`, `release()`, `workf
 
 ---
 
+## Idempotent steps and check mode
+
+Source: https://docs.kici.dev/user/idempotent-steps/
+
+An **idempotent step** describes _desired state_ rather than a fixed sequence of
+commands. You give the step a `check` function that inspects the world and a
+`run` function that converges it. KiCI then executes the workflow in one of two
+modes:
+
+- **Apply mode** (the default): for each step, `check()` runs first; on drift the
+  step applies the change; when already in sync the step is skipped.
+- **Check mode** (`--check`): for each step, `check()` runs and KiCI reports what
+  _would_ change — **without changing anything**. This is the same model as a
+  dry-run plan: you see the drift before any side effect happens.
+
+This turns a workflow into convergent configuration management: re-running an
+apply is safe (in-sync steps do nothing), and a check-mode run is a read-only
+preview you can gate a build on.
+
+## Authoring a checked step
+
+Add a `check` facet to the existing `step()` factory. When `check` is present,
+`run` becomes the _apply_ function and receives the drift value `check`
+returned:
+
+```typescript
+import { step, z } from '@kici-dev/sdk';
+
+const configureNginx = step('configure-nginx', {
+  // optional schema for the drift value — gives the dashboard a typed shape
+  drift: z.object({ want: z.string() }),
+
+  // read-only inspection; return null when already in the desired state
+  check: async (ctx) => {
+    const current = await ctx.$`nginx -T`;
+    return current.stdout.includes(DESIRED) ? null : { want: DESIRED };
+  },
+
+  // human-readable preview line — REQUIRED when check is set. It is the drift's
+  // serializable face: it streams to the logs and persists for the dashboard.
+  summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+
+  // apply — runs only when check returned drift (apply mode); receives that drift
+  run: async (ctx, drift) => {
+    await writeConfig(drift.want);
+    return { reloaded: true };
+  },
+
+  // optional — runs when check returned null, to produce the step's outputs
+  whenInSync: async () => ({ reloaded: false }),
+});
+```
+
+### The facet fields
+
+| Field        | Required         | Purpose                                                                |
+| ------------ | ---------------- | ---------------------------------------------------------------------- |
+| `check`      | to opt in        | Read-only inspection. Return a drift value, or `null` when in sync.    |
+| `summarize`  | when `check` set | Human-readable, serializable preview of the drift. Streams + persists. |
+| `run`        | always           | Apply function. With `check`, it receives the drift as its second arg. |
+| `whenInSync` | optional         | Produces the step's outputs when `check` returned `null`.              |
+| `drift`      | optional         | Schema that validates / shapes the drift value.                        |
+
+`summarize` is **required** whenever `check` is declared. `run` and `whenInSync`
+both produce the same output type — one output shape per step, whichever path
+runs. Every other step facet (`cache`, `rules`, `continueOnError`, `timeout`,
+`requireApproval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
+
+A plain `step()` without `check` keeps its exact current behavior — the check
+facet is fully optional.
+
+## Run modes
+
+A run carries one of three modes:
+
+| Mode                  | CLI flags                 | Behavior                                                                                   |
+| --------------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
+| `apply`               | (default, no flags)       | Converge: drift ⇒ apply ⇒ **applied**; null ⇒ **in sync** (skipped).                       |
+| `check`               | `--check`                 | Preview only: drift ⇒ **would change**; null ⇒ **in sync**. Never applies. Always exits 0. |
+| `check-fail-on-drift` | `--check --fail-on-drift` | Same as check, but the run **fails** if any step reports drift.                            |
+
+Per-step outcomes:
+
+- **applied** — drift was found and the step applied the change (apply mode).
+- **in sync** — `check` returned `null`; nothing to do.
+- **would change** — drift was found in check mode; the change was previewed, not applied.
+- **no check** — a plain step (no `check`) reached under check mode. A
+  side-effecting step can't be safely previewed, so it is skipped.
+
+In check mode KiCI never invokes a checked step's `run` (apply) — the preview is
+guaranteed side-effect-free.
+
+## Running in check mode
+
+`--check` and `--fail-on-drift` work on both local and remote runs:
+
+```bash
+# Apply (default): converge the workflow.
+kici run local push
+kici run remote my-fixture
+
+# Check: report drift, change nothing. Always exits 0.
+kici run local push --check
+kici run remote my-fixture --check
+
+# Check + fail on drift: exit non-zero (2) locally, or fail the run remotely,
+# when any step reports drift. Use this as a CI gate ("fail the build if prod
+# has drifted").
+kici run local push --check --fail-on-drift
+```
+
+`--fail-on-drift` only modifies check mode — passing it without `--check` is an
+error.
+
+## Where outcomes show up
+
+A check-mode run is labeled in the dashboard with a **CHECK MODE — preview**
+badge on the run header. Each step shows its outcome chip — applied / in sync /
+would change / no check — and, when drift was detected, the `summarize` line
+describing what would change. The rendering is read-only.
+
+## See also
+
+- [Idempotent SDK helpers](./sdk/idempotent.md) — the `idempotent()` / `idempotentStep()` convenience wrappers, which always apply on drift inside a single step (no run-level check mode).
+- [Core SDK reference](./sdk/core.md) — the `step()`, `job()`, and `workflow()` factories the check facet extends.
+- [Lock file and drift](./lock-file-and-drift.md) — how the lock file carries step capability flags.
+
+---
+
 ## Private npm registries
 
 Source: https://docs.kici.dev/user/private-registries/
@@ -9628,7 +9835,82 @@ forge side looks like:
 Use the App when you can; the `github-repo` preset is a fallback for
 repos where you can't install an App.
 
-## Create the GitHub App on GitHub's side
+## One-click setup (recommended)
+
+`kici-admin source add github --manifest` creates **and** configures the
+GitHub App for you via GitHub's App Manifest flow. KiCI builds a manifest
+with the exact permissions, events, webhook URL, and webhook secret baked
+in, so you never pick permissions, paste a URL, generate a secret, or
+download a `.pem` by hand — the App is correct by construction.
+
+```bash
+kici-admin --url http://<orchestrator-host>:4000 --token $KICI_BOOTSTRAP_ADMIN_TOKEN \
+  source add github --manifest --name my-org --github-org my-org
+```
+
+`--github-org <slug>` creates the App under a GitHub **organization** (the
+`<slug>` is the org's `github.com/<slug>` URL slug, not its display name) — the
+recommended default, since org-owned Apps can be installed across the org. Drop
+the flag only when you deliberately want a personal-account App, which can be
+installed solely on repos you own. You need permission to create Apps in that
+org (be an org owner, or have the org allow member App creation).
+
+What happens:
+
+1. The CLI resolves your org's webhook URL and opens GitHub with a
+   pre-filled App manifest. You click **"Create GitHub App"** once — the
+   only manual step.
+2. GitHub redirects back to a localhost callback; the CLI exchanges the
+   returned setup code for the App's id, private key, and webhook secret.
+   **The private key is exchanged and stored only on your orchestrator
+   host — it never transits the KiCI Platform.**
+3. The CLI stores the credentials encrypted under `KICI_SECRET_KEY` and
+   registers the routing key `github:<appId>`, reusing the same storage
+   path as the manual flow.
+4. It opens the App's install page so you can pick repos, then verifies
+   end-to-end: it waits for the installation, mints an installation token,
+   and confirms repo access before declaring success.
+
+```
+$ kici-admin source add github --manifest --name my-org --github-org my-org
+→ Opening GitHub to create your App…
+→ ✓ App created (id 12345), credentials captured
+→ ✓ Stored on orchestrator (encrypted), registered as github:12345
+→ Install the App on your repos: https://github.com/apps/my-org/installations/new
+→ ✓ Installation detected (account my-org)
+→ ✓ Credentials verified (3 repositories reachable)
+
+GitHub App "my-org" is live.
+  Webhook: https://<platform-host>/webhook/<orgId>/github
+```
+
+**Flags:**
+
+| Flag                  | Effect                                                                                                                                                                                                              |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--name <name>`       | The App name on GitHub (required).                                                                                                                                                                                  |
+| `--github-org <slug>` | Create the App under a GitHub organization instead of your personal account.                                                                                                                                        |
+| `--no-browser`        | Headless mode: the CLI prints a `kici.dev` URL to open, then reads the setup code you paste back. The page is pure client-side — it only displays the short-lived code, which is useless once the CLI exchanges it. |
+
+The manifest flow always creates a **new** App on GitHub. If a source for
+that App id already exists on the orchestrator, the command refuses — use
+`source update` to rotate an existing App's credentials.
+
+If any step after App creation fails (e.g. storage), the CLI prints the
+captured App id and writes the private key to a `0600` file, then tells
+you how to finish with the manual `source add github` command — so a
+created App is never orphaned.
+
+Independent-mode orchestrators have no GitHub-App ingress (it is
+Platform-relayed), so the manifest flow is unavailable there; use a
+generic webhook source instead.
+
+## Manual setup (fallback)
+
+When you'd rather create the App by hand — or your environment can't run
+the manifest flow — follow these steps.
+
+### Create the GitHub App on GitHub's side
 
 1. **Decide the App scope.** User-owned Apps can only be installed on
    repos you own; organization-owned Apps can be installed anywhere in
@@ -9704,7 +9986,7 @@ repos where you can't install an App.
    KiCI runs. Re-install to add repos later — this is live and
    revocable without redeploying the App.
 
-## Register the App with the orchestrator
+### Register the App with the orchestrator
 
 With the App ID, private key `.pem`, and webhook secret in hand:
 
@@ -10283,7 +10565,7 @@ Source: https://docs.kici.dev/architecture/data-flows/
 
 This document describes the key data flows through the KiCI architecture: webhook delivery, job execution, developer-initiated remote runs, dependency caching, re-run and cancel, trace ID propagation, internal event routing, and generic webhook ingestion.
 
-> **Lock file schema version:** The lock file uses schema version 17, which widens per-job init to typed presets (`mise` / `{ mise }`) and `auto` detection on top of v16's normalized approval config, v15's per-job init config, v14's declarative cache specs, v11's `LockInlineValue` for pure function inline evaluation, v10's simplified negative patterns (! prefix in repos/paths arrays), v9's global workflow repos matching, and v8's runsOn polymorphic type support.
+> **Lock file schema version:** The lock file uses schema version 21, which adds the `CheckMode` / `CheckStepOutcome` enums for check-mode step execution on top of v20's `LabelMatcher` (exact/regex) selectors for `runsOn`/`runsOnAll`/`excludeLabels`, v19's `maxParallel`/`failFast` fan-out concurrency, v18's `runsOnAll` host fan-out predicate and `onUnreachable` policy, v17's typed init presets (`mise` / `{ mise }`) and `auto` detection, v16's normalized approval config, v15's per-job init config, v14's declarative cache specs, v11's `LockInlineValue` for pure function inline evaluation, v10's simplified negative patterns (! prefix in repos/paths arrays), v9's global workflow repos matching, and v8's runsOn polymorphic type support.
 
 ## Webhook delivery flow
 
@@ -10489,7 +10771,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 17.
+- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 21.
 - **Cross-source / global-workflow dispatch** (a workflow registered against source A fired by a webhook on source B) bypasses both caches. The registration's lock file entry still carries `contentHash`, but the cross-source path always clone-and-installs — the eval temp dir doesn't ship `@kici-dev/sdk`. The execution agent still verifies `contentHash` against the cloned source for drift detection.
 
 ### Build deduplication
@@ -10528,7 +10810,7 @@ Both source and dep caches use `S3CacheStorage` as the sole backend. The `CacheS
 
 Cache keys reflect that source tarballs and deps have different platform characteristics:
 
-- **Source:** `source/{contentHash}.tar.gz` — platform-agnostic. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(schemaVersion + ":" + rawSource [+ "\0" + assetDigest])`).
+- **Source:** `source/{contentHash}.tar.gz` — platform-agnostic. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(COMPILE_SCHEMA_VERSION + ":" + rawSource [+ "\0" + assetDigest])`, where `COMPILE_SCHEMA_VERSION = 5` and line endings are normalized to LF so the hash agrees across platforms).
 - **Deps:** `deps/{platform}-{arch}/{lockfileHash}.tar.gz` (e.g., `deps/linux-arm64/def456.tar.gz`) — platform-specific. Native dependencies in `node_modules` differ across architectures, so each platform/arch combination gets its own cache entry.
 
 The orchestrator derives the target platform/arch for dep cache lookups by probing `AgentRegistry.findAvailable()` with the workflow's first job's `runsOn` labels to find a representative matching agent, then using that agent's platform and arch. Falls back to `linux/x64` if no matching agents are registered.
@@ -11173,7 +11455,9 @@ This model also enables fully self-hosted deployment: all three tiers can run on
 
 ### Platform
 
-The Platform tier is a thin webhook router. It verifies inbound webhook signatures, relays the payload to the correct orchestrator over WebSocket, and writes a delivery row to its event log. It does not process, store, or execute any customer code. Multi-tenant SaaS specifics (Stripe-driven billing, dashboard surface, identity provider integration) are documented in the internal docs.
+The Platform is KiCI's hosted, multi-tenant control plane. It provides the hosted dashboard (run listing, run detail, live log streaming, settings), identity and authentication (OIDC, personal access tokens, API keys, JWTs), multi-tenant organization / team / role-based access management, billing, and webhook ingestion -- verifying inbound signatures (HMAC-SHA256, timing-safe) and relaying payloads to the correct orchestrator over WebSocket. It aggregates execution telemetry and status forwarded by orchestrators, registers sources, and matchmakes peers for clustering.
+
+The Platform never processes, stores, or executes customer code, and never sees customer secrets. It routes webhook payloads and aggregates execution status; the code itself only ever lives on the customer's orchestrator and agent tiers. In the execution path the Platform is deliberately thin -- it does not run jobs -- but functionally it is a full platform, not merely a relay. The hosted Platform is EU-sovereign.
 
 ### Orchestrator (`@kici-dev/orchestrator`)
 
@@ -11208,7 +11492,7 @@ The agent is the execution worker. It runs on customer infrastructure and has fu
 
 Shared business logic used by all three tiers. Single source of truth for cross-tier concerns. Has no internal `@kici-dev/*` dependencies -- only a handful of third-party libraries.
 
-- Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, test run lifecycle, observer channel, log pull, run events, peer-to-peer, cluster join, and source registration)
+- Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, the test-relay control plane, log pull, run events, peer-to-peer, cluster join, and source registration)
 - Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster)
 - Trigger matching engine (branch, path, event evaluation)
 - Execution state machine (11 states, 16 events, pure functions)

package/dist/llm-context/llms.txt

@@ -52,6 +52,7 @@ The full markdown bundle of every page indexed here is available at https://docs
 - [Environments](https://docs.kici.dev/user/environments/): Configure deployment environments with variables, secrets, and protection rules
 - [Event system](https://docs.kici.dev/user/events/): How KiCI's event model works -- event types, the registration model, event matching, and circuit breaker protection
 - [Global workflows](https://docs.kici.dev/user/global-workflows/): Cross-repo workflows that run on events from any repo in the same org
+- [Idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/): Declare desired state with a step check facet, then run in apply or --check preview mode
 - [Private npm registries](https://docs.kici.dev/user/private-registries/): Authenticate `npm install` against private registries (CodeArtifact, GitHub Packages, Verdaccio, …) from a workflow's `.kici/package.json`
 - [Build provenance and attestations](https://docs.kici.dev/user/provenance/): Generate and verify signed SLSA provenance for the artifacts your workflows build
 - [Secrets](https://docs.kici.dev/user/secrets/): How to access secrets in KiCI workflow steps

package/dist/local-executor/index.js

@@ -15,7 +15,7 @@ import path from "node:path";
 import pc from "picocolors";
 import { writeFile } from "node:fs/promises";
 import { logger } from "@kici-dev/core";
-import { matchAllWorkflows } from "@kici-dev/engine";
+import { CheckMode, CheckStepOutcome, matchAllWorkflows } from "@kici-dev/engine";
 import os from "node:os";
 //#region src/local-executor/index.ts
 /**
@@ -169,7 +169,8 @@ async function runWorkflowBody(workflow, ctx, options, secrets, kiciDir, concurr
 				kiciDir,
 				execDir: ctx.execDir,
 				jobOutputsMap,
-				signal
+				signal,
+				checkMode: options.checkMode
 			});
 		},
 		isSuccess: (result) => result.status === "success" || result.status === "skipped"
@@ -305,6 +306,11 @@ async function executeLocal(options) {
 			if (!isQuiet) logger.info(pc.green(`JUnit XML written to ${options.junit}`));
 		}
 		if (!isQuiet) displayLocalSummary(workflowResults);
+		if (options.checkMode === CheckMode.enum["check-fail-on-drift"] && hasDrift(workflowResults)) {
+			if (!isQuiet) logger.info(pc.yellow("Drift detected in check mode (--fail-on-drift): exiting with code 2"));
+			if (materialized && !options.keep) await materialized.cleanup();
+			process.exit(2);
+		}
 		return allSucceeded;
 	} finally {
 		if (materialized) if (allSucceeded && !options.keep) await materialized.cleanup();
@@ -312,6 +318,13 @@ async function executeLocal(options) {
 	}
 }
 /**
+* True when any step across all workflows reported drift (`dry-run` outcome) —
+* the signal `check-fail-on-drift` uses to exit non-zero.
+*/
+function hasDrift(results) {
+	return results.some((wf) => wf.jobs.some((job) => (job.steps ?? []).some((s) => s.checkOutcome === CheckStepOutcome.enum["dry-run"])));
+}
+/**
 * Get default concurrency based on available CPU parallelism.
 */
 function getDefaultConcurrency() {

package/dist/local-executor/job-runner.d.ts

@@ -8,6 +8,7 @@
  * - Single-job step-by-step execution with rules, abort, and output chaining
  */
 import type { Workflow, OutputsMap } from '@kici-dev/sdk';
+import { CheckMode } from '@kici-dev/engine';
 import type { SimulatedEvent } from '@kici-dev/engine';
 import type { ParsedSecrets } from '../test-runner/secrets-file.js';
 import type { ResolvedJob, LocalJobResult } from './types.js';
@@ -24,6 +25,8 @@ export interface JobExecutionContext {
     execDir: string;
     jobOutputsMap: OutputsMap;
     signal: AbortSignal;
+    /** Run mode for idempotent steps. Defaults to `apply` when unset. */
+    checkMode?: CheckMode;
 }
 /**
  * Resolve all jobs in a workflow, expanding matrix jobs and evaluating dynamic jobs.

package/dist/local-executor/job-runner.js

@@ -8,7 +8,8 @@ import { toEventPayload } from "./to-event-payload.js";
 import { pathToFileURL } from "node:url";
 import path from "node:path";
 import { applyIncludeExclude, expandMatrix, isDynamicJobFn, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
-import { formatMatrixSuffix } from "@kici-dev/engine";
+import { CheckMode, CheckStepOutcome, formatMatrixSuffix } from "@kici-dev/engine";
+import { runIdempotentStep } from "@kici-dev/core/idempotency";
 //#region src/local-executor/job-runner.ts
 /**
 * Job resolution (matrix/dynamic) and single-job execution with step context.
@@ -51,6 +52,45 @@ function resolveNeedName(need) {
 	return need.name;
 }
 /**
+* Run one local step honoring the run-level {@link CheckMode}, reusing the
+* `runIdempotentStep` primitive for checked steps (never hand-rolled branching).
+* Mirrors the agent step loop's check phase so `kici run local --check` and a
+* remote check run produce identical per-step outcomes.
+*/
+async function runLocalStepWithCheckMode(step, ctx, checkMode) {
+	if (!step.check) {
+		if (checkMode !== CheckMode.enum.apply) return {
+			checkOutcome: CheckStepOutcome.enum.no_check,
+			status: "skipped",
+			outputs: void 0
+		};
+		return {
+			status: "success",
+			outputs: await step.run(ctx)
+		};
+	}
+	const res = await runIdempotentStep({
+		name: step.name,
+		check: () => step.check(ctx),
+		summarize: step.summarize,
+		apply: (drift) => step.run(ctx, drift),
+		whenInSync: step.whenInSync ? () => step.whenInSync(ctx) : void 0
+	}, {
+		dryRun: checkMode !== CheckMode.enum.apply,
+		yes: true,
+		log: (line) => ctx.log.info(line)
+	});
+	const driftSummary = res.drift != null ? step.summarize(res.drift) : void 0;
+	const status = res.outcome === CheckStepOutcome.enum.applied ? "success" : "skipped";
+	const mappedStatus = res.outcome === CheckStepOutcome.enum["dry-run"] ? "success" : status;
+	return {
+		checkOutcome: res.outcome,
+		status: mappedStatus,
+		outputs: res.result,
+		...driftSummary !== void 0 && { driftSummary }
+	};
+}
+/**
 * Maintain the base-name `{ byMatrix, merged }` envelope as each matrix child
 * completes. `merged` is rebuilt last-write-wins in suffix order so the result
 * is deterministic regardless of child completion order — matching the remote
@@ -101,6 +141,10 @@ async function resolveJobs(workflow, event) {
 					scalers: [],
 					agents: []
 				}) },
+				inventory: {
+					query: () => Promise.resolve([]),
+					get: () => Promise.resolve(null)
+				},
 				oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available during local execution")) }
 			}
 		});
@@ -267,14 +311,18 @@ async function executeResolvedJobInner(resolvedJob, context, startTime) {
 		formatter.logStepStart(expandedName, normalizedStep.name);
 		const stepStart = Date.now();
 		try {
-			const outputs = await normalizedStep.run(stepCtx);
+			const checkMode = context.checkMode ?? CheckMode.enum.apply;
+			const phase = await runLocalStepWithCheckMode(normalizedStep, stepCtx, checkMode);
+			const outputs = phase.outputs;
 			const stepDuration = Date.now() - stepStart;
 			formatter.logStepComplete(expandedName, normalizedStep.name, stepDuration);
 			const stepResult = {
 				name: normalizedStep.name,
-				status: "success",
+				status: phase.status,
 				durationMs: stepDuration,
-				outputs
+				outputs,
+				...phase.checkOutcome !== void 0 && { checkOutcome: phase.checkOutcome },
+				...phase.driftSummary !== void 0 && { driftSummary: phase.driftSummary }
 			};
 			if (outputs != null) outputsMap.set(normalizedStep.name, outputs);
 			stepResults.push(stepResult);

package/dist/local-executor/output-streamer.js

@@ -95,7 +95,9 @@ function formatLocalJsonResult(results) {
 					name: step.name,
 					status: step.status,
 					durationMs: step.durationMs,
-					...step.error && { error: step.error.message }
+					...step.error && { error: step.error.message },
+					...step.checkOutcome && { checkOutcome: step.checkOutcome },
+					...step.driftSummary && { driftSummary: step.driftSummary }
 				})),
 				...job.ruleResults && job.ruleResults.length > 0 && { ruleResults: job.ruleResults.map((r) => ({
 					label: r.label,

package/dist/local-executor/types.d.ts

@@ -1,4 +1,5 @@
 import type { MatrixValues, Job } from '@kici-dev/sdk';
+import type { CheckMode } from '@kici-dev/engine';
 import type { JobResult } from '../test-runner/job-executor.js';
 /**
  * All CLI flags for `kici run local`.
@@ -42,6 +43,12 @@ export interface RunLocalOptions {
     inPlace?: boolean;
     /** --keep: always retain the isolated tmp checkout (default: keep only on failure) */
     keep?: boolean;
+    /**
+     * Run mode resolved from --check / --fail-on-drift. Threads to the agent step
+     * loop: `apply` (default) converges, `check` previews drift, `check-fail-on-drift`
+     * previews drift and fails the run if any step reports drift. Defaults to `apply`.
+     */
+    checkMode?: CheckMode;
 }
 /**
  * A job after matrix expansion with resolved values.

package/dist/lockfile/generator.js

@@ -650,6 +650,8 @@ function transformSteps(steps, gitRoot) {
 			},
 			...step.onCancel !== void 0 && { hasOnCancel: true },
 			...step.cleanup !== void 0 && { hasCleanup: true },
+			...step.check !== void 0 && { hasCheck: true },
+			...step.whenInSync !== void 0 && { hasWhenInSync: true },
 			...step.requireApproval !== void 0 && { approval: toLockApproval(step.requireApproval) }
 		};
 	});

package/dist/remote/platform-client.d.ts

@@ -10,6 +10,7 @@
  * The overlay tarball does NOT flow through here: `initUpload` returns an
  * external presigned URL the CLI PUTs to directly (data plane).
  */
+import type { CheckMode } from '@kici-dev/engine';
 export declare class AuthenticationError extends Error {
     constructor(message?: string);
 }
@@ -70,6 +71,12 @@ export interface PlatformTriggerInput {
     secrets?: Record<string, string>;
     encryptedSecrets?: string;
     encryptedSecretsKey?: string;
+    /**
+     * Run mode for the dispatched run (`apply` | `check` | `check-fail-on-drift`).
+     * The Platform relays it onto the dispatch event so the orchestrator runs the
+     * agent step loop in the requested mode. Omitted means `apply`.
+     */
+    checkMode?: CheckMode;
 }
 export interface PlatformTriggerResponse {
     runId: string;

package/dist/templates/package-json.js

@@ -1,6 +1,6 @@
 import "../chunk-BTugEXQM.js";
 //#region src/templates/package-json.ts
-const sdkVersion = "0.1.19";
+const sdkVersion = "0.1.21";
 /**
 * Generate package.json content for .kici/ directory
 *

package/dist/test-runner/job-executor.d.ts

@@ -1,5 +1,6 @@
 import type { Job, Workflow } from '@kici-dev/sdk';
 import type { OutputsMap, StepRefMap } from '@kici-dev/sdk';
+import type { CheckStepOutcome } from '@kici-dev/engine';
 import type { SimulatedEvent } from '@kici-dev/engine';
 import type { RuleResult } from '@kici-dev/sdk';
 import type { ParsedSecrets } from './secrets-file.js';
@@ -15,10 +16,14 @@ interface SdkOutputSetters {
 }
 export interface StepResult {
     name: string;
-    status: 'success' | 'failure';
+    status: 'success' | 'failure' | 'skipped';
     durationMs: number;
     error?: Error;
     outputs?: Record<string, unknown>;
+    /** Idempotent per-step outcome under a non-default check mode. */
+    checkOutcome?: CheckStepOutcome;
+    /** Human-readable drift summary, present when drift was detected. */
+    driftSummary?: string;
 }
 export interface JobResult {
     name: string;

package/dist/test-runner/step-context.js

@@ -133,6 +133,10 @@ function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix,
 				scalers: [],
 				agents: []
 			}) },
+			inventory: {
+				query: () => Promise.resolve([]),
+				get: () => Promise.resolve(null)
+			},
 			oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available in the local test runner")) }
 		},
 		cache: {

package/dist/types.d.ts

@@ -23,7 +23,7 @@ export interface LockApproval {
     readonly timeoutSeconds?: number;
 }
 /** Schema version - re-exported from engine as single source of truth */
-export declare const SCHEMA_VERSION: 20;
+export declare const SCHEMA_VERSION: 21;
 /**
  * Source file reference with meaningful path.
  * Format: file is relative path from git root, export uses hash syntax.
@@ -334,6 +334,15 @@ export interface LockStep {
     readonly hasOnCancel?: boolean;
     /** Whether this step has a cleanup hook. */
     readonly hasCleanup?: boolean;
+    /**
+     * Whether this step declares an idempotent `check` facet. When true the
+     * orchestrator knows the step is check-capable and a run can be dispatched in
+     * check mode. The check/apply closures themselves are never serialized — the
+     * agent re-evaluates the real workflow TypeScript.
+     */
+    readonly hasCheck?: boolean;
+    /** Whether this step declares a `whenInSync` facet (produces outputs when in sync). */
+    readonly hasWhenInSync?: boolean;
     /** Normalized approval gate; when set the step pauses for a human approval. */
     readonly approval?: LockApproval;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/compiler",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Compiler and CLI for KiCI workflows. Compiles `.kici/workflows/*.ts` to a `kici.lock.json` file consumed by the orchestrator and agents, and runs workflows locally or against a remote orchestrator.",
   "keywords": [
     "ci",
@@ -63,11 +63,11 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.19",
-    "@kici-dev/engine": "0.1.19"
+    "@kici-dev/core": "0.1.21",
+    "@kici-dev/engine": "0.1.21"
   },
   "peerDependencies": {
-    "@kici-dev/sdk": "0.1.19"
+    "@kici-dev/sdk": "0.1.21"
   },
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4"

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/compiler@0.1.19",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fcompiler/0.1.19/3822508c-fd16-4b1b-a7f4-3a5038adca82",
+  "name": "@kici-dev/compiler@0.1.21",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fcompiler/0.1.21/4162fc88-26bd-41e3-8085-1dc26bb0eb1f",
   "creationInfo": {
-    "created": "2026-06-19T05:11:14Z",
+    "created": "2026-06-23T05:10:19Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -484,7 +484,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/compiler",
-      "versionInfo": "0.1.19",
+      "versionInfo": "0.1.21",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -495,16 +495,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/compiler@0.1.19"
+          "referenceLocator": "pkg:npm/%40kici-dev/compiler@0.1.21"
         }
       ],
       "description": "Compiler and CLI for KiCI workflows. Compiles `.kici/workflows/*.ts` to a `kici.lock.json` file consumed by the orchestrator and agents, and runs workflows locally or against a remote orchestrator.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.21",
       "name": "@kici-dev/core",
-      "versionInfo": "0.1.19",
+      "versionInfo": "0.1.21",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -515,16 +515,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.19"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.21"
         }
       ],
       "description": "Light shared utilities for the KiCI stack (logging, errors, formatting, crypto, zx init, the TypeScript ESM loader hook). No server-side dependencies.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.19",
+      "versionInfo": "0.1.21",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -535,16 +535,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.19"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.21"
         }
       ],
       "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-sdk-0.1.19",
+      "SPDXID": "SPDXRef-Package--kici-dev-sdk-0.1.21",
       "name": "@kici-dev/sdk",
-      "versionInfo": "0.1.19",
+      "versionInfo": "0.1.21",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -555,7 +555,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.19"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.21"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -3222,17 +3222,17 @@
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-sdk-0.1.19",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-sdk-0.1.21",
       "relationshipType": "DEPENDS_ON"
     },
     {
@@ -3301,82 +3301,82 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.135.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-jose-6.2.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.4",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.19",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.21",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.19",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.21",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-micromatch-4.0.8",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-sdk-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },