@kici-dev/sdk 0.1.21 → 0.1.23

package/dist/job.js

@@ -35,12 +35,14 @@ function job(nameOrOptions, maybeOptions) {
 	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,
@@ -66,7 +68,7 @@ function job(nameOrOptions, maybeOptions) {
 		resources: options.resources,
 		init: options.init,
 		...options.cache !== void 0 && { cache: options.cache },
-		...options.requireApproval !== void 0 && { requireApproval: options.requireApproval },
+		...options.approval !== void 0 && { approval: options.approval },
 		result: createJobOutputProxy(name)
 	};
 }

package/dist/needs-context.d.ts

@@ -1,31 +1,38 @@
 import type { OutputProxy, DynamicJobNeed } from './types.js';
+import type { ExecutionJobStatus } from '@kici-dev/engine';
 /**
- * Frozen snapshot of upstream outputs, captured once at first eval of a
- * result-aware dynamic generator and replayed unchanged on re-eval.
+ * Frozen snapshot of upstream outputs + statuses, captured once at first eval of
+ * a result-aware dynamic generator and replayed unchanged on re-eval.
  *
  * - `jobs` maps an upstream job name to its outputs record.
  * - `groups` maps a dynamic group name to its ordered member job names.
+ * - `statuses` maps an upstream job name to its terminal status. Absent entries
+ *   default to `success` (the only status that satisfies a default needs edge,
+ *   so an upstream resolved into the snapshot is success unless told otherwise).
  */
 export interface UpstreamSnapshot {
     jobs: Record<string, Record<string, unknown>>;
     groups: Record<string, string[]>;
+    statuses?: Record<string, ExecutionJobStatus>;
 }
 /** One entry in the array exposed for a `dynamicGroup(...)` need. */
 export interface GroupNeedEntry {
     name: string;
     result: OutputProxy<any>;
+    status: ExecutionJobStatus;
 }
-/** A single-job need exposes `{ result }`; a group need exposes an ordered array. */
+/** A single-job need exposes `{ result, status }`; a group need exposes an ordered array. */
 export type NeedEntry = {
     result: OutputProxy<any>;
+    status: ExecutionJobStatus;
 } | GroupNeedEntry[];
 /** The resolved `ctx.needs` map keyed by job name or group name. */
 export type NeedsContext = Record<string, NeedEntry>;
 /**
  * Resolve declared needs against a frozen snapshot into the `ctx.needs` map.
  *
- * - A single static/named-job need resolves to `{ result: <proxy over jobs[name]> }`.
- * - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result }`,
+ * - A single static/named-job need resolves to `{ result: <proxy over jobs[name]>, status }`.
+ * - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result, status }`,
  *   one entry per group member in the snapshot's deterministic eval order.
  */
 export declare function buildNeedsContext(snapshot: UpstreamSnapshot, declaredNeeds: ReadonlyArray<DynamicJobNeed>): NeedsContext;

package/dist/needs-context.js

@@ -19,11 +19,15 @@ function needKey(need) {
 		key: need.name
 	};
 }
+/** Read an upstream's terminal status from the snapshot, defaulting to success. */
+function statusFor(snapshot, name) {
+	return snapshot.statuses?.[name] ?? "success";
+}
 /**
 * Resolve declared needs against a frozen snapshot into the `ctx.needs` map.
 *
-* - A single static/named-job need resolves to `{ result: <proxy over jobs[name]> }`.
-* - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result }`,
+* - A single static/named-job need resolves to `{ result: <proxy over jobs[name]>, status }`.
+* - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result, status }`,
 *   one entry per group member in the snapshot's deterministic eval order.
 */
 function buildNeedsContext(snapshot, declaredNeeds) {
@@ -32,9 +36,13 @@ function buildNeedsContext(snapshot, declaredNeeds) {
 		const { kind, key } = needKey(need);
 		if (kind === "group") out[key] = (snapshot.groups[key] ?? []).map((name) => ({
 			name,
-			result: createSnapshotOutputProxy(name, snapshot.jobs[name])
+			result: createSnapshotOutputProxy(name, snapshot.jobs[name]),
+			status: statusFor(snapshot, name)
 		}));
-		else out[key] = { result: createSnapshotOutputProxy(key, snapshot.jobs[key]) };
+		else out[key] = {
+			result: createSnapshotOutputProxy(key, snapshot.jobs[key]),
+			status: statusFor(snapshot, key)
+		};
 	}
 	return out;
 }

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/step.js

@@ -1,7 +1,24 @@
 import "./chunk-BTugEXQM.js";
+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.
@@ -59,6 +76,8 @@ function step(nameOrRunOrOptions, runOrOptions) {
 		options = nameOrRunOrOptions;
 	}
 	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,
@@ -70,11 +89,12 @@ 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,
 		cleanup: options.cleanup,
-		...options.requireApproval !== void 0 && { requireApproval: options.requireApproval },
+		...options.approval !== void 0 && { approval: options.approval },
 		_sourceLocation,
 		result: createStepOutputProxy(name)
 	};

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/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';
 /**

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { z } from 'zod';
 import type { $ as Shell } from 'zx';
-import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode } from '@kici-dev/engine';
+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';
 import type { Rule } from './rules/types.js';
@@ -9,8 +10,15 @@ import type { HookInput } from './hooks/types.js';
 import type { KiciApi } from './api-types.js';
 import type { DynamicGroupRef } from './dynamic-group.js';
 import type { EventPayload } from './events/event-payloads.js';
-import type { RequireApproval } from './approval.js';
-export type { ResourceRequest, ResourceSpec, RunsOnAllInput, OnUnreachableMode, } from '@kici-dev/engine';
+import type { ApprovalConfig } from './approval.js';
+export type { ResourceRequest, ResourceSpec, RunsOnAllInput, OnUnreachableMode, NeedsWhen, } from '@kici-dev/engine';
+/**
+ * Author-facing run condition for a `needs` edge: keyword sugar
+ * (`'on-success'` | `'always'` | `'on-skip'` | `'on-failure'`) or a raw set of
+ * upstream terminal statuses. Resolved to a normalized status-set at compile
+ * time; the downstream runs when the upstream's terminal status is a member.
+ */
+export type NeedsWhenInput = NeedsWhen | ExecutionJobStatus[];
 /** Source location captured at a step() call site. */
 export interface SourceLocation {
     readonly file: string;
@@ -57,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). */
@@ -65,8 +75,8 @@ export interface Step<TResult = void> {
     readonly onCancel?: HookInput;
     /** Always runs after step (success, failure, or cancel). */
     readonly cleanup?: HookInput;
-    /** Pause for a manual human approval before this step runs. */
-    readonly requireApproval?: RequireApproval;
+    /** Pause for a manual human approval (before this step, or on drift). */
+    readonly approval?: ApprovalConfig;
     /** Internal: source location captured at step() call site. Not part of public API. */
     readonly _sourceLocation?: SourceLocation;
     /**
@@ -88,6 +98,33 @@ export type BareStepFn<TResult = void> = (ctx: StepContext) => Promise<TResult>;
 export type StepInput = Step<any> | BareStepFn<any>;
 /** 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.
@@ -99,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). */
@@ -107,8 +146,8 @@ export interface StepOptionsBase {
     onCancel?: HookInput;
     /** Always runs after step (success, failure, or cancel). */
     cleanup?: HookInput;
-    /** Pause for a manual human approval before this step runs. */
-    requireApproval?: RequireApproval;
+    /** Pause for a manual human approval (before this step, or on drift). */
+    approval?: ApprovalConfig;
 }
 /**
  * Plain step options: `run` takes only the context — the existing, fully
@@ -249,10 +288,10 @@ declare const DYNAMIC_JOB_NEEDS_TAG: unique symbol;
  */
 export type DynamicJobNeed = Job | string | DynamicGroupRef | {
     name: string;
-    ifFailed?: 'skip' | 'run';
+    when?: NeedsWhenInput;
 } | {
     group: string;
-    ifFailed?: 'skip' | 'run';
+    when?: NeedsWhenInput;
 };
 /**
  * Options-object form of {@link dynamicJob}: a result-aware generator that is
@@ -354,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)
@@ -384,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`. */
@@ -391,10 +452,10 @@ export interface Job {
     readonly steps: readonly StepInput[];
     readonly needs?: ReadonlyArray<Job | string | DynamicGroupRef | {
         name: string;
-        ifFailed: 'skip' | 'run';
+        when?: NeedsWhenInput;
     } | {
         group: string;
-        ifFailed: 'skip' | 'run';
+        when?: NeedsWhenInput;
     }>;
     /** Rules for conditional execution */
     readonly rules?: Rule[];
@@ -457,7 +518,7 @@ export interface Job {
     /** Declarative cache: restored before steps, saved after the job on key miss. */
     readonly cache?: import('./cache-types.js').CacheInput;
     /** Pause for a manual human approval before this job dispatches. */
-    readonly requireApproval?: RequireApproval;
+    readonly approval?: ApprovalConfig;
     /**
      * Type-safe proxy for accessing this job's outputs.
      * For multi-step jobs: jobRef.result.stepName.field
@@ -484,6 +545,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 —
@@ -510,10 +578,10 @@ export interface JobOptions {
     run?: (ctx: StepContext) => Promise<any>;
     needs?: Array<Job | string | DynamicGroupRef | {
         name: string;
-        ifFailed: 'skip' | 'run';
+        when?: NeedsWhenInput;
     } | {
         group: string;
-        ifFailed: 'skip' | 'run';
+        when?: NeedsWhenInput;
     }>;
     /** Rules that must pass for job to execute */
     rules?: Rule[];
@@ -591,7 +659,7 @@ export interface JobOptions {
     /** Declarative cache: restored before steps, saved after the job on key miss. */
     cache?: import('./cache-types.js').CacheInput;
     /** Pause for a manual human approval before this job dispatches. */
-    requireApproval?: RequireApproval;
+    approval?: ApprovalConfig;
 }
 /**
  * Private npm registry declaration. Tells the agent to authenticate against
@@ -670,7 +738,7 @@ export interface Workflow {
         readonly max?: number;
     };
     /** Pause for a manual human approval before the whole workflow dispatches. */
-    readonly requireApproval?: RequireApproval;
+    readonly approval?: ApprovalConfig;
 }
 /** Options for workflow() factory */
 export interface WorkflowOptions {
@@ -723,7 +791,7 @@ export interface WorkflowOptions {
         max?: number;
     };
     /** Pause for a manual human approval before the whole workflow dispatches. */
-    requireApproval?: RequireApproval;
+    approval?: ApprovalConfig;
 }
 export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig } from './triggers/types.js';
 export type { Rule, RuleContext, RuleCheckFn, RuleResult } from './rules/types.js';

package/dist/workflow.js

@@ -76,7 +76,7 @@ function workflow(name, options) {
 		onSuccess: options.onSuccess,
 		onFailure: options.onFailure,
 		concurrency: options.concurrency,
-		requireApproval: options.requireApproval
+		approval: options.approval
 	};
 }
 //#endregion

package/package.json

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