@kici-dev/sdk 0.1.22 → 0.1.24

package/dist/api-types.d.ts

@@ -74,6 +74,40 @@ export interface HostApi {
         deadlineMs?: number;
     }): Promise<void>;
 }
+export interface BootstrapApi {
+    /**
+     * Bring up a temporary privileged init-runner on a declared-but-un-agented
+     * host over SSH, so it auto-enrolls as a short-lived `kici:init` agent. The
+     * step calling this must run on an agent holding the
+     * `kici:capability:ssh-transport` capability (the orchestrator refuses
+     * otherwise). No-op (`broughtUp: false`) when the target already has a live
+     * agent. Each bring-up is access-logged.
+     *
+     * The target's reach metadata + the bring-up SSH key (a scoped secret) are
+     * resolved server-side from the host roster — the workflow author supplies
+     * only the target agent id.
+     */
+    ensureInitRunner(targetAgentId: string): Promise<{
+        broughtUp: boolean;
+    }>;
+    /**
+     * Ship an input to a host's pre-boot SSH channel (e.g. a LUKS passphrase to
+     * a dropbear/initramfs `cryptroot-unlock` prompt on port 2222). Generic
+     * "pipe stdin to a forced-command endpoint"; the unlock recipe is
+     * per-host-passphrase → `preBootSend` → `waitForHostAlive`. Same
+     * `kici:capability:ssh-transport` gate + access-log as `ensureInitRunner`.
+     *
+     * `inputSecret` is a scoped-secret ref (`scope/key`) the orchestrator
+     * resolves server-side; the plaintext never passes through the workflow.
+     * Success is the send completing (the session drops as the box boots) —
+     * compose `restartHost`/host-alive waits to confirm the boot.
+     */
+    preBootSend(targetAgentId: string, opts: {
+        inputSecret: string;
+        port?: number;
+        command?: string;
+    }): Promise<void>;
+}
 export interface KiciApi {
     /** Query orchestrator infrastructure (scalers, agents). */
     infrastructure: InfrastructureApi;
@@ -83,6 +117,8 @@ export interface KiciApi {
     oidc: OidcApi;
     /** Host-lifecycle operations on the agent's own host (e.g. reboot). */
     host: HostApi;
+    /** Fresh-box bootstrap bring-up (init-runner over SSH, pre-boot unlock). */
+    bootstrap: BootstrapApi;
 }
 /**
  * Low-level transport function used to implement KiciApi.

package/dist/api-types.js

@@ -37,7 +37,14 @@ function buildKiciApi(transport, jobCtx) {
 				audience: opts.audience
 			});
 		} },
-		host: { requestReboot: (opts) => transport("host.requestReboot", { ...opts?.deadlineMs !== void 0 ? { deadlineMs: opts.deadlineMs } : {} }) }
+		host: { requestReboot: (opts) => transport("host.requestReboot", { ...opts?.deadlineMs !== void 0 ? { deadlineMs: opts.deadlineMs } : {} }) },
+		bootstrap: {
+			ensureInitRunner: (targetAgentId) => transport("kici.ensureInitRunner", { targetAgentId }),
+			preBootSend: (targetAgentId, opts) => transport("kici.preBootSend", {
+				targetAgentId,
+				...opts
+			})
+		}
 	};
 }
 //#endregion

package/dist/context.d.ts

@@ -3,6 +3,7 @@ import type { MatrixValues } from './matrix/types.js';
 import type { EventEmitOptions } from './events/types.js';
 import type { StepSecrets } from './secrets.js';
 import type { KiciApi } from './api-types.js';
+import type { FanoutPosition } from './fanout-context.js';
 /** Logger interface for step execution */
 export interface Logger {
     info(message: string, ...args: unknown[]): void;
@@ -113,8 +114,21 @@ export interface StepContext<TInputs = Record<string, unknown>> {
     setEnv(key: string, value: string): void;
     /** Prepend a directory to PATH, visible to this step and all subsequent steps. */
     addPath(dir: string): void;
+    /**
+     * Aborted when this step should stop early — the job is being cancelled, the
+     * job-level timeout fired, or (in a `parallel()` group) a sibling failed under
+     * fail-fast. Pass it to `fetch`, `ctx.$`, timers, or any cancellable async work
+     * to cooperatively unwind. Unaborted for a normally-running step.
+     */
+    signal: AbortSignal;
     /** Typed inputs from dependencies */
     inputs: TInputs;
+    /**
+     * Operator-supplied, validated + coerced workflow-dispatch inputs (from `dispatch({ inputs })`).
+     * Distinct from `inputs` (typed outputs from `needs` dependencies). Empty when none declared.
+     * Prefer the typed `defineDispatchInputs(...).from(ctx)` accessor for per-key types.
+     */
+    dispatchInputs: Readonly<Record<string, string | number | boolean | null>>;
     /** Current workflow metadata */
     workflow: WorkflowInfo;
     /** Current job metadata */
@@ -137,10 +151,16 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * platform, arch). Set only for jobs that use `runsOnAll`. Undefined otherwise.
      */
     agent?: AgentInfo;
+    /**
+     * Position of this child within its fan-out (a `runsOnAll` host or a matrix
+     * combination), deterministically ordered (host: by `agentId`; matrix: by
+     * variant label). Undefined on a non-fan-out job.
+     */
+    fanout?: FanoutPosition;
     /**
      * Raw webhook payload from the git provider.
      * Contains the full, unmodified payload as received from the webhook.
-     * In local test mode (kici test), contains the simulated payload.
+     * In local preview/run mode (`kici preview` / `kici run local`), contains the simulated payload.
      * Use this for provider-specific data not covered by normalized fields.
      */
     rawPayload?: Record<string, unknown>;
@@ -151,7 +171,7 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      */
     provider?: string;
     /**
-     * Whether this execution was triggered by `kici test` (remote test run).
+     * Whether this execution was triggered by `kici run remote` (developer-initiated remote run).
      * Use to conditionally skip destructive operations in test mode.
      * Defaults to false for backward compatibility.
      */

package/dist/fanout-context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Deterministic position of a fan-out child within its fan-out.
+ *
+ * A fan-out child is one of:
+ * - a `runsOnAll` host execution (one pinned execution per matching roster host), or
+ * - a matrix combination (one execution per expanded combination).
+ *
+ * The order is deterministic: host fan-out is sorted by `agentId`, matrix fan-out by
+ * its variant label, so `first` is always reproducible across re-runs.
+ */
+export interface FanoutPosition {
+    /** 0-based position in the deterministically-ordered fan-out. */
+    index: number;
+    /** Number of children in this fan-out. */
+    total: number;
+    /** Whether this is the first child (`index === 0`). */
+    first: boolean;
+    /** Whether this is the last child (`index === total - 1`). */
+    last: boolean;
+}
+//# sourceMappingURL=fanout-context.d.ts.map

package/dist/fanout-context.js

@@ -0,0 +1,2 @@
+import "./chunk-BTugEXQM.js";
+export {};

package/dist/fixture.d.ts

@@ -2,7 +2,7 @@
  * Fixture factory for defining test event replicas.
  *
  * Fixtures declare which trigger event to simulate when running
- * `kici test <name>`. They are event replicas (not assertions) --
+ * `kici run remote <name>`. They are event replicas (not assertions) --
  * pass/fail is determined by the pipeline execution.
  */
 import type { TriggerConfig } from './triggers/types.js';
@@ -25,7 +25,7 @@ export interface FixtureOptions {
 }
 /** Resolved fixture definition */
 export interface Fixture {
-    /** Unique fixture ID used in `kici test <name>` */
+    /** Unique fixture ID used in `kici run remote <name>` */
     readonly id: string;
     /** Fixture options (plain object or async factory function) */
     readonly options: FixtureOptions | (() => FixtureOptions | Promise<FixtureOptions>);
@@ -33,7 +33,7 @@ export interface Fixture {
 /**
  * Create a test fixture definition.
  *
- * @param id - Unique fixture ID (no whitespace allowed, used in `kici test <name>`)
+ * @param id - Unique fixture ID (no whitespace allowed, used in `kici run remote <name>`)
  * @param options - Fixture configuration or async factory function
  * @returns Frozen fixture definition
  *

package/dist/fixture.js

@@ -3,7 +3,7 @@ import "./chunk-BTugEXQM.js";
 /**
 * Create a test fixture definition.
 *
-* @param id - Unique fixture ID (no whitespace allowed, used in `kici test <name>`)
+* @param id - Unique fixture ID (no whitespace allowed, used in `kici run remote <name>`)
 * @param options - Fixture configuration or async factory function
 * @returns Frozen fixture definition
 *

package/dist/idempotent.d.ts

@@ -21,7 +21,8 @@
  *   whose run function executes `idempotent(...)` and propagates ctx.log
  *   into the runner's status sink.
  */
-import type { Step } from './types.js';
+import type { Step, StepOptionsBase } from './types.js';
+import type { StepContext } from './context.js';
 export interface IdempotentOptions<TDrift, TInSync = void, TApplied = void> {
     /** Optional name surfaced in status lines and error messages. */
     name?: string;
@@ -68,4 +69,34 @@ export declare function idempotent<TDrift, TInSync = void, TApplied = void>(opts
  * The step's typed return value is the IdempotentResult union.
  */
 export declare function idempotentStep<TDrift, TInSync = void, TApplied = void>(name: string, opts: Omit<IdempotentOptions<TDrift, TInSync, TApplied>, 'name' | 'log'>): Step<IdempotentResult<TDrift, TInSync, TApplied>>;
+/**
+ * Options for {@link checkStep}. The same shape as `idempotentStep`'s options,
+ * except `apply` and `whenInSync` receive `ctx` first (matching the `step()`
+ * check facet's `run(ctx, drift)` form) so the apply logic has access to
+ * `ctx.$` / `ctx.log` / `ctx.secrets`. The remaining `StepOptionsBase`
+ * passthroughs (`continueOnError`, `timeout`, `rules`, `outputs`, `retry`, …)
+ * are forwarded to the underlying step.
+ */
+export interface CheckStepOptions<TDrift, TInSync = void, TApplied = void> extends Omit<StepOptionsBase, 'onCancel' | 'cleanup' | 'approval'> {
+    /** Read-only inspection: drift if apply would change state, or null if in sync. */
+    check: (ctx: StepContext) => Promise<TDrift | null>;
+    /** Brings the system to the desired state. Runs only in apply mode (skipped under `kici run --check`). */
+    apply: (ctx: StepContext, drift: TDrift) => Promise<TApplied>;
+    /** Required: human-readable summary of what apply() would do; shown in check-mode drift output. */
+    summarize: (drift: TDrift) => string;
+    /** Runs when check() returns null (already in sync). */
+    whenInSync?: (ctx: StepContext) => Promise<TInSync>;
+}
+/**
+ * Factory returning a check-facet SDK Step — the check-mode-aware sibling of
+ * {@link idempotentStep}. Unlike `idempotentStep` (which always applies on
+ * drift), a `checkStep` respects the run-level check mode: `kici run --check`
+ * reports the drift and skips `apply`, while apply mode applies it.
+ *
+ * It desugars to the `step()` check facet
+ * (`run: (ctx, drift) => apply(ctx, drift)`), so it inherits the agent
+ * step-loop and local-executor check-mode drive for free — no engine, agent,
+ * orchestrator, or lockfile change.
+ */
+export declare function checkStep<TDrift, TInSync = void, TApplied = void>(name: string, options: CheckStepOptions<TDrift, TInSync, TApplied>): Step<TApplied | TInSync>;
 //# sourceMappingURL=idempotent.d.ts.map

package/dist/idempotent.js

@@ -71,7 +71,32 @@ function idempotentStep(name, opts) {
 		log: (line) => ctx.log.info(line)
 	}) });
 }
+/**
+* Factory returning a check-facet SDK Step — the check-mode-aware sibling of
+* {@link idempotentStep}. Unlike `idempotentStep` (which always applies on
+* drift), a `checkStep` respects the run-level check mode: `kici run --check`
+* reports the drift and skips `apply`, while apply mode applies it.
+*
+* It desugars to the `step()` check facet
+* (`run: (ctx, drift) => apply(ctx, drift)`), so it inherits the agent
+* step-loop and local-executor check-mode drive for free — no engine, agent,
+* orchestrator, or lockfile change.
+*/
+function checkStep(name, options) {
+	return step(name, {
+		check: options.check,
+		summarize: options.summarize,
+		run: (ctx, drift) => options.apply(ctx, drift),
+		...options.whenInSync && { whenInSync: options.whenInSync },
+		...options.outputs !== void 0 && { outputs: options.outputs },
+		...options.continueOnError !== void 0 && { continueOnError: options.continueOnError },
+		...options.timeout !== void 0 && { timeout: options.timeout },
+		...options.retry !== void 0 && { retry: options.retry },
+		...options.cache !== void 0 && { cache: options.cache },
+		...options.rules !== void 0 && { rules: options.rules }
+	});
+}
 //#endregion
-export { idempotent, idempotentStep };
+export { checkStep, idempotent, idempotentStep };
 
 //# sourceMappingURL=idempotent.js.map

package/dist/index.d.ts

@@ -1,19 +1,21 @@
 export { step } from './step.js';
 export { job } from './job.js';
 export { workflow } from './workflow.js';
+export { parallel, isParallelGroup, flattenStepInputs } from './parallel.js';
+export type { ParallelGroup, ParallelOptions } from './parallel.js';
 export { normalizeApproval } from './approval.js';
 export type { ApprovalConfig, ApprovalWhen, ApproverClause, NormalizedApproval, } from './approval.js';
-export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle, } from './triggers/index.js';
-export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './triggers/index.js';
+export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle, defineDispatchInputs, } from './triggers/index.js';
+export type { DefinedDispatchInputs, InferDispatchInputs, DispatchInputsMap, TriggerConfig, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './triggers/index.js';
 export { onCancel, cleanup, onSuccess, onFailure, beforeStep, afterStep } from './hooks/index.js';
 export type { HookConfig, HookFn, HookInput, HookContext, OutcomeMetadata } from './hooks/index.js';
-export { rule, skip } from './rules/index.js';
+export { rule, skip, onlyOnFirstHost, onlyOnLastHost, onlyOnFanoutIndex } from './rules/index.js';
 export { evaluateRules } from './rules/index.js';
 export { isEventType } from './rules/index.js';
 export type { Rule, RuleContext, RuleCheckFn, RuleResult, EventPayload, RuleEvaluationResult, EventBase, PullRequestEventPayload, PushEventPayload, TagEventPayload, CommentEventPayload, ReviewEventPayload, ReviewCommentEventPayload, ReleaseEventPayload, DispatchEventPayload, CreateEventPayload, DeleteEventPayload, StatusEventPayload, WorkflowRunEventPayload, ForkEventPayload, StarEventPayload, WatchEventPayload, WebhookEventPayload, KiciEventPayload, WorkflowCompleteEventPayload, JobCompleteEventPayload, GenericWebhookEventPayload, ScheduleEventPayload, LifecycleEventPayload, GitHubRepository, GitHubUser, GitHubPullRequest, GitHubCommit, GitHubComment, GitHubReview, GitHubRelease, } from './rules/index.js';
 export { validateDag } from './validation/index.js';
 export type { DagNode, DagValidationResult } from './validation/index.js';
-export type { SourceLocation, OutputProxy, Step, StepOptions, StepOptionsBase, StepOptionsPlain, StepOptionsWithCheck, StepRunFn, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, MiseInitConfig, InitPreset, InitItem, InitConfig, ContainerConfig, RunsOnSelector, RunsOn, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
+export type { SourceLocation, OutputProxy, Step, StepOptions, StepOptionsBase, StepOptionsPlain, StepOptionsWithCheck, StepRunFn, RetryConfig, NormalizedRetry, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, MiseInitConfig, InitPreset, InitItem, InitConfig, ContainerConfig, RunsOnSelector, RunsOn, RunsOnPick, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
 export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, } from './types.js';
 export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, NeedsWhen, NeedsWhenInput, } from './types.js';
 export { buildNeedsContext } from './needs-context.js';
@@ -27,6 +29,7 @@ export { dynamicGroup, isDynamicGroupRef, DYNAMIC_GROUP_TAG } from './dynamic-gr
 export type { DynamicGroupRef } from './dynamic-group.js';
 export type { StepContext, Logger, WorkflowInfo, JobInfo, AgentInfo, MatrixJobOutputs, HostJobOutputs, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
 export { isMatrixJobOutputs, isHostJobOutputs } from './context.js';
+export type { FanoutPosition } from './fanout-context.js';
 export { buildKiciApi } from './api-types.js';
 export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, InventoryApi, HostApi, HostInventoryEntry, InventorySelector, } from './api-types.js';
 export { SecretNotFoundError } from './errors.js';
@@ -42,8 +45,8 @@ export type { EventDefinition } from './events/index.js';
 export type { EventEmitOptions } from './events/index.js';
 export { fixture } from './fixture.js';
 export type { Fixture, FixtureOptions } from './fixture.js';
-export { idempotent, idempotentStep } from './idempotent.js';
-export type { IdempotentOptions, IdempotentResult } from './idempotent.js';
+export { idempotent, idempotentStep, checkStep } from './idempotent.js';
+export type { IdempotentOptions, IdempotentResult, CheckStepOptions } from './idempotent.js';
 export { waitFor, waitForStep, WaitForTimeoutError } from './wait-for.js';
 export type { WaitForOptions, WaitForResult } from './wait-for.js';
 export { waitForHostAlive, restartHost } from './host-restart.js';

package/dist/index.js

@@ -10,9 +10,10 @@ import { createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy,
 import { step } from "./step.js";
 import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
 import { restartHost, waitForHostAlive } from "./host-restart.js";
-import { idempotent, idempotentStep } from "./idempotent.js";
+import { checkStep, idempotent, idempotentStep } from "./idempotent.js";
 import { job } from "./job.js";
 import { workflow } from "./workflow.js";
+import { flattenStepInputs, isParallelGroup, parallel } from "./parallel.js";
 import { pr } from "./triggers/pr.js";
 import { push } from "./triggers/push.js";
 import { tag } from "./triggers/tag.js";
@@ -35,9 +36,10 @@ import { jobComplete } from "./triggers/job-complete.js";
 import { genericWebhook } from "./triggers/generic-webhook.js";
 import { schedule } from "./triggers/schedule.js";
 import { lifecycle } from "./triggers/lifecycle.js";
+import { defineDispatchInputs } from "./triggers/dispatch-inputs.js";
 import "./triggers/index.js";
 import { afterStep, beforeStep, cleanup, onCancel, onFailure, onSuccess } from "./hooks/index.js";
-import { rule, skip } from "./rules/rule.js";
+import { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip } from "./rules/rule.js";
 import { evaluateRules } from "./rules/evaluator.js";
 import { isEventType } from "./events/event-payloads.js";
 import "./rules/index.js";
@@ -53,4 +55,4 @@ import "./matrix/index.js";
 import { defineEvent } from "./events/define-event.js";
 import "./events/index.js";
 import { z } from "zod";
-export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, cleanup, comment, create, createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isHostJobOutputs, isMatrixJobOutputs, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, restartHost, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForHostAlive, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };
+export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, checkStep, cleanup, comment, create, createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineDispatchInputs, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, flattenStepInputs, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isHostJobOutputs, isMatrixJobOutputs, isParallelGroup, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, parallel, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, restartHost, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForHostAlive, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };

package/dist/job.js

@@ -32,15 +32,20 @@ function job(nameOrOptions, maybeOptions) {
 		steps = [options.run];
 	}
 	validateInit(options.init, name);
+	const firstEnv = options.environments?.[0];
+	const concurrencyGroup = options.concurrencyGroup ?? (typeof firstEnv === "string" ? firstEnv : void 0);
+	if (options.environment !== void 0 && options.environments !== void 0) throw new Error(`job('${name}'): environment and environments are mutually exclusive — use one`);
 	if (options.runsOn !== void 0 && options.runsOnAll !== void 0) throw new Error(`job('${name}'): runsOn and runsOnAll are mutually exclusive`);
 	if (options.runsOn === void 0 && options.runsOnAll === void 0) throw new Error(`job('${name}'): one of runsOn or runsOnAll is required`);
 	if (options.onUnreachable !== void 0 && options.runsOnAll === void 0) console.warn(`[kici] job('${name}'): onUnreachable is ignored without runsOnAll`);
+	if (options.includeUninitialized !== void 0 && options.runsOnAll === void 0) console.warn(`[kici] job('${name}'): includeUninitialized is ignored without runsOnAll`);
 	return {
 		_tag: "Job",
 		name,
 		...options.runsOn !== void 0 && { runsOn: options.runsOn },
 		...options.runsOnAll !== void 0 && { runsOnAll: options.runsOnAll },
 		...options.onUnreachable !== void 0 && { onUnreachable: options.onUnreachable },
+		...options.includeUninitialized !== void 0 && { includeUninitialized: options.includeUninitialized },
 		...options.maxParallel !== void 0 && { maxParallel: options.maxParallel },
 		...options.failFast !== void 0 && { failFast: options.failFast },
 		steps,
@@ -53,8 +58,9 @@ function job(nameOrOptions, maybeOptions) {
 		checkout: options.checkout,
 		container: options.container,
 		environment: options.environment,
+		environments: options.environments,
 		env: options.env,
-		concurrencyGroup: options.concurrencyGroup,
+		concurrencyGroup,
 		onCancel: options.onCancel,
 		cleanup: options.cleanup,
 		onSuccess: options.onSuccess,

package/dist/parallel.d.ts

@@ -0,0 +1,40 @@
+import type { Step, BareStepFn, StepInput } from './types.js';
+/** A flat step entry: a step or bare function, never a parallel group. */
+export type FlatStepInput = Step<any> | BareStepFn<any>;
+/**
+ * A concurrent group of steps with a join barrier. Each child runs concurrently
+ * and surfaces as its own observable dashboard step (own logs, status, timing).
+ * Execution continues past the group only once every child has settled.
+ */
+export interface ParallelGroup {
+    readonly _tag: 'ParallelGroup';
+    /** Optional group label shown on the dashboard band. */
+    readonly name?: string;
+    /** When the first child fails, cancel in-flight siblings (default `true`). */
+    readonly failFast: boolean;
+    /** Maximum children running at once; queued children show `pending`. */
+    readonly maxParallel?: number;
+    readonly steps: readonly StepInput[];
+}
+export interface ParallelOptions {
+    readonly failFast?: boolean;
+    readonly maxParallel?: number;
+    readonly name?: string;
+}
+/**
+ * Run `steps` concurrently with a join barrier; each child is its own
+ * observable step. A `parallel()` group's `failFast`/`maxParallel` nest inside
+ * the job-level fan-out scopes — they govern only this step group.
+ */
+export declare function parallel(steps: StepInput[], opts?: ParallelOptions): ParallelGroup;
+/** Type guard distinguishing a `ParallelGroup` from a step or bare function. */
+export declare function isParallelGroup(x: unknown): x is ParallelGroup;
+/**
+ * Flatten a job's `steps` into a flat list where each parallel group's children
+ * are inlined in array order (the group wrapper is dropped). Used by single-
+ * process consumers (the local executor and dry-run preview) that surface each
+ * child as its own step but do not run a concurrent scheduler; the concurrent
+ * agent path expands groups into observable concurrent tasks instead.
+ */
+export declare function flattenStepInputs(steps: readonly StepInput[]): FlatStepInput[];
+//# sourceMappingURL=parallel.d.ts.map

package/dist/parallel.js

@@ -0,0 +1,37 @@
+import "./chunk-BTugEXQM.js";
+//#region src/parallel.ts
+/**
+* Run `steps` concurrently with a join barrier; each child is its own
+* observable step. A `parallel()` group's `failFast`/`maxParallel` nest inside
+* the job-level fan-out scopes — they govern only this step group.
+*/
+function parallel(steps, opts = {}) {
+	return {
+		_tag: "ParallelGroup",
+		name: opts.name,
+		failFast: opts.failFast ?? true,
+		maxParallel: opts.maxParallel,
+		steps
+	};
+}
+/** Type guard distinguishing a `ParallelGroup` from a step or bare function. */
+function isParallelGroup(x) {
+	return typeof x === "object" && x !== null && x._tag === "ParallelGroup";
+}
+/**
+* Flatten a job's `steps` into a flat list where each parallel group's children
+* are inlined in array order (the group wrapper is dropped). Used by single-
+* process consumers (the local executor and dry-run preview) that surface each
+* child as its own step but do not run a concurrent scheduler; the concurrent
+* agent path expands groups into observable concurrent tasks instead.
+*/
+function flattenStepInputs(steps) {
+	const flat = [];
+	for (const entry of steps) if (isParallelGroup(entry)) flat.push(...entry.steps);
+	else flat.push(entry);
+	return flat;
+}
+//#endregion
+export { flattenStepInputs, isParallelGroup, parallel };
+
+//# sourceMappingURL=parallel.js.map

package/dist/rules/index.d.ts

@@ -1,4 +1,4 @@
-export { rule, skip } from './rule.js';
+export { rule, skip, onlyOnFirstHost, onlyOnLastHost, onlyOnFanoutIndex } from './rule.js';
 export { evaluateRules, type RuleEvaluationResult } from './evaluator.js';
 export type { Rule, RuleCheckFn, RuleContext, RuleResult, EventPayload } from './types.js';
 export { isEventType } from '../events/event-payloads.js';

package/dist/rules/index.js

@@ -1,5 +1,5 @@
 import "../chunk-BTugEXQM.js";
-import { rule, skip } from "./rule.js";
+import { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip } from "./rule.js";
 import { evaluateRules } from "./evaluator.js";
 import { isEventType } from "../events/event-payloads.js";
-export { evaluateRules, isEventType, rule, skip };
+export { evaluateRules, isEventType, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip };

package/dist/rules/rule.d.ts

@@ -31,4 +31,24 @@ export declare function rule(label: string, check: RuleCheckFn): Rule;
  * });
  */
 export declare function skip(label: string, check: RuleCheckFn): Rule;
+/**
+ * Run a step only on the first fan-out child (the lowest-`agentId` host, or the
+ * first matrix variant). KiCI's `run_once`-on-the-first-host primitive.
+ *
+ * A non-fan-out job is treated as a single implicit child at index 0, so a step
+ * gated this way runs normally there (there is exactly one host, which is first).
+ *
+ * @example
+ * step('enable sync mode', async (ctx) => { ... }, { rules: [onlyOnFirstHost()] })
+ */
+export declare function onlyOnFirstHost(): Rule;
+/**
+ * Run a step only on the last fan-out child. Runs normally when not fanned out.
+ */
+export declare function onlyOnLastHost(): Rule;
+/**
+ * Run a step only on the fan-out child at index `n`. A non-fan-out job is the
+ * implicit child at index 0, so `onlyOnFanoutIndex(0)` runs normally there.
+ */
+export declare function onlyOnFanoutIndex(n: number): Rule;
 //# sourceMappingURL=rule.d.ts.map

package/dist/rules/rule.js

@@ -31,7 +31,33 @@ function skip(label, check) {
 		check: async (ctx) => !await check(ctx)
 	};
 }
+/**
+* Run a step only on the first fan-out child (the lowest-`agentId` host, or the
+* first matrix variant). KiCI's `run_once`-on-the-first-host primitive.
+*
+* A non-fan-out job is treated as a single implicit child at index 0, so a step
+* gated this way runs normally there (there is exactly one host, which is first).
+*
+* @example
+* step('enable sync mode', async (ctx) => { ... }, { rules: [onlyOnFirstHost()] })
+*/
+function onlyOnFirstHost() {
+	return rule("fanout: first host only", (ctx) => ctx.fanout === void 0 || ctx.fanout.first);
+}
+/**
+* Run a step only on the last fan-out child. Runs normally when not fanned out.
+*/
+function onlyOnLastHost() {
+	return rule("fanout: last host only", (ctx) => ctx.fanout === void 0 || ctx.fanout.last);
+}
+/**
+* Run a step only on the fan-out child at index `n`. A non-fan-out job is the
+* implicit child at index 0, so `onlyOnFanoutIndex(0)` runs normally there.
+*/
+function onlyOnFanoutIndex(n) {
+	return rule(`fanout: index ${n} only`, (ctx) => (ctx.fanout?.index ?? 0) === n);
+}
 //#endregion
-export { rule, skip };
+export { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip };
 
 //# sourceMappingURL=rule.js.map

package/dist/rules/types.d.ts

@@ -1,5 +1,6 @@
 import type { $ as Shell } from 'zx';
 import type { EventPayload } from '../events/event-payloads.js';
+import type { FanoutPosition } from '../fanout-context.js';
 export type { EventPayload } from '../events/event-payloads.js';
 /**
  * Context passed to rule check functions.
@@ -12,6 +13,14 @@ export interface RuleContext {
     changedFiles: string[];
     /** Environment variables */
     env: Record<string, string | undefined>;
+    /** Operator-supplied, validated + coerced workflow-dispatch inputs. Empty when none declared. */
+    dispatchInputs: Readonly<Record<string, string | number | boolean | null>>;
+    /**
+     * Position of this child within its fan-out (a `runsOnAll` host or a matrix
+     * combination); undefined on a non-fan-out job. Read by the run-once rule
+     * helpers (`onlyOnFirstHost` / `onlyOnLastHost` / `onlyOnFanoutIndex`).
+     */
+    fanout?: FanoutPosition;
     /** zx shell executor for running commands */
     $: typeof Shell;
 }

package/dist/secrets.d.ts

@@ -48,7 +48,7 @@ export interface MountedFile {
  *
  * The SDK owns the public surface (`mountFile` / `exposeFile`) but defers
  * disk and `process.env` operations to the agent so the SDK stays free of
- * any `node:fs` / `node:os` imports. Local-test mode (`kici test`) plugs
+ * any `node:fs` / `node:os` imports. Local preview/run mode (`kici preview` / `kici run local`) plugs
  * in the same adapter shape against `os.tmpdir()`.
  */
 export interface StepSecretsFileHost {

package/dist/step.js

@@ -3,6 +3,22 @@ import { normalizeApproval } from "./approval.js";
 import { createStepOutputProxy } from "./outputs.js";
 //#region src/step.ts
 /**
+* Fill retry defaults and expand the `retry: N` shorthand into a
+* {@link NormalizedRetry}. `retryIf` is carried through unchanged (it is
+* execution-only and never serialized).
+*/
+function normalizeRetry(retry) {
+	if (retry === void 0) return void 0;
+	const cfg = typeof retry === "number" ? { maxAttempts: retry } : retry;
+	return {
+		maxAttempts: cfg.maxAttempts,
+		delayMs: cfg.delayMs ?? 1e3,
+		backoff: cfg.backoff ?? "exponential",
+		maxDelayMs: cfg.maxDelayMs ?? 3e4,
+		...cfg.retryIf && { retryIf: cfg.retryIf }
+	};
+}
+/**
 * Capture the call-site source location of step() using the V8 stack trace API.
 * Uses Error.captureStackTrace with the `step` function as the constructor argument
 * so the stack starts from step()'s caller.
@@ -61,6 +77,7 @@ function step(nameOrRunOrOptions, runOrOptions) {
 	}
 	if (options.check && !options.summarize) throw new Error("summarize is required when check is set");
 	if (options.approval !== void 0 && normalizeApproval(options.approval).when === "drift" && !options.check) throw new Error("approval.when \"drift\" requires a check facet");
+	const retry = normalizeRetry(options.retry);
 	return {
 		_tag: "Step",
 		name,
@@ -72,6 +89,7 @@ function step(nameOrRunOrOptions, runOrOptions) {
 		...options.whenInSync !== void 0 && { whenInSync: options.whenInSync },
 		continueOnError: options.continueOnError,
 		timeout: options.timeout,
+		...retry !== void 0 && { retry },
 		...options.cache !== void 0 && { cache: options.cache },
 		rules: options.rules,
 		onCancel: options.onCancel,

package/dist/triggers/dispatch-inputs.d.ts

@@ -0,0 +1,32 @@
+import type { z } from 'zod';
+import type { DispatchInputsMap } from './types.js';
+/** The per-key inferred output type of a declared dispatch-inputs map. */
+export type InferDispatchInputs<TMap extends DispatchInputsMap> = {
+    [K in keyof TMap]: z.infer<TMap[K]>;
+};
+/** A context that may carry validated, coerced dispatch inputs. */
+interface DispatchInputsCarrier {
+    dispatchInputs?: Record<string, unknown>;
+}
+/**
+ * A branded handle returned by `defineDispatchInputs`. It is accepted directly
+ * by `dispatch({ inputs })` and exposes typed `.from(ctx)` / `.fromRule(ctx)`
+ * readers over `ctx.dispatchInputs`, typed per declared key.
+ */
+export interface DefinedDispatchInputs<TMap extends DispatchInputsMap> {
+    readonly __kiciDispatchInputs: true;
+    readonly map: TMap;
+    /** Read the validated, coerced dispatch inputs from a step context, typed per declared key. */
+    from(ctx: DispatchInputsCarrier): InferDispatchInputs<TMap>;
+    /** Same, from a rule context. */
+    fromRule(ctx: DispatchInputsCarrier): InferDispatchInputs<TMap>;
+}
+/**
+ * Declare a typed workflow-dispatch inputs map once and get back a handle that
+ * both `dispatch({ inputs })` accepts and exposes a typed `.from(ctx)` reader —
+ * no double type annotation. Type safety comes via Standard-Schema inference
+ * (Zod 4 implements `~standard`), without a builder-generics refactor.
+ */
+export declare function defineDispatchInputs<TMap extends DispatchInputsMap>(map: TMap): DefinedDispatchInputs<TMap>;
+export {};
+//# sourceMappingURL=dispatch-inputs.d.ts.map

package/dist/triggers/dispatch-inputs.js

@@ -0,0 +1,21 @@
+import "../chunk-BTugEXQM.js";
+//#region src/triggers/dispatch-inputs.ts
+/**
+* Declare a typed workflow-dispatch inputs map once and get back a handle that
+* both `dispatch({ inputs })` accepts and exposes a typed `.from(ctx)` reader —
+* no double type annotation. Type safety comes via Standard-Schema inference
+* (Zod 4 implements `~standard`), without a builder-generics refactor.
+*/
+function defineDispatchInputs(map) {
+	const read = (ctx) => ctx.dispatchInputs ?? {};
+	return Object.freeze({
+		__kiciDispatchInputs: true,
+		map: Object.freeze({ ...map }),
+		from: read,
+		fromRule: read
+	});
+}
+//#endregion
+export { defineDispatchInputs };
+
+//# sourceMappingURL=dispatch-inputs.js.map

package/dist/triggers/dispatch.js

@@ -13,11 +13,15 @@ import { asArray, toBranchPattern } from "./types.js";
 */
 function dispatch(config) {
 	const repos = config?.repos ? asArray(config.repos).map(toBranchPattern) : [];
+	const rawInputs = config?.inputs;
+	let inputsMap;
+	if (rawInputs) inputsMap = "__kiciDispatchInputs" in rawInputs ? rawInputs.map : rawInputs;
 	const result = {
 		_tag: "DispatchTrigger",
 		types: Object.freeze(config?.types ? [...config.types] : []),
 		repos: Object.freeze([...repos]),
-		...config?.description !== void 0 && { description: config.description }
+		...config?.description !== void 0 && { description: config.description },
+		...inputsMap && { inputs: Object.freeze({ ...inputsMap }) }
 	};
 	return Object.freeze(result);
 }

package/dist/triggers/index.d.ts

@@ -23,6 +23,8 @@ export { jobComplete } from './job-complete.js';
 export { genericWebhook } from './generic-webhook.js';
 export { schedule } from './schedule.js';
 export { lifecycle } from './lifecycle.js';
-export type { BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, TriggerConfig, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './types.js';
+export { defineDispatchInputs } from './dispatch-inputs.js';
+export type { DefinedDispatchInputs, InferDispatchInputs } from './dispatch-inputs.js';
+export type { DispatchInputsMap, BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, TriggerConfig, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './types.js';
 export { DEFAULT_PR_EVENTS, toBranchPattern } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/triggers/index.js

@@ -22,4 +22,5 @@ import { jobComplete } from "./job-complete.js";
 import { genericWebhook } from "./generic-webhook.js";
 import { schedule } from "./schedule.js";
 import { lifecycle } from "./lifecycle.js";
-export { DEFAULT_PR_EVENTS, comment, create, del as delete, dispatch, fork, genericWebhook, jobComplete, kiciEvent, lifecycle, pr, push, release, review, reviewComment, schedule, star, status, tag, toBranchPattern, watch, webhook, workflowComplete, workflowRun };
+import { defineDispatchInputs } from "./dispatch-inputs.js";
+export { DEFAULT_PR_EVENTS, comment, create, defineDispatchInputs, del as delete, dispatch, fork, genericWebhook, jobComplete, kiciEvent, lifecycle, pr, push, release, review, reviewComment, schedule, star, status, tag, toBranchPattern, watch, webhook, workflowComplete, workflowRun };

package/dist/triggers/schedule.d.ts

@@ -15,6 +15,9 @@ import type { ScheduleConfigInput, ScheduleTriggerConfig } from './types.js';
  *
  * // Run weekly on Monday at 9am in a specific timezone
  * schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' })
+ *
+ * // Daily at midnight UTC, with a defaults-only input
+ * schedule({ cron: '0 0 * * *', inputs: { mode: z.enum(['full', 'quick']).default('full') } })
  */
 export declare function schedule(config: ScheduleConfigInput): ScheduleTriggerConfig;
 //# sourceMappingURL=schedule.d.ts.map

package/dist/triggers/schedule.js

@@ -12,14 +12,21 @@ import "../chunk-BTugEXQM.js";
 *
 * // Run weekly on Monday at 9am in a specific timezone
 * schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' })
+*
+* // Daily at midnight UTC, with a defaults-only input
+* schedule({ cron: '0 0 * * *', inputs: { mode: z.enum(['full', 'quick']).default('full') } })
 */
 function schedule(config) {
 	if (!config.cron || config.cron.trim() === "") throw new Error("schedule() requires a non-empty cron expression");
+	const rawInputs = config.inputs;
+	let inputsMap;
+	if (rawInputs) inputsMap = "__kiciDispatchInputs" in rawInputs ? rawInputs.map : rawInputs;
 	const result = {
 		_tag: "ScheduleTrigger",
 		cron: config.cron,
 		timezone: config.timezone ?? "UTC",
-		...config.description !== void 0 && { description: config.description }
+		...config.description !== void 0 && { description: config.description },
+		...inputsMap && { inputs: Object.freeze({ ...inputsMap }) }
 	};
 	return Object.freeze(result);
 }

package/dist/triggers/types.d.ts

@@ -2,6 +2,14 @@
  * Trigger types and interfaces for pr() and push() trigger helpers.
  * Supports both glob patterns and regex patterns for branch/path matching.
  */
+import type { z } from 'zod';
+/**
+ * A declared map of typed workflow-dispatch inputs: `{ name: ZodSchema }`.
+ * Each schema must fall within the closed dispatch-input subset (extracted by
+ * the compiler) — z.string/number/boolean/enum/literal plus
+ * .optional/.nullable/.default/.min/.max/.regex/.int.
+ */
+export type DispatchInputsMap = Record<string, z.ZodType>;
 /**
  * Branch pattern - discriminated union supporting both glob and regex patterns.
  * Glob patterns use micromatch syntax, regex patterns use standard JS regex.
@@ -165,6 +173,8 @@ export interface DispatchTriggerConfig {
     readonly types: readonly string[];
     readonly repos: readonly BranchPattern[];
     readonly description?: string;
+    /** Declared, typed workflow-dispatch inputs (frozen `{ name: ZodSchema }`). */
+    readonly inputs?: DispatchInputsMap;
 }
 /**
  * Input configuration for dispatch() factory function.
@@ -173,6 +183,16 @@ export interface DispatchConfigInput {
     readonly types?: string[];
     readonly repos?: string | RegExp | (string | RegExp)[];
     readonly description?: string;
+    /**
+     * Typed workflow-dispatch inputs. Accepts a bare `{ name: ZodSchema }` map or
+     * a `defineDispatchInputs(...)` branded handle (which also exposes a typed
+     * `.from(ctx)` accessor). The compiler validates each schema against the
+     * closed dispatch-input subset.
+     */
+    readonly inputs?: DispatchInputsMap | {
+        readonly __kiciDispatchInputs: true;
+        readonly map: DispatchInputsMap;
+    };
 }
 export type RefType = 'branch' | 'tag';
 /**
@@ -439,6 +459,16 @@ export interface ScheduleConfigInput {
     readonly cron: string;
     readonly timezone?: string;
     readonly description?: string;
+    /**
+     * Typed schedule inputs (defaults-only — no operator overrides on a fire).
+     * Accepts a bare `{ name: ZodSchema }` map or a `defineDispatchInputs(...)`
+     * branded handle. Each input must declare a `.default()` or be `.optional()`
+     * (enforced at compile time).
+     */
+    readonly inputs?: DispatchInputsMap | {
+        readonly __kiciDispatchInputs: true;
+        readonly map: DispatchInputsMap;
+    };
 }
 /**
  * Configuration for a schedule trigger.
@@ -448,6 +478,8 @@ export interface ScheduleTriggerConfig {
     readonly cron: string;
     readonly timezone: string;
     readonly description?: string;
+    /** Declared, typed schedule inputs (frozen `{ name: ZodSchema }`). */
+    readonly inputs?: DispatchInputsMap;
 }
 /**
  * Lifecycle event types for cross-workflow orchestration.

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod';
 import type { $ as Shell } from 'zx';
+import type { RetryBackoff } from '@kici-dev/core';
 import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode, NeedsWhen, ExecutionJobStatus } from '@kici-dev/engine';
 import type { StepContext, Logger } from './context.js';
 import type { TriggerConfig } from './triggers/types.js';
@@ -64,6 +65,8 @@ export interface Step<TResult = void> {
     readonly continueOnError?: boolean;
     /** Step-level timeout in milliseconds. Overrides the agent's default (30 minutes). */
     readonly timeout?: number;
+    /** Normalized retry policy (defaults filled, shorthand expanded). `retryIf` is execution-only. */
+    readonly retry?: NormalizedRetry;
     /** Declarative cache: restored before this step, saved after on key miss. */
     readonly cache?: import('./cache-types.js').CacheInput;
     /** Step-level conditional rules (evaluated agent-side). */
@@ -90,11 +93,38 @@ export interface Step<TResult = void> {
 export type BareStepFn<TResult = void> = (ctx: StepContext) => Promise<TResult>;
 /**
  * Union type for items accepted in a job's steps array.
- * Accepts both Step objects and bare async functions.
+ * Accepts Step objects, bare async functions, and concurrent parallel groups.
  */
-export type StepInput = Step<any> | BareStepFn<any>;
+export type StepInput = Step<any> | BareStepFn<any> | import('./parallel.js').ParallelGroup;
 /** Options for step() factory - simple form (just async function) */
 export type StepRunFn = (ctx: StepContext) => Promise<void>;
+/**
+ * Author-supplied retry policy for a step. A thrown attempt is re-run while
+ * attempts remain and `retryIf(err)` is true.
+ */
+export interface RetryConfig {
+    /** Total attempts incl. the first; `maxAttempts: 3` ⇒ up to 3 runs. Must be >= 1. */
+    maxAttempts: number;
+    /** Base delay between attempts, ms. Default 1000. */
+    delayMs?: number;
+    /** Delay growth. Default 'exponential'. */
+    backoff?: RetryBackoff;
+    /** Cap for exponential backoff, ms. Default 30000. */
+    maxDelayMs?: number;
+    /** Retry only when this returns true for the thrown error. Default: retry on any throw. */
+    retryIf?: (err: unknown) => boolean;
+}
+/**
+ * Retry policy with defaults filled in, carried on the built {@link Step}.
+ * `retryIf` rides along on the in-memory step (it is never serialized).
+ */
+export interface NormalizedRetry {
+    maxAttempts: number;
+    delayMs: number;
+    backoff: RetryBackoff;
+    maxDelayMs: number;
+    retryIf?: (err: unknown) => boolean;
+}
 /**
  * Facets shared by both the plain and the check variant of {@link StepOptions}.
  * These compose unchanged whether or not a step declares a `check` facet.
@@ -106,6 +136,8 @@ export interface StepOptionsBase {
     continueOnError?: boolean;
     /** Step-level timeout in milliseconds. Overrides the agent's default (30 minutes). */
     timeout?: number;
+    /** Retry policy: re-run a thrown step with backoff. `retry: N` ⇒ `{ maxAttempts: N }`. */
+    retry?: number | RetryConfig;
     /** Declarative cache: restored before this step, saved after on key miss. */
     cache?: import('./cache-types.js').CacheInput;
     /** Step-level conditional rules (evaluated agent-side). */
@@ -361,7 +393,21 @@ export type InitConfig = InitItem | InitItem[] | 'auto' | false;
 export interface RunsOnSelector {
     labels: string | RegExp | (string | RegExp)[];
     exclude?: string | RegExp | (string | RegExp)[];
+    /**
+     * How to pick the single agent when more than one matches.
+     *
+     * - `'deterministic'` (default) — sort matching candidates by `agentId` and
+     *   pick the lowest, so a run-once-on-one-host job (a migration, a dump) lands
+     *   on the same host across re-runs. Can hot-spot equivalent agents.
+     * - `'any'` — pick any available agent (load spread). Opt out of determinism
+     *   for jobs that don't need a stable host.
+     *
+     * The string / array shorthand `runsOn` forms imply `'deterministic'` too.
+     */
+    pick?: RunsOnPick;
 }
+/** Single-agent selection policy when multiple agents match a `runsOn` selector. */
+export type RunsOnPick = 'deterministic' | 'any';
 /**
  * Polymorphic runsOn type: string shorthand, array shorthand, or full selector object.
  * - `'kici:os:linux'` — single label shorthand (targets any linux agent)
@@ -391,6 +437,14 @@ export interface Job {
     readonly runsOnAll?: RunsOnAllInput;
     /** Failure policy for unreachable durable hosts when using `runsOnAll`. */
     readonly onUnreachable?: OnUnreachableMode;
+    /**
+     * Widen a `runsOnAll` fan-out to declared-but-un-agented hosts: each matching
+     * host that has no live agent gets a temporary init-runner brought up over SSH
+     * and its steps run on it (fresh-box bootstrap convergence). Already-live hosts
+     * run on their own agent. Default `false` (only live hosts run). Only
+     * meaningful alongside `runsOnAll`.
+     */
+    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 remainder. Default `false`. */
@@ -419,9 +473,16 @@ export interface Job {
     readonly container?: string | ContainerConfig;
     /** Deployment environment for this job. String for static, or a function of the normalized event envelope for dynamic (resolved at orchestrator two-phase eval). */
     readonly environment?: string | ((event: EventPayload) => string | Promise<string>);
+    /**
+     * Deployment environments for this job, in merge order (later entries override
+     * earlier on name collisions). Mutually exclusive with `environment`. Each entry
+     * is a static name or a function of the event (dynamic, resolved per element at
+     * two-phase eval).
+     */
+    readonly environments?: readonly (string | ((event: EventPayload) => string | Promise<string>))[];
     /** Environment variables. Static object or a function of the normalized event envelope (resolved at orchestrator two-phase eval). */
     readonly env?: Record<string, string> | ((event: EventPayload) => Record<string, string> | Promise<Record<string, string>>);
-    /** Concurrency group name. Defaults to environment name if not set. String or a function of the normalized event envelope. */
+    /** Concurrency group name. Defaults to the first bound environment's name if not set. String or a function of the normalized event envelope. */
     readonly concurrencyGroup?: string | ((event: EventPayload) => string | Promise<string>);
     /** Runs on cancellation. */
     readonly onCancel?: HookInput;
@@ -491,6 +552,13 @@ export interface JobOptions {
      * pinned child and waits. Only meaningful alongside `runsOnAll`.
      */
     onUnreachable?: OnUnreachableMode;
+    /**
+     * Widen a `runsOnAll` fan-out to declared-but-un-agented hosts: a matching host
+     * with no live agent gets a temporary init-runner brought up over SSH and its
+     * steps run on it (fresh-box bootstrap convergence); already-live hosts run on
+     * their own agent. Default `false`. Only meaningful alongside `runsOnAll`.
+     */
+    includeUninitialized?: boolean;
     /**
      * Fan-out concurrency width: the maximum number of fan-out children (matrix
      * combinations or `runsOnAll` hosts) that run at once. A sliding window —
@@ -553,9 +621,16 @@ export interface JobOptions {
     container?: string | ContainerConfig;
     /** Deployment environment for this job. String for static, or a function of the normalized event envelope for dynamic (resolved at orchestrator two-phase eval). */
     environment?: string | ((event: EventPayload) => string | Promise<string>);
+    /**
+     * Deployment environments for this job, in merge order (later entries override
+     * earlier on name collisions). Mutually exclusive with `environment`. Each entry
+     * is a static name or a function of the event (dynamic, resolved per element at
+     * two-phase eval).
+     */
+    environments?: (string | ((event: EventPayload) => string | Promise<string>))[];
     /** Environment variables. Static object or a function of the normalized event envelope (resolved at orchestrator two-phase eval). */
     env?: Record<string, string> | ((event: EventPayload) => Record<string, string> | Promise<Record<string, string>>);
-    /** Concurrency group name. Defaults to environment name if not set. String or a function of the normalized event envelope. */
+    /** Concurrency group name. Defaults to the first bound environment's name if not set. String or a function of the normalized event envelope. */
     concurrencyGroup?: string | ((event: EventPayload) => string | Promise<string>);
     /** Runs on cancellation. */
     onCancel?: HookInput;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "ci",
@@ -49,8 +49,8 @@
     "micromatch": "^4.0.8",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.22",
-    "@kici-dev/engine": "0.1.22"
+    "@kici-dev/core": "0.1.24",
+    "@kici-dev/engine": "0.1.24"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10"

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/sdk@0.1.22",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.22/fea982d5-064e-481c-8436-fbd07a92a3c8",
+  "name": "@kici-dev/sdk@0.1.24",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.24/5d1c0e54-b629-4883-86a2-1959def49eaa",
   "creationInfo": {
-    "created": "2026-06-24T06:03:05Z",
+    "created": "2026-06-28T16:24:27Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -146,9 +146,9 @@
       "homepage": "https://ericsmekens.github.io/jsep/tree/master/packages/regex#readme"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.22",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.24",
       "name": "@kici-dev/core",
-      "versionInfo": "0.1.22",
+      "versionInfo": "0.1.24",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -159,16 +159,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.22"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.24"
         }
       ],
       "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.22",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.24",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.22",
+      "versionInfo": "0.1.24",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -179,7 +179,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.22"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.24"
         }
       ],
       "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.",
@@ -188,7 +188,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/sdk",
-      "versionInfo": "0.1.22",
+      "versionInfo": "0.1.24",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -199,7 +199,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.22"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.24"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -1584,68 +1584,68 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.135.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-jose-6.2.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.4",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.24",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.22",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.24",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.22",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.24",
       "relationshipType": "DEPENDS_ON"
     },
     {