@kici-dev/compiler 0.1.21 → 0.1.23

package/dist/llm-context/llms.txt

@@ -4,6 +4,18 @@
 
 The full markdown bundle of every page indexed here is available at https://docs.kici.dev/llms-full.txt.
 
+## Bundles
+
+Each bundle below is a self-contained markdown file for one authoring task. Fetch only the one your task needs instead of the full bundle:
+
+- [getting-started](https://docs.kici.dev/llms-getting-started.txt) (25 KB) — Install the SDK, write your first workflow, compile and test locally
+- [patterns](https://docs.kici.dev/llms-patterns.txt) (49 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
+- [sdk](https://docs.kici.dev/llms-sdk.txt) (185 KB) — Authoring API: workflow/job/step factories, triggers, rules, matrix, runtime, caching
+- [cli](https://docs.kici.dev/llms-cli.txt) (117 KB) — Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift
+- [features](https://docs.kici.dev/llms-features.txt) (116 KB) — Workflow features: concurrency, environments, secrets, approvals, provenance, events
+- [providers](https://docs.kici.dev/llms-providers.txt) (36 KB) — Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://
+- [architecture](https://docs.kici.dev/llms-architecture.txt) (88 KB) — How the runtime works: three-tier relay model, data flows, configuration
+
 ## Getting started
 
 - [User guide](https://docs.kici.dev/user/): Writing and testing CI/CD workflows in TypeScript
@@ -14,6 +26,7 @@ The full markdown bundle of every page indexed here is available at https://docs
 
 - [Basic workflow patterns](https://docs.kici.dev/user/patterns/basic/): Basic CI, PR-only / push-only filters, multiple triggers, manual-only workflows
 - [Conditionals & matrix patterns](https://docs.kici.dev/user/patterns/conditionals-matrix/): Conditional execution with rules, matrix builds (static + dynamic), dynamic job generation
+- [Host restart & wait-for-alive](https://docs.kici.dev/user/patterns/host-restart/): Reboot the host a workflow runs on and continue after it comes back
 - [Integration patterns](https://docs.kici.dev/user/patterns/integrations/): Workflow chaining, generic webhooks, Stripe, self-hosted git forges, plain GitHub repos
 - [Pattern reference](https://docs.kici.dev/user/patterns/reference/): Step context, examples repository, GitHub check run output — cross-cutting reference for all patterns
 - [Scheduling & event patterns](https://docs.kici.dev/user/patterns/scheduling-and-events/): Nightly cron, workflow-complete-triggered deploys, custom event chaining
@@ -44,7 +57,7 @@ The full markdown bundle of every page indexed here is available at https://docs
 ## Workflow features
 
 - [Account and sign-in](https://docs.kici.dev/user/account-and-login/): How your KiCI account relates to sign-in methods, and how to change the way you sign in.
-- [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with requireApproval
+- [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with approval
 - [Concurrency groups](https://docs.kici.dev/user/concurrency/): Control parallel execution with auto-cancel and queue modes
 - [Dashboard](https://docs.kici.dev/user/dashboard/): Web UI for monitoring workflow runs, managing sources, secrets, and organization settings.
 - [Dynamic values](https://docs.kici.dev/user/dynamic-values/)
@@ -65,5 +78,6 @@ The full markdown bundle of every page indexed here is available at https://docs
 
 ## Architecture overview
 
+- [Configuration architecture](https://docs.kici.dev/architecture/configuration/): Config resolution chain, DB schema, encryption, hot-reload, cluster sync
 - [Data flows](https://docs.kici.dev/architecture/data-flows/): End-to-end data flows through the KiCI three-tier architecture
 - [Architecture overview](https://docs.kici.dev/architecture/overview/): Three-tier relay model, package structure, and component responsibilities

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 { CheckMode, CheckStepOutcome, matchAllWorkflows } from "@kici-dev/engine";
+import { CheckMode, CheckStepOutcome, coerceDispatchInputs, matchAllWorkflows, parseInputPairs } from "@kici-dev/engine";
 import os from "node:os";
 //#region src/local-executor/index.ts
 /**
@@ -136,8 +136,37 @@ async function runOneMatchedWorkflow(workflow, ctx) {
 * The actual DAG-execution body for one workflow. Split out so
 * {@link runOneMatchedWorkflow} can wrap it in a lock acquire/release.
 */
+/**
+* Resolve the dispatch-input descriptor declared on a workflow's `dispatch()`
+* trigger(s) from the in-memory trigger objects, merged across triggers.
+* Returns undefined when none declared.
+*/
+function dispatchInputsDescriptorForWorkflow(workflow) {
+	const merged = {};
+	let found = false;
+	for (const trigger of transformTriggers(workflow.on)) if (trigger._type === "dispatch" && trigger.inputs) {
+		Object.assign(merged, trigger.inputs);
+		found = true;
+	}
+	return found ? merged : void 0;
+}
+/**
+* Coerce + default the operator's `--input` pairs against the workflow's
+* dispatch descriptor for a local run. The local executor is authoritative for
+* `run local` (no orchestrator), so defaults are applied here exactly once.
+* Returns the resolved values, or throws when input is invalid.
+*/
+function resolveLocalDispatchInputs(workflow, options) {
+	const descriptor = dispatchInputsDescriptorForWorkflow(workflow);
+	const raw = parseInputPairs(options.inputs ?? []);
+	if (!descriptor) return raw;
+	const r = coerceDispatchInputs(raw, descriptor);
+	if ("error" in r) throw r.error;
+	return r.values;
+}
 async function runWorkflowBody(workflow, ctx, options, secrets, kiciDir, concurrency, failFast) {
 	const { event } = ctx;
+	const dispatchInputs = resolveLocalDispatchInputs(workflow, options);
 	const resolvedJobs = await resolveJobs(workflow, event);
 	let dagNodes = resolvedJobs.map((r) => ({
 		name: r.expandedName,
@@ -170,7 +199,8 @@ async function runWorkflowBody(workflow, ctx, options, secrets, kiciDir, concurr
 				execDir: ctx.execDir,
 				jobOutputsMap,
 				signal,
-				checkMode: options.checkMode
+				checkMode: options.checkMode,
+				dispatchInputs
 			});
 		},
 		isSuccess: (result) => result.status === "success" || result.status === "skipped"
@@ -223,7 +253,8 @@ async function executeLocal(options) {
 	if (!await compileCommand({
 		kiciDir,
 		check: false,
-		verbose: options.debug ?? false
+		verbose: options.debug ?? false,
+		quiet: Boolean(options.json || options.quiet)
 	})) {
 		process.exitCode = 2;
 		return false;
@@ -268,6 +299,12 @@ async function executeLocal(options) {
 			return true;
 		}
 	}
+	for (const workflow of matchedWorkflows) try {
+		resolveLocalDispatchInputs(workflow, options);
+	} catch (err) {
+		logger.error(pc.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+		process.exit(2);
+	}
 	const isQuiet = Boolean(options.quiet || options.json);
 	const repoRoot = path.dirname(kiciDir);
 	let materialized = null;

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

@@ -27,6 +27,8 @@ export interface JobExecutionContext {
     signal: AbortSignal;
     /** Run mode for idempotent steps. Defaults to `apply` when unset. */
     checkMode?: CheckMode;
+    /** Resolved (coerced + defaulted) workflow-dispatch inputs for `ctx.dispatchInputs`. */
+    dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>;
 }
 /**
  * Resolve all jobs in a workflow, expanding matrix jobs and evaluating dynamic jobs.

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

@@ -8,6 +8,7 @@ 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 { computeBackoffDelay } from "@kici-dev/core";
 import { CheckMode, CheckStepOutcome, formatMatrixSuffix } from "@kici-dev/engine";
 import { runIdempotentStep } from "@kici-dev/core/idempotency";
 //#region src/local-executor/job-runner.ts
@@ -91,6 +92,33 @@ async function runLocalStepWithCheckMode(step, ctx, checkMode) {
 	};
 }
 /**
+* Run a local step through its retry policy. An attempt is one full
+* `runLocalStepWithCheckMode` call (which throws on failure). A thrown attempt
+* is retried while attempts remain AND `retryIf(err)` is true; backoff sleeps
+* between attempts. Mirrors the agent step loop so `kici run local` retries
+* identically to a remote run.
+*/
+async function runLocalStepWithRetry(step, ctx, checkMode, log) {
+	const retry = step.retry;
+	const max = retry?.maxAttempts ?? 1;
+	let lastErr;
+	for (let n = 1; n <= max; n++) try {
+		return await runLocalStepWithCheckMode(step, ctx, checkMode);
+	} catch (err) {
+		lastErr = err;
+		if (!(n < max && (retry?.retryIf?.(err) ?? true))) break;
+		const delay = computeBackoffDelay(n, {
+			maxAttempts: max,
+			delayMs: retry.delayMs,
+			backoff: retry.backoff,
+			maxDelayMs: retry.maxDelayMs
+		});
+		log(`Step '${step.name}' attempt ${n}/${max} failed: ${err instanceof Error ? err.message : String(err)}; retrying in ${delay}ms`);
+		await new Promise((r) => setTimeout(r, delay));
+	}
+	throw lastErr;
+}
+/**
 * 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
@@ -145,7 +173,12 @@ async function resolveJobs(workflow, event) {
 					query: () => Promise.resolve([]),
 					get: () => Promise.resolve(null)
 				},
-				oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available during local execution")) }
+				oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available during local execution")) },
+				host: { requestReboot: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.host.requestReboot() is not available during local execution")) },
+				bootstrap: {
+					ensureInitRunner: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.ensureInitRunner() is not available during local execution")),
+					preBootSend: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.preBootSend() is not available during local execution"))
+				}
 			}
 		});
 		for (const genJob of generatedJobs) {
@@ -256,7 +289,7 @@ async function executeResolvedJobInner(resolvedJob, context, startTime) {
 	const sdkSetters = await resolveSdkSetters(context.kiciDir);
 	let ruleResults;
 	if (job.rules && job.rules.length > 0) {
-		const ruleContext = createRuleContext(context.event, context.event.changedFiles);
+		const ruleContext = createRuleContext(context.event, context.event.changedFiles, context.dispatchInputs ?? {});
 		const ruleEval = await evaluateRulesWithFormatting(job.rules, ruleContext, expandedName);
 		ruleResults = ruleEval.results;
 		if (!ruleEval.allPassed) return {
@@ -281,7 +314,7 @@ async function executeResolvedJobInner(resolvedJob, context, startTime) {
 	const stepCtx = createStepContext({ name: context.workflowName }, {
 		name: expandedName,
 		runsOn: localRunsOnString(job.runsOn)
-	}, repoRoot, void 0, hasMatrix ? matrixValues : void 0, context.secrets, void 0, context.event.payload, context.event.provider);
+	}, repoRoot, void 0, hasMatrix ? matrixValues : void 0, context.secrets, void 0, context.event.payload, context.event.provider, context.dispatchInputs ?? {});
 	const stepResults = [];
 	let stepCounter = 0;
 	for (const stepOrFn of job.steps) {
@@ -312,7 +345,7 @@ async function executeResolvedJobInner(resolvedJob, context, startTime) {
 		const stepStart = Date.now();
 		try {
 			const checkMode = context.checkMode ?? CheckMode.enum.apply;
-			const phase = await runLocalStepWithCheckMode(normalizedStep, stepCtx, checkMode);
+			const phase = await runLocalStepWithRetry(normalizedStep, stepCtx, checkMode, (line) => formatter.logJobLine(expandedName, line));
 			const outputs = phase.outputs;
 			const stepDuration = Date.now() - stepStart;
 			formatter.logStepComplete(expandedName, normalizedStep.name, stepDuration);

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

@@ -27,6 +27,8 @@ export interface RunLocalOptions {
     container?: boolean;
     /** --env KEY=VALUE overrides (repeatable) */
     env?: string[];
+    /** --input KEY=VALUE typed workflow-dispatch inputs (repeatable) */
+    inputs?: string[];
     /** --quiet: minimal output */
     quiet?: boolean;
     /** --json: JSON output format */

package/dist/lockfile/generator.js

@@ -5,11 +5,11 @@ import { resolveHashFiles } from "./hash-files.js";
 import { analyzePurity } from "./purity-analyzer.js";
 import path from "node:path";
 import { readFileSync } from "node:fs";
-import { getDynamicJobGroup, getDynamicJobNeeds, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isStaticArray, isStaticObject, normalizeCacheSpecs, normalizeRequireApproval } from "@kici-dev/sdk";
+import { getDynamicJobGroup, getDynamicJobNeeds, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isStaticArray, isStaticObject, normalizeApproval, normalizeCacheSpecs } from "@kici-dev/sdk";
 import { sha256 } from "@kici-dev/core";
 import { PackageManager, detectPackageManagerSync, detectYarnFlavorSync } from "@kici-dev/core/package-manager";
-import { validateResourceRequest } from "@kici-dev/engine";
-import { normalizeRunsOnAllToMatchers, normalizeRunsOnToMatchers } from "@kici-dev/engine/labels/compile";
+import { extractInputsDescriptorMap, resolveWhenToRunOn, validateResourceRequest } from "@kici-dev/engine";
+import { normalizeRunsOnAllToMatchers, normalizeRunsOnToMatchers, runsOnPickFromInput } from "@kici-dev/engine/labels/compile";
 import { execSync } from "node:child_process";
 //#region src/lockfile/generator.ts
 /**
@@ -158,7 +158,7 @@ function transformWorkflow(workflow, sourceFile, exportRef, bundleSource, gitRoo
 			...workflow.concurrency.max !== void 0 && { max: workflow.concurrency.max }
 		} },
 		...workflow.timeout !== void 0 && { timeout: workflow.timeout },
-		...workflow.requireApproval !== void 0 && { approval: toLockApproval(workflow.requireApproval) }
+		...workflow.approval !== void 0 && { approval: (assertNonStepApprovalScope(workflow.approval, "workflow"), toLockApproval(workflow.approval)) }
 	};
 }
 /**
@@ -234,7 +234,8 @@ function toLockDispatch(t) {
 	return {
 		_type: "dispatch",
 		types: t.types,
-		...reposField(t)
+		...reposField(t),
+		...t.inputs && { inputs: extractInputsDescriptorMap(t.inputs) }
 	};
 }
 function toLockCreate(t) {
@@ -458,7 +459,8 @@ function normalizeRunsOnForLock(runsOn, jobName) {
 	const { include, exclude } = normalizeRunsOnToMatchers(runsOn, `job '${jobName}' runsOn`);
 	return {
 		runsOn: include,
-		...exclude.length > 0 ? { excludeLabels: exclude } : {}
+		...exclude.length > 0 ? { excludeLabels: exclude } : {},
+		runsOnPick: runsOnPickFromInput(runsOn)
 	};
 }
 /**
@@ -540,6 +542,7 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.runsOn !== void 0 ? normalizeRunsOnForLock(job.runsOn, job.name) : {},
 		...job.runsOnAll !== void 0 && { runsOnAll: normalizeRunsOnAllToMatchers(job.runsOnAll, `job '${job.name}' runsOnAll`) },
 		...job.onUnreachable !== void 0 && { onUnreachable: job.onUnreachable },
+		...job.includeUninitialized !== void 0 && { includeUninitialized: job.includeUninitialized },
 		...job.maxParallel !== void 0 && { maxParallel: job.maxParallel },
 		...job.failFast !== void 0 && { failFast: job.failFast },
 		...resolveNeedsForLock(job.needs, uuidToName),
@@ -565,12 +568,13 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.timeout !== void 0 && { timeout: job.timeout },
 		...job.resources !== void 0 && { resources: job.resources },
 		...job.init !== void 0 && { init: job.init },
-		...job.requireApproval !== void 0 && { approval: toLockApproval(job.requireApproval) }
+		...job.approval !== void 0 && { approval: (assertNonStepApprovalScope(job.approval, "job"), toLockApproval(job.approval)) }
 	};
 }
 /**
 * Resolve needs to lock file format.
-* Handles strings, Job objects, DynamicGroupRef, and object forms with ifFailed policy.
+* Handles strings, Job objects, DynamicGroupRef, and object forms with a `when`
+* run condition (normalized to a `runOn` status-set via the engine helper).
 * Uses the UUID-to-renamed-name mapping so that references to id-less jobs
 * resolve to their lock file names (job-N) instead of the original UUIDs.
 */
@@ -582,26 +586,26 @@ function resolveNeedsForLock(needs, uuidToName) {
 	else if (isDynamicGroupRef(need)) {
 		resolvedNeeds.push({
 			group: need.group,
-			ifFailed: need.ifFailed ?? "skip"
+			runOn: resolveWhenToRunOn(need.when)
 		});
 		groups.push(need.group);
+	} else if ("_tag" in need && need._tag === "Job") {
+		const name = need.name;
+		resolvedNeeds.push(uuidToName?.get(name) ?? name);
 	} else if ("group" in need && typeof need.group === "string") {
 		const g = need;
 		resolvedNeeds.push({
 			group: g.group,
-			ifFailed: g.ifFailed ?? "skip"
+			runOn: resolveWhenToRunOn(g.when)
 		});
 		groups.push(g.group);
-	} else if ("ifFailed" in need && "name" in need) {
+	} else {
 		const n = need;
 		const name = uuidToName?.get(n.name) ?? n.name;
 		resolvedNeeds.push({
 			name,
-			ifFailed: n.ifFailed
+			runOn: resolveWhenToRunOn(n.when)
 		});
-	} else {
-		const name = need.name;
-		resolvedNeeds.push(uuidToName?.get(name) ?? name);
 	}
 	return {
 		needs: resolvedNeeds,
@@ -613,15 +617,31 @@ function resolveNeedsForLock(needs, uuidToName) {
 * Assigns counter-based IDs to unnamed steps (bare functions and id-less steps).
 * Counter only increments for unnamed entries; named steps keep their names.
 */
-/** Map an SDK `requireApproval` to the normalized lock `approval` block. */
-function toLockApproval(r) {
-	const n = normalizeRequireApproval(r);
+/** Map an SDK `approval` to the normalized lock `approval` block. */
+function toLockApproval(c) {
+	const n = normalizeApproval(c);
 	return {
 		clauses: n.clauses,
 		...n.reason !== void 0 && { reason: n.reason },
-		...n.timeoutSeconds !== void 0 && { timeoutSeconds: n.timeoutSeconds }
+		...n.timeoutSeconds !== void 0 && { timeoutSeconds: n.timeoutSeconds },
+		when: n.when
 	};
 }
+/**
+* Validate an approval config at job/workflow scope: `when: 'drift'` is a
+* step-scope-only gate (it fires between a step's check and run), so it is a
+* compile error anywhere else.
+*/
+function assertNonStepApprovalScope(c, scope) {
+	if (normalizeApproval(c).when === "drift") throw new Error(`approval.when "drift" is only valid on steps (found at ${scope} scope)`);
+}
+/**
+* Validate a step's approval config: `when: 'drift'` fires between the step's
+* check and run, so it requires a `check` facet. A compile error otherwise.
+*/
+function assertStepApprovalCheckFacet(step) {
+	if (step.approval !== void 0 && normalizeApproval(step.approval).when === "drift" && step.check === void 0) throw new Error(`step '${step.name || "(unnamed)"}': approval.when "drift" requires a check facet`);
+}
 function transformSteps(steps, gitRoot) {
 	let stepCounter = 0;
 	return steps.map((stepOrFn) => {
@@ -638,6 +658,12 @@ function transformSteps(steps, gitRoot) {
 			hasOutputs: !!step.outputs && Object.keys(step.outputs).length > 0,
 			...step.continueOnError !== void 0 && { continueOnError: step.continueOnError },
 			...step.timeout !== void 0 && { timeout: step.timeout },
+			...step.retry !== void 0 && { retry: {
+				maxAttempts: step.retry.maxAttempts,
+				delayMs: step.retry.delayMs,
+				backoff: step.retry.backoff,
+				maxDelayMs: step.retry.maxDelayMs
+			} },
 			...step.cache !== void 0 && { cache: normalizeCacheSpecs(step.cache) },
 			...step._sourceLocation && { sourceLocation: {
 				file: makeRelativePath(step._sourceLocation.file, gitRoot),
@@ -652,7 +678,7 @@ function transformSteps(steps, gitRoot) {
 			...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) }
+			...step.approval !== void 0 && { approval: (assertStepApprovalCheckFacet(step), toLockApproval(step.approval)) }
 		};
 	});
 }

package/dist/remote/config.d.ts

@@ -9,6 +9,8 @@ export interface GlobalConfig {
     endpoint?: string;
     /** Platform relay URL */
     platformEndpoint?: string;
+    /** OIDC issuer URL the PAT was minted against (provenance; from OAuth login) */
+    oidcIssuer?: string;
     /** Routing key for webhook source identification (e.g., 'github:42') */
     routingKey?: string;
     /** Personal access token (from OAuth login) */

package/dist/remote/config.js

@@ -14,6 +14,7 @@ function sanitizeConfig(raw) {
 	if (typeof obj.token === "string") config.token = obj.token;
 	if (typeof obj.endpoint === "string") config.endpoint = obj.endpoint;
 	if (typeof obj.platformEndpoint === "string") config.platformEndpoint = obj.platformEndpoint;
+	if (typeof obj.oidcIssuer === "string") config.oidcIssuer = obj.oidcIssuer;
 	if (typeof obj.routingKey === "string") config.routingKey = obj.routingKey;
 	if (typeof obj.pat === "string") config.pat = obj.pat;
 	if (typeof obj.patId === "string") config.patId = obj.patId;

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

@@ -10,7 +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';
+import type { CheckMode, HostTargetSelector } from '@kici-dev/engine';
 export declare class AuthenticationError extends Error {
     constructor(message?: string);
 }
@@ -77,6 +77,17 @@ export interface PlatformTriggerInput {
      * agent step loop in the requested mode. Omitted means `apply`.
      */
     checkMode?: CheckMode;
+    /**
+     * Host narrowing from `kici run --target`. The Platform relays it verbatim to
+     * the orchestrator, which intersects each runsOnAll roster with it.
+     */
+    target?: HostTargetSelector;
+    /**
+     * Raw operator-supplied `kici run --input KEY=VALUE` pairs (not defaulted /
+     * coerced). The Platform relays them verbatim; the orchestrator validates,
+     * coerces, and applies defaults authoritatively against the lock descriptor.
+     */
+    dispatchInputs?: Record<string, string>;
 }
 export interface PlatformTriggerResponse {
     runId: string;

package/dist/remote/uploader.js

@@ -232,6 +232,7 @@ function getSizeWarning(compressedSize) {
 */
 async function uploadTarball(opts) {
 	const { tarballPath, signedUrl, orchestratorPublicKey, onProgress } = opts;
+	if (!signedUrl) throw new Error("The orchestrator did not return an upload URL, so the overlay cannot be uploaded. This usually means the orchestrator has no object storage configured for remote runs. Ask your orchestrator operator to enable cache storage (KICI_STORAGE_TYPE=s3 or filesystem).");
 	const { encryptedPath, cliPublicKey } = await encryptTarball(tarballPath, orchestratorPublicKey);
 	const encryptedData = await fs.readFile(encryptedPath);
 	const encryptedSize = encryptedData.length;

package/dist/templates/package-json.js

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

package/dist/test-runner/rule-evaluator.d.ts

@@ -3,7 +3,7 @@ import type { RuleEvaluationResult } from '@kici-dev/sdk';
 /**
  * Create RuleContext for rule evaluation.
  */
-export declare function createRuleContext(event: EventPayload, changedFiles?: string[]): RuleContext;
+export declare function createRuleContext(event: EventPayload, changedFiles?: string[], dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>): RuleContext;
 /**
  * Evaluate rules with formatting output.
  * Wraps the SDK's evaluateRules() with a callback that logs each rule result.

package/dist/test-runner/rule-evaluator.js

@@ -8,11 +8,12 @@ initZx();
 /**
 * Create RuleContext for rule evaluation.
 */
-function createRuleContext(event, changedFiles = []) {
+function createRuleContext(event, changedFiles = [], dispatchInputs = {}) {
 	return {
 		event,
 		changedFiles,
 		env: { ...process.env },
+		dispatchInputs,
 		$
 	};
 }

package/dist/test-runner/step-context.d.ts

@@ -11,5 +11,5 @@ import type { StepContext, WorkflowInfo, JobInfo, MatrixValues } from '@kici-dev
 export declare function createStepContext(workflowInfo: WorkflowInfo, jobInfo: JobInfo, repoRoot: string, inputs?: Record<string, unknown>, matrix?: MatrixValues, testSecrets?: {
     flat: Record<string, string>;
     contexts: Record<string, Record<string, string>>;
-}, environment?: string, rawPayload?: Record<string, unknown>, provider?: string): StepContext;
+}, environment?: string, rawPayload?: Record<string, unknown>, provider?: string, dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>): StepContext;
 //# sourceMappingURL=step-context.d.ts.map

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

@@ -42,7 +42,7 @@ function createTestLogger(jobName) {
 * `ctx.$` would inherit `process.cwd()` — i.e. wherever the user invoked
 * `kici` — which silently breaks any step that uses relative paths.
 */
-function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix, testSecrets, environment, rawPayload, provider) {
+function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix, testSecrets, environment, rawPayload, provider, dispatchInputs = {}) {
 	const flat = testSecrets?.flat ?? {};
 	const namespacedSecrets = testSecrets?.contexts ?? {};
 	const mergedFlat = { ...flat };
@@ -110,6 +110,7 @@ function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix,
 			process.env.PATH = updated;
 		},
 		inputs,
+		dispatchInputs,
 		workflow: workflowInfo,
 		job: jobInfo,
 		matrix,
@@ -137,7 +138,12 @@ function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix,
 				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")) }
+			oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available in the local test runner")) },
+			host: { requestReboot: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.host.requestReboot() is not available in the local test runner")) },
+			bootstrap: {
+				ensureInitRunner: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.ensureInitRunner() is not available in the local test runner")),
+				preBootSend: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.preBootSend() is not available in the local test runner"))
+			}
 		},
 		cache: {
 			restore: async () => ({ hit: false }),

package/dist/types.d.ts

@@ -12,18 +12,23 @@
  * v15 adds per-job init config(s).
  * v17 widens per-job init to typed presets ('mise' / { mise }) and 'auto' detection.
  */
-import type { ResourceRequest, ApproverClause, RunsOnAllPredicate, OnUnreachableMode, LabelMatcher } from '@kici-dev/engine';
+import type { ResourceRequest, ApproverClause, RunsOnAllPredicate, OnUnreachableMode, LabelMatcher, ExecutionJobStatus, InputsDescriptorMap } from '@kici-dev/engine';
 /**
  * Normalized approval config carried in the lock file. Mirrors the engine
- * `LockApproval` type. Produced by the compiler from an SDK `requireApproval`.
+ * `LockApproval` type. Produced by the compiler from an SDK `approval` config.
  */
 export interface LockApproval {
     readonly clauses: ApproverClause[];
     readonly reason?: string;
     readonly timeoutSeconds?: number;
+    /**
+     * When the gate fires. `always` (default) gates before the element; `drift`
+     * gates between a step's check and run on detected drift (step scope only).
+     */
+    readonly when: 'always' | 'drift';
 }
 /** Schema version - re-exported from engine as single source of truth */
-export declare const SCHEMA_VERSION: 21;
+export declare const SCHEMA_VERSION: 26;
 /**
  * Source file reference with meaningful path.
  * Format: file is relative path from git root, export uses hash syntax.
@@ -122,6 +127,8 @@ export interface LockDispatchTrigger {
     readonly _type: 'dispatch';
     readonly types: readonly string[];
     readonly repos?: readonly LockBranchPattern[];
+    /** Typed dispatch-input descriptors (from `dispatch({ inputs })`). */
+    readonly inputs?: InputsDescriptorMap;
 }
 /**
  * Create trigger in lock file.
@@ -367,15 +374,15 @@ export declare function isLockInlineValue(value: unknown): value is LockInlineVa
  * (e.g., `kici:role:builder`, `kici:role:init-runner`) are injected by the orchestrator
  * for internal job types (build/init) and are not user-settable.
  */
-/** Needs entry with per-edge failure policy (mirrors engine NeedsEntry). */
+/** Needs entry with per-edge run-on status-set (mirrors engine NeedsEntry). */
 export interface LockNeedsEntry {
     readonly name: string;
-    readonly ifFailed: 'skip' | 'run';
+    readonly runOn: ExecutionJobStatus[];
 }
 /** Needs group entry for dynamic group dependencies (mirrors engine NeedsGroupEntry). */
 export interface LockNeedsGroupEntry {
     readonly group: string;
-    readonly ifFailed: 'skip' | 'run';
+    readonly runOn: ExecutionJobStatus[];
 }
 export interface LockJob {
     readonly _type: 'static';
@@ -387,6 +394,8 @@ export interface LockJob {
     readonly runsOnAll?: RunsOnAllPredicate;
     /** Failure policy for unreachable durable hosts in a runsOnAll fan-out. */
     readonly onUnreachable?: OnUnreachableMode;
+    /** Widen runsOnAll to declared-but-un-agented hosts (init-runner bring-up per fresh box). */
+    readonly includeUninitialized?: boolean;
     /** Fan-out concurrency width (sliding window; 1 = serial). Applies to matrix and runsOnAll. */
     readonly maxParallel?: number;
     /** Halt the fan-out on first child failure, skipping the held remainder. Default false. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/compiler",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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.21",
-    "@kici-dev/engine": "0.1.21"
+    "@kici-dev/core": "0.1.23",
+    "@kici-dev/engine": "0.1.23"
   },
   "peerDependencies": {
-    "@kici-dev/sdk": "0.1.21"
+    "@kici-dev/sdk": "0.1.23"
   },
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4"