@kici-dev/compiler 0.1.27 → 0.2.0

package/dist/commands/runs/list.js

@@ -15,7 +15,13 @@ async function runsListCommand(options = {}) {
 			return true;
 		}
 		if (page.runs.length === 0) {
-			console.log(pc.gray("No runs found."));
+			const activity = await client.getWebhookActivity().catch(() => null);
+			if (activity && activity.received > 0) {
+				const win = activity.windowMinutes === 60 ? "the last hour" : `the last ${activity.windowMinutes} minutes`;
+				const headline = activity.orchestratorUnavailable || activity.matched === void 0 ? `${activity.received} webhooks received in ${win} but none produced a run` : `${activity.received} webhooks received in ${win}, ${activity.matched} matched`;
+				console.log(pc.yellow(`${headline}.`));
+				console.log(pc.gray(`Run ${pc.cyan("kici preview push")} to test your triggers locally.`));
+			} else console.log(pc.gray("No runs found."));
 			return true;
 		}
 		const rows = page.runs.map((r) => [
@@ -36,7 +42,7 @@ async function runsListCommand(options = {}) {
 			"started",
 			"duration"
 		], rows));
-		console.log(pc.gray(`\nPage ${page.page} · ${page.runs.length} of ${page.total}${page.hasMore ? " (more — use --page)" : ""}`));
+		console.log(pc.gray(`\n${page.runs.length} of ~${page.approxTotal} runs${page.nextCursor ? `  (more — use --cursor ${page.nextCursor})` : ""}`));
 		return true;
 	} catch (err) {
 		logger.error(pc.red(err instanceof DashboardClientError ? err.message : toErrorMessage(err)));

package/dist/commands/verify-attestation.d.ts

@@ -3,7 +3,9 @@ export interface VerifyAttestationOptions {
     bundle?: string;
     /**
      * Trusted issuer URL (online discovery) or a self-contained `{ issuer, jwks }`
-     * file. Optional — defaults to the hosted KiCI Platform's provenance issuer.
+     * file. Optional — defaults to the configured orchestrator, falling back to
+     * the hosted KiCI Platform's provenance issuer when no orchestrator is
+     * configured.
      */
     trustRoot?: string;
     /** Expected token audience (defaults to the KiCI provenance audience). */

package/dist/commands/verify-attestation.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { resolveTrustRoot } from "../provenance-trust-root.js";
+import { loadGlobalConfig } from "../remote/config.js";
 import "../remote/prod-defaults.js";
 import pc from "picocolors";
 import { readFile } from "node:fs/promises";
@@ -16,10 +17,14 @@ import { verifyKiciBundle } from "@kici-dev/engine/provenance/verify";
 * `@kici-dev/engine`. The engine owns all crypto; this command is the thin Node
 * wrapper (fs / fetch / artifact digest / output).
 *
-* `--trust-root` is optional: when omitted it defaults to the hosted KiCI
-* Platform's provenance issuer, so the common case (verifying a bundle attested
-* on the hosted platform) needs no flag. Pass `--trust-root` to verify against a
-* different environment (e.g. staging) or an offline `{ issuer, jwks }` file.
+* `--trust-root` is optional: when omitted it defaults to the CONFIGURED
+* ORCHESTRATOR (its own `.well-known`), which now owns provenance signing — the
+* natural root of trust for a self-hosted customer. When no orchestrator is
+* configured it falls back to the hosted KiCI Platform's provenance issuer (for
+* historical Platform-signed bundles, which keep verifying forever). Pass
+* `--trust-root` to verify against a different environment or an offline
+* `{ issuer, jwks }` file (air-gap). The token `iss` is always pinned to the
+* trust root out-of-band — a bundle can never name its own trusted issuer.
 *
 * Returns a boolean (verified) so `cli.ts` can map it to an exit code (0/1).
 */
@@ -29,9 +34,14 @@ async function verifyAttestationCommand(artifact, options = {}) {
 			logger.error(pc.red("Error: --bundle <path|url> is required"));
 			return false;
 		}
-		const trustRoot = options.trustRoot ?? "https://api.kici.dev";
+		const configuredOrchestrator = (await loadGlobalConfig().catch(() => null))?.endpoint;
+		const trustRoot = options.trustRoot ?? configuredOrchestrator ?? "https://api.kici.dev";
 		const usingDefault = !options.trustRoot;
-		if (usingDefault) logger.info(pc.gray(`Using default trust root ${trustRoot} (pass --trust-root to override)`));
+		const usingConfiguredOrchestrator = usingDefault && !!configuredOrchestrator;
+		if (usingDefault) {
+			const which = usingConfiguredOrchestrator ? "configured orchestrator" : "hosted KiCI platform";
+			logger.info(pc.gray(`Using default trust root ${trustRoot} (${which}; pass --trust-root to override)`));
+		}
 		const bundle = JSON.parse(await readBundle(options.bundle));
 		let resolved;
 		try {
@@ -39,7 +49,8 @@ async function verifyAttestationCommand(artifact, options = {}) {
 		} catch (error) {
 			const msg = toErrorMessage(error);
 			if (usingDefault && /\b503\b/.test(msg)) {
-				logger.error(pc.red(`Error: build provenance is not enabled on the hosted KiCI platform yet (${trustRoot} returned 503). Pass --trust-root to verify against another environment (e.g. staging) or an offline { issuer, jwks } file.`));
+				const where = usingConfiguredOrchestrator ? `your configured orchestrator (${trustRoot})` : `the hosted KiCI platform (${trustRoot})`;
+				logger.error(pc.red(`Error: build provenance signing is not enabled on ${where} yet (returned 503). Pass --trust-root to verify against another environment or an offline { issuer, jwks } file.`));
 				return false;
 			}
 			throw error;

package/dist/errors/formatter.d.ts

@@ -1,5 +1,16 @@
-/** Error code string (e.g., 'E001', 'E102'). */
+/**
+ * Error code string. Thrown compile errors use `E<digits>` (e.g. 'E001', 'E102');
+ * advisory, render-only diagnostics use `W<digits>` (e.g. 'W101'). `isCompilerError`
+ * only matches the `E<digits>` family — warning codes are never thrown, only rendered.
+ */
 type ErrorCode = string;
+/** Diagnostic severity. Errors abort compilation; warnings are advisory (compile still succeeds). */
+export declare enum DiagnosticSeverity {
+    Error = "error",
+    Warning = "warning"
+}
+/** Warning code for the impure dynamic-value → init-job fallback. */
+export declare const PURITY_FALLBACK_CODE = "W101";
 /** Source location for error reporting */
 export interface SourceLocation {
     readonly file: string;
@@ -12,6 +23,7 @@ export interface CompilerError {
     readonly message: string;
     readonly location?: SourceLocation;
     readonly suggestion?: string;
+    readonly severity?: DiagnosticSeverity;
 }
 /**
  * Format error in GNU standard format: file:line:column: error [CODE]: message
@@ -25,6 +37,7 @@ export declare function formatError(error: CompilerError): string;
 export declare function compilerError(code: ErrorCode, message: string, options?: {
     location?: SourceLocation;
     suggestion?: string;
+    severity?: DiagnosticSeverity;
 }): CompilerError;
 /** Check if an error is a CompilerError (codes are E + digits, e.g. E001, E102) */
 export declare function isCompilerError(error: unknown): error is CompilerError;

package/dist/errors/formatter.js

@@ -1,6 +1,14 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import pc from "picocolors";
 //#region src/errors/formatter.ts
+/** Diagnostic severity. Errors abort compilation; warnings are advisory (compile still succeeds). */
+let DiagnosticSeverity = /* @__PURE__ */ function(DiagnosticSeverity) {
+	DiagnosticSeverity["Error"] = "error";
+	DiagnosticSeverity["Warning"] = "warning";
+	return DiagnosticSeverity;
+}({});
+/** Warning code for the impure dynamic-value → init-job fallback. */
+const PURITY_FALLBACK_CODE = "W101";
 /**
 * Format error in GNU standard format: file:line:column: error [CODE]: message
 *
@@ -11,7 +19,8 @@ import pc from "picocolors";
 function formatError(error) {
 	const parts = [];
 	if (error.location) parts.push(pc.cyan(`${error.location.file}:${error.location.line}:${error.location.column}`));
-	parts.push(pc.red("error") + pc.gray(` [${error.code}]`) + ": " + error.message);
+	const label = error.severity === "warning" ? pc.yellow("warning") : pc.red("error");
+	parts.push(label + pc.gray(` [${error.code}]`) + ": " + error.message);
 	let output = parts.join(" ");
 	if (error.suggestion) output += "\n  " + pc.dim(`Suggestion: ${error.suggestion}`);
 	return output;
@@ -22,7 +31,8 @@ function compilerError(code, message, options) {
 		code,
 		message,
 		location: options?.location,
-		suggestion: options?.suggestion
+		suggestion: options?.suggestion,
+		severity: options?.severity
 	};
 }
 /** Check if an error is a CompilerError (codes are E + digits, e.g. E001, E102) */
@@ -30,6 +40,6 @@ function isCompilerError(error) {
 	return typeof error === "object" && error !== null && "code" in error && "message" in error && typeof error.code === "string" && /^E\d+$/.test(error.code);
 }
 //#endregion
-export { compilerError, formatError, isCompilerError };
+export { DiagnosticSeverity, PURITY_FALLBACK_CODE, compilerError, formatError, isCompilerError };
 
 //# sourceMappingURL=formatter.js.map

package/dist/errors/index.d.ts

@@ -1,5 +1,6 @@
-export { formatError, compilerError, isCompilerError } from './formatter.js';
+export { formatError, compilerError, isCompilerError, DiagnosticSeverity, PURITY_FALLBACK_CODE, } from './formatter.js';
 export type { SourceLocation, CompilerError } from './formatter.js';
 export { CapabilityGapError, formatCapabilityGapError } from './capability-gap.js';
 export type { CapabilityGapInfo } from './capability-gap.js';
+export { firstStepLocation, locationForJob, locationForWorkflow } from './source-location.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/errors/index.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { compilerError, formatError, isCompilerError } from "./formatter.js";
+import { DiagnosticSeverity, PURITY_FALLBACK_CODE, compilerError, formatError, isCompilerError } from "./formatter.js";
 import { CapabilityGapError, formatCapabilityGapError } from "./capability-gap.js";
-export { CapabilityGapError, compilerError, formatCapabilityGapError, formatError, isCompilerError };
+import { firstStepLocation, locationForJob, locationForWorkflow } from "./source-location.js";
+export { CapabilityGapError, DiagnosticSeverity, PURITY_FALLBACK_CODE, compilerError, firstStepLocation, formatCapabilityGapError, formatError, isCompilerError, locationForJob, locationForWorkflow };

package/dist/errors/source-location.d.ts

@@ -0,0 +1,20 @@
+import type { Job } from '@kici-dev/sdk';
+import type { SourceLocation } from './formatter.js';
+/**
+ * First step (walking one level into parallel groups) that carries a captured
+ * `_sourceLocation`. `step()` records a precise V8 call-site; bare functions and
+ * parallel-group wrappers do not, so this returns the first real anchor found.
+ */
+export declare function firstStepLocation(job: Job): SourceLocation | undefined;
+/**
+ * Best available location for a job-scoped error: its first step's captured
+ * location when a step exists, else the workflow source file at line 1
+ * (`job()` itself captures no call-site).
+ */
+export declare function locationForJob(job: Job, workflowFile: string): SourceLocation;
+/**
+ * Location for a workflow-scoped error: `workflow()` captures no call-site, so
+ * the best anchor is the workflow's source file at line 1.
+ */
+export declare function locationForWorkflow(file: string): SourceLocation;
+//# sourceMappingURL=source-location.d.ts.map

package/dist/errors/source-location.js

@@ -0,0 +1,45 @@
+import "../rolldown-runtime-ClRpJifh.js";
+//#region src/errors/source-location.ts
+/**
+* First step (walking one level into parallel groups) that carries a captured
+* `_sourceLocation`. `step()` records a precise V8 call-site; bare functions and
+* parallel-group wrappers do not, so this returns the first real anchor found.
+*/
+function firstStepLocation(job) {
+	for (const entry of job.steps ?? []) {
+		const stepLike = entry;
+		if (stepLike._sourceLocation) return stepLike._sourceLocation;
+		const group = entry;
+		if (Array.isArray(group.steps)) {
+			const inner = group.steps.find((c) => c._sourceLocation)?._sourceLocation;
+			if (inner) return inner;
+		}
+	}
+}
+/**
+* Best available location for a job-scoped error: its first step's captured
+* location when a step exists, else the workflow source file at line 1
+* (`job()` itself captures no call-site).
+*/
+function locationForJob(job, workflowFile) {
+	return firstStepLocation(job) ?? {
+		file: workflowFile,
+		line: 1,
+		column: 1
+	};
+}
+/**
+* Location for a workflow-scoped error: `workflow()` captures no call-site, so
+* the best anchor is the workflow's source file at line 1.
+*/
+function locationForWorkflow(file) {
+	return {
+		file,
+		line: 1,
+		column: 1
+	};
+}
+//#endregion
+export { firstStepLocation, locationForJob, locationForWorkflow };
+
+//# sourceMappingURL=source-location.js.map

package/dist/execution/executor.js

@@ -8,6 +8,30 @@ import { existsSync } from "node:fs";
 import fs$1 from "node:fs/promises";
 //#region src/execution/executor.ts
 /**
+* Map a caught runtime error's stack to a `SourceLocation` in the entry file.
+* Scans for the first stack frame referencing `entryPoint` (ignoring the
+* `?t=` cache-buster and the `file://` scheme) and returns its line/column;
+* falls back to `entryPoint` at line 1 when no frame matches.
+*/
+function locateInEntry(stack, entryPoint) {
+	const fallback = {
+		file: entryPoint,
+		line: 1,
+		column: 1
+	};
+	if (!stack) return fallback;
+	const needle = entryPoint.split("?")[0];
+	for (const raw of stack.split("\n")) {
+		const m = raw.match(/(.+?):(\d+):(\d+)\)?$/);
+		if (m && m[1].includes(needle)) return {
+			file: entryPoint,
+			line: parseInt(m[2], 10),
+			column: parseInt(m[3], 10)
+		};
+	}
+	return fallback;
+}
+/**
 * Load a TypeScript workflow/config module by direct dynamic import.
 *
 * Relies on the `@kici-dev/core/ts-loader-hook` ESM loader hook, registered
@@ -34,11 +58,7 @@ async function loadModule(entryPoint, errorContext) {
 	} catch (err) {
 		const message = err.message ?? "Failed to load module";
 		throw compilerError("E003", `Failed to load ${errorContext.fileLabel} module: ${message}`, {
-			location: {
-				file: errorContext.filePath,
-				line: 1,
-				column: 1
-			},
+			location: locateInEntry(err.stack, errorContext.filePath),
 			suggestion: `Check for TypeScript or runtime errors in your ${errorContext.fileLabel}. Make sure you invoke the workflow via the kici CLI (the bin shim registers the oxc-transform loader hook that handles TS files).`
 		});
 	}

package/dist/fixtures/defaults/index.js

@@ -86,7 +86,8 @@ const FIXTURES = {
 * @throws Error if event is unknown
 */
 function getDefaultFixture(event) {
-	const fixture = FIXTURES[event.toLowerCase().trim()];
+	const normalized = event.toLowerCase().trim();
+	const fixture = FIXTURES[normalized];
 	if (!fixture) {
 		const available = Object.keys(FIXTURES).filter((k, i, arr) => arr.indexOf(k) === i).join(", ");
 		throw new Error(`Unknown event type: ${event}\nAvailable events: ${available}`);

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

@@ -19,7 +19,7 @@ Per-orchestrator settings loaded from a YAML file. These are instance-specific a
 ```typescript
 interface LocalConfig {
   database: { url: string };
-  instance?: { id?: string; mode?: 'platform' | 'hybrid' | 'independent' };
+  instance?: { id?: string; mode?: 'platform' | 'hybrid' | 'independent' | 'observed' };
   server?: { port?: number; basePath?: string; logLevel?: string };
   scaler?: { configPath?: string; configDir?: string };
 }
@@ -56,7 +56,7 @@ The merged result type used throughout the codebase. Combines `LocalConfig` + `S
 ```typescript
 interface AppConfig {
   instanceId: string; // From local config or auto-generated
-  mode: 'platform' | 'hybrid' | 'independent';
+  mode: 'platform' | 'hybrid' | 'independent' | 'observed';
   databaseUrl: string; // Flattened from database.url
   port: number; // Flattened from server.port
   basePath: string;
@@ -376,7 +376,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 29. The orchestrator rejects any fetched lock whose `schemaVersion` does not exactly match the engine version it was built against, so a stale lock must be recompiled with `kici compile` and pushed again after any SDK upgrade that bumps the schema.
+> **Lock file schema version:** The orchestrator accepts a compatibility window of lock schema versions rather than an exact match. A lock is accepted when its `schemaVersion` is at or above the orchestrator's oldest supported version (additive bumps add fields older readers ignore) and the orchestrator's own schema is at or above the lock's `minReaderVersion` (the newest breaking version at compile time). A lock below the floor must be recompiled with `kici compile` and pushed; a lock requiring a newer reader means the orchestrator must be upgraded. Both out-of-window cases are rejected with an actionable error rather than a silent mis-route. See [lock file and drift](https://docs.kici.dev/user/lock-file-and-drift/#schema-compatibility-window).
 
 ## Webhook delivery flow
 
@@ -582,7 +582,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 29.
+- **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 31.
 - **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
@@ -670,7 +670,7 @@ Agents receive pre-signed S3 GET URLs (15-minute expiry) directly in `job.dispat
 
 The source/dep cache above is internal: the orchestrator owns its keys and decides when to hit or build. The **user-facing cache** is driven by the workflow author — the declarative `cache: { key, paths, restoreKeys? }` on a job/step, or the imperative `ctx.cache.restore()` / `ctx.cache.save()` API (see [SDK caching reference](https://docs.kici.dev/user/sdk/caching/)). It reuses the same object-storage backend and the same direct-to-storage presigned-URL transport, but the agent — not the orchestrator — initiates each restore and save over WebSocket.
 
-The agent's cache module archives `paths` into a gzipped tarball (computing a SHA-256 over the bytes) and streams downloads back through a checksum-verified extract pipeline. The orchestrator's `UserCache` owns the `cache/<orgId>/<repoId>/<scope>/<key>` namespacing, the immutable first-save check, the `restoreKeys` prefix scan, the two-phase atomic save, and per-org quota/TTL eviction.
+The agent's cache module archives `paths` into a gzipped tarball (computing a SHA-256 over the bytes) and streams downloads back through a checksum-verified extract pipeline. The orchestrator's `UserCache` owns the `cache/<orgId>/<repoId>/<scope>/<key>-<discriminator>` namespacing (the discriminator is a hash of the exact cache key, so two keys differing only by case stay two objects on a case-insensitive store), the immutable first-save check, the `restoreKeys` prefix scan, the two-phase atomic save, and per-org quota/TTL eviction.
 
 ### Restore flow
 
@@ -951,7 +951,7 @@ POST /webhook/:orgId/generic/:sourceId
 
 ## Database topology
 
-The orchestrator owns its own PostgreSQL database, with the authoritative `execution_runs`, `execution_jobs`, `execution_steps`, `dispatch_queue`, `dedup_cache`, `workflow_registrations`, `environments` / `scoped_secrets` / `environment_bindings`, `agent_tokens`, `cluster_meta`, and related tables. Each orchestrator deployment uses its own `KICI_DATABASE_URL`; database users are scoped per service.
+The orchestrator owns its own PostgreSQL database, with the authoritative `execution_runs`, `execution_jobs`, `execution_steps`, `dispatch_queue`, `dedup_cache`, `workflow_registrations`, `contexts` / `scoped_secrets` / `context_bindings`, `agent_tokens`, `cluster_meta`, and related tables. Each orchestrator deployment uses its own `KICI_DATABASE_URL`; database users are scoped per service.
 
 ## Execution reporting flow
 
@@ -1135,7 +1135,7 @@ Output chaining allows steps to consume outputs from preceding steps (within a j
 When workflow code runs at definition time (`step()`, `job()` calls):
 
 - `step()` creates an `OutputProxy<T>` via `createStepOutputProxy(stepName)` and attaches it as `.result`
-- `job()` creates an `OutputProxy<any>` via `createJobOutputProxy(jobName)` and attaches it as `.result`
+- `job()` creates an `OutputProxy<TOutputs>` (the job's inferred output shape — nested by step name for a multi-step job, flat for the `run:` shorthand) via `createJobOutputProxy(jobName)` and attaches it as `.result`, so cross-job reads type-check
 - The proxy is an ES6 `Proxy` object that defers all property access to a module-global `OutputsMap`
 - No outputs exist yet -- accessing `.result.field` before execution throws "has not produced outputs yet"
 
@@ -1219,7 +1219,7 @@ The Platform tier exposes a `/ws/browser` WebSocket endpoint for dashboard clien
 - [Architecture overview](https://docs.kici.dev/architecture/overview/) -- three-tier model and component responsibilities
 - [Protocol messages](https://docs.kici.dev/architecture/protocol-messages/) -- WebSocket message schemas
 - [Event system internals](https://docs.kici.dev/architecture/webhooks/event-system/) -- event router, registration model, cron scheduler
-- [State machine](https://docs.kici.dev/architecture/execution/state-machine/) -- job execution state transitions
+- [Execution lifecycle](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and terminal states
 - [Webhook delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) -- detailed webhook processing pipeline
 - [Operator: dependency caching](https://docs.kici.dev/operator/dependency-caching/) -- configuration guide
 - [Operator: monitoring & tracing](https://docs.kici.dev/operator/observability/monitoring/) -- trace fields and Loki queries
@@ -1248,6 +1248,7 @@ flowchart LR
     AGENT_B["Agent\n(arm64)"]
 
     GH -- "HTTP\n(webhooks)" --> PLATFORM
+    GH -. "HTTP direct webhook\n(hybrid / observed / independent)" .-> ORCH_A
     PLATFORM <-- "WebSocket\n(relay + telemetry)" --> ORCH_A
     PLATFORM <-- "WebSocket\n(relay + telemetry)" --> ORCH_B
     ORCH_A <-- "WebSocket P2P\n(reroute + progress\n+ Raft)" --> ORCH_B
@@ -1260,7 +1261,19 @@ flowchart LR
 
 **Why three tiers?** Trust boundaries. The Platform relay never sees customer code -- it only verifies webhook signatures and forwards payloads. The orchestrator matches triggers against the lock file without cloning repositories. Only the agent, running on customer infrastructure, clones code and executes steps.
 
-This model also supports an independent deployment without the hosted Platform: the orchestrator and agent run on customer infrastructure, with the orchestrator receiving webhooks directly from GitHub instead of through the Platform relay.
+This model also supports pointing webhooks **directly** at the orchestrator,
+bypassing the Platform relay. In **hybrid** mode the orchestrator keeps its
+Platform connection for the dashboard and telemetry while GitHub delivers events
+straight to the orchestrator's ingress — so a Platform outage never drops a build
+trigger. **Observed** mode drops the relay leg entirely: webhooks reach only the
+orchestrator's own ingress (no payload ever transits KiCI) while the Platform
+connection stays up for the hosted dashboard, and the orchestrator's sources
+register as observe-only — recorded and dashboard-visible, but excluded from
+every relay-candidate lookup. In a fully **independent** deployment the
+orchestrator and agent run on customer infrastructure with no Platform at all,
+receiving webhooks directly. For
+exactly which capabilities the hosted Platform provides in each case, see
+[What requires the hosted Platform](https://docs.kici.dev/operator/orchestrator/platform-capabilities/).
 
 ## Component responsibilities
 
@@ -1275,7 +1288,7 @@ The Platform never processes, stores, or executes customer code, and never sees
 The orchestrator is the execution brain. It decides what to run and dispatches work to agents.
 
 - **Trigger matching** -- Evaluates lock file triggers against webhook payloads to determine which jobs to run. Uses branch, path, and event matching via picomatch.
-- **Lock file caching** -- Fetches `kici.lock.json` from the configured provider's API (GitHub, generic webhook, universal-git, or internal). An LRU cache wraps the per-provider fetcher, keyed by `{provider}:{repo}:{ref}` so cross-provider fallback resolutions stay isolated.
+- **Lock file caching** -- Fetches `kici.lock.json` via the configured source's fetcher (GitHub API, universal-git clone for generic webhook sources backed by a git URL, or the local filesystem for `file://` sources). An LRU cache wraps the per-provider fetcher, keyed by `{provider}:{repo}:{ref}` so cross-provider fallback resolutions stay isolated.
 - **Agent registry** -- Tracks connected agents with label-based routing for job dispatch.
 - **Job queue** -- PostgreSQL-backed FIFO queue for reliable dispatch.
 - **Webhook pipeline** -- Dedup, event mapping, lock file fetch, trigger matching, and job dispatch in a single pipeline.
@@ -1290,12 +1303,13 @@ The orchestrator is the execution brain. It decides what to run and dispatches w
 The agent is the execution worker. It runs on customer infrastructure and has full access to customer code.
 
 - **Repository cloning** -- Clones the target repo with token-based auth (token in HTTP headers, not URLs, to prevent leakage).
-- **Step execution** -- Runs steps sequentially with full `StepContext` (zx shell, logger, environment, workflow/job metadata).
-- **Docker support** -- Container-based step execution via `docker exec` for isolated environments.
+- **Step execution** -- Runs steps in declaration order with full `StepContext` (zx shell, logger, environment, workflow/job metadata). Steps wrapped in a `parallel()` group run concurrently behind a `maxParallel` window, and each child reports as its own observable step with its own logs, status, timing, and retry.
+- **Execution sandboxes** -- Runs the workflow runner as a separate child process with a sanitized environment, in one of three sandboxes: bare metal (process fork, with optional bubblewrap namespace isolation), a container runtime (the whole job lifecycle runs inside a disposable container), or inside a Firecracker microVM. Agent-internal credentials never reach customer workflow code.
 - **Log streaming** -- Chunked log streaming back to the orchestrator with configurable size limits.
+- **Dependency caching** -- Packs, uploads, and restores installed workflow dependencies so repeat runs skip the install step.
 - **Graceful shutdown** -- SIGTERM with 10s grace period, SIGUSR1 for drain mode.
 
-> Source: `packages/agent/src/execution/job-runner.ts` (job lifecycle), `packages/agent/src/server.ts` (entry point)
+> Source: `packages/agent/src/execution/job-runner.ts` (job lifecycle), `packages/agent/src/execution/sandbox/` (execution sandboxes and the parallel step scheduler), `packages/agent/src/server.ts` (entry point)
 
 ## Supporting packages
 
@@ -1306,14 +1320,22 @@ Shared business logic used by all three tiers. Single source of truth for cross-
 - 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)
+- Dispatch inputs (input descriptors, extraction from the trigger event, and coercion to typed values)
+- Matrix expansion and fanout (combination expansion with include/exclude, job-name suffix formatting, and materialization of one matrix or multi-host job into N dispatchable children)
+- Execution status vocabulary (run/job/step status enums + terminal-state sets; lifecycle owned by the orchestrator's execution tracker)
+- Check mode (the idempotent run modes `apply` / `check` / `check-fail-on-drift` and the per-step outcome vocabulary)
 - Webhook signature verification (HMAC-SHA256, timing-safe)
 - WebSocket close codes (unified across all tiers)
 - WebSocket rate limiting (WsRateLimiter)
 - Environment allowlist (safe env var filtering)
 - Secrets management (secret context resolution)
-- Environment model (scoped secrets, env merge, protection gates)
+- Context model (scoped secrets, ordered context merge, protection gates)
+- Approval requirements (normalized approver clauses shared by the orchestrator gate, the resolver, the held-run store, and the agent step round-trip)
+- Build provenance (in-toto statement schema, DSSE envelope, attestation bundle, verification)
+- Artifact name contract (the shared filesystem/URL-safe name schema the orchestrator, agent, and SDK all validate against)
+- Developer MCP tool schemas (argument schemas for the AI-agent tool surface)
 - Label utilities (platform label derivation, runsOn normalization, `kici:*` set-only reserved namespace, role labels)
+- Host inventory (the canonical queryable host-roster schema shared by the orchestrator's roster store, the agent-facing inventory API, and the SDK's `ctx.kici.inventory`)
 - Audit policy and retention (per-action access-log sampling, warm-retention windows for cold-store eligibility, federated activity row schema)
 - Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`)
 - Registration trigger type enum (registerable trigger discriminator)
@@ -1331,7 +1353,9 @@ User-facing SDK for defining workflows in TypeScript. Provides factory functions
 
 CLI tooling for workflow authors. Compiles `.kici/workflows/*.ts` to `.kici/kici.lock.json`, provides watch mode, local test execution, project initialization, and pre-commit hook integration.
 
-> Source: `packages/compiler/src/`
+It also runs the **local dev plane** -- an on-demand, fully local execution stack (embedded PostgreSQL, an orchestrator process, and a bare-metal-scaled agent) that lets an author run a workflow end-to-end on their own machine. That is why the compiler depends on `@kici-dev/orchestrator` and `@kici-dev/agent`: it resolves and spawns their built entry points rather than reimplementing them. See [Local dev plane](https://docs.kici.dev/operator/orchestrator/local-dev-plane/).
+
+> Source: `packages/compiler/src/` (`local-plane/` for the local dev plane)
 
 ### `@kici-dev/core`
 
@@ -1357,7 +1381,7 @@ Unscoped wrapper package that provides the `kici` CLI command. Re-exports `@kici
 
 ### `kici-admin` (admin CLI wrapper)
 
-Unscoped wrapper package that provides the `kici-admin` CLI command. Re-exports `@kici-dev/orchestrator/cli` for orchestrator administration tasks.
+Unscoped wrapper package that ships two binaries: `kici-admin`, which re-exports `@kici-dev/orchestrator/cli` for orchestrator administration tasks, and `kici-agent`, which re-exports `@kici-dev/agent/server` to run an agent. It therefore depends on both `@kici-dev/orchestrator` and `@kici-dev/agent` (the `KICIADMIN → AGENT` edge in the graph below).
 
 > Source: `packages/kici-admin/`
 
@@ -1380,10 +1404,13 @@ flowchart TD
     DASH --> ENGINE
     DASH -.->|dev| PLATFORM
     SHARED --> CORE
+    SHARED --> ENGINE
     SDK --> ENGINE
     SDK --> CORE
     COMPILER --> ENGINE
     COMPILER --> CORE
+    COMPILER --> ORCH
+    COMPILER --> AGENT
     COMPILER -.->|peer| SDK
     PLATFORM --> ENGINE
     PLATFORM --> SHARED
@@ -1402,10 +1429,12 @@ flowchart TD
     KICIADMIN --> AGENT
 ```
 
-**Leaf packages** (no `@kici` dependencies): `@kici-dev/core` and `@kici-dev/engine`. These can be tested and built independently. `@kici-dev/shared` builds on `@kici-dev/core` and re-exports it. The dashboard depends on `@kici-dev/engine` for shared types (protocol schemas, state machine) and imports the Platform's API type definitions as a dev dependency, but communicates with backend services at runtime via HTTP/WebSocket, not at compile time.
+**Leaf packages** (no `@kici` dependencies): `@kici-dev/core` and `@kici-dev/engine`. These can be tested and built independently. `@kici-dev/shared` builds on `@kici-dev/core` (which it re-exports) and on `@kici-dev/engine` for shared vocabularies. The dashboard depends on `@kici-dev/engine` for shared types (protocol schemas, execution status enums) and imports the Platform's API type definitions as a dev dependency, but communicates with backend services at runtime via HTTP/WebSocket, not at compile time.
 
 **Runtime tiers** (Platform, orchestrator, agent) all depend on `@kici-dev/engine` for shared business logic and `@kici-dev/shared` for utilities. Only the agent depends on `@kici-dev/sdk` (it loads workflow definitions at runtime).
 
+The `COMPILER → ORCH` and `COMPILER → AGENT` edges exist solely for the local dev plane: the compiler spawns a local orchestrator and agent so an author can execute a workflow end-to-end without any deployed infrastructure. Nothing in the compile path itself reaches into either tier.
+
 ## Connection overview
 
 KiCI uses three WebSocket layers for real-time communication.
@@ -1433,7 +1462,7 @@ KiCI uses application-level tenant isolation. The Platform dashboard API accepts
 ## See also
 
 - [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) -- P2P clustering, Raft consensus, job rerouting
-- [State Machine](https://docs.kici.dev/architecture/execution/state-machine/) -- execution lifecycle tracking across all tiers
+- [Execution lifecycle](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and the tracker that owns lifecycle state
 - [Protocol Messages](https://docs.kici.dev/architecture/protocol-messages/) -- WebSocket message schemas for all three layers
 - [Webhook Delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) -- end-to-end trace of a webhook through all three tiers