@kici-dev/agent 0.1.22 → 0.1.24

package/dist/bootstrap/api-intercept.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent-process interception of the bootstrap bring-up API methods.
+ *
+ * `ctx.kici.bootstrap.ensureInitRunner` / `preBootSend` are relayed from the
+ * workflow sandbox as `agent.api.request` IPC. The agent process intercepts
+ * those two methods HERE (rather than relaying them straight to the
+ * orchestrator) so the SSH transport — and the bring-up key / bootstrap token
+ * the orchestrator hands back — stay in the agent process, never reaching user
+ * workflow code. Every other method falls through to the orchestrator relay
+ * unchanged.
+ */
+import { type ApiTransport, type EnsureInitRunnerDeps } from './ensure-init-runner.js';
+/**
+ * Wrap the orchestrator API transport so the two bootstrap methods are handled
+ * in-process (SSH transport here; privileged resolve relayed to the
+ * orchestrator). `relay` is the raw orchestrator transport (the WS
+ * `sendApiRequest`).
+ */
+export declare function withBootstrapInterception(relay: ApiTransport, deps?: EnsureInitRunnerDeps): (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+//# sourceMappingURL=api-intercept.d.ts.map

package/dist/bootstrap/ensure-init-runner.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Agent-side init-runner bring-up.
+ *
+ * Runs in the AGENT process (never the workflow sandbox), so the bring-up SSH
+ * key and bootstrap token the orchestrator hands back never reach user
+ * workflow code. The flow:
+ *
+ *   1. Call the orchestrator's privileged `kici.ensureInitRunner` handler — it
+ *      gates on this agent's `kici:capability:ssh-transport` capability,
+ *      resolves the target's reach + SSH key, mints a single-use bootstrap
+ *      token, audits, and returns the material (or `{ broughtUp: false }` when
+ *      the target already has a live agent).
+ *   2. Over SSH (ephemeral key, never on disk): drop a launcher onto the target
+ *      that starts `kici-agent` with the bootstrap env (token + agent id +
+ *      orchestrator URL + labels), and start it detached.
+ *
+ * The init-runner then connects → `auth.request` (bootstrap token) →
+ * `agent.register` auto-enroll as a temporary `kici:init` agent.
+ */
+import { type SshDeps } from './ssh-exec.js';
+/** Transport that relays an API request to the orchestrator and awaits the result. */
+export type ApiTransport = (method: string, params: Record<string, unknown>) => Promise<unknown>;
+export interface EnsureInitRunnerDeps extends SshDeps {
+    /**
+     * The command used to start the init-runner on the target. Defaults to
+     * `kici-agent` (resolved on the target's PATH). Override for a rescue env
+     * that stages the binary at a fixed path.
+     */
+    agentCommand?: string;
+}
+/**
+ * Bring up a temporary init-runner on `targetAgentId`. Returns `{ broughtUp }`:
+ * false when the target already had a live agent (the orchestrator no-op'd),
+ * true when this call dropped + started the init-runner.
+ */
+export declare function ensureInitRunner(transport: ApiTransport, targetAgentId: string, deps?: EnsureInitRunnerDeps): Promise<{
+    broughtUp: boolean;
+}>;
+//# sourceMappingURL=ensure-init-runner.d.ts.map

package/dist/bootstrap/pre-boot-send.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent-side pre-boot input send (dropbear / initramfs unlock).
+ *
+ * Runs in the AGENT process. Asks the orchestrator's privileged
+ * `kici.preBootSend` handler to gate on the `kici:capability:ssh-transport`
+ * capability, resolve the input secret (e.g. a LUKS passphrase), and audit;
+ * then pipes the resolved input to the target's pre-boot SSH endpoint
+ * (default dropbear port 2222, forced `cryptroot-unlock`). The unlock drops
+ * the session as the box boots — success is the send completing, not the SSH
+ * exit code; the caller composes a host-alive wait to confirm boot.
+ */
+import { type SshDeps } from './ssh-exec.js';
+import type { ApiTransport } from './ensure-init-runner.js';
+export interface PreBootSendOpts {
+    inputSecret: string;
+    port?: number;
+    command?: string;
+}
+/**
+ * Ship a pre-boot input to the target's dropbear/initramfs SSH channel. The
+ * input plaintext is resolved server-side and never logged. Resolves once the
+ * send completes (the SSH session legitimately drops as the box boots).
+ */
+export declare function preBootSend(transport: ApiTransport, targetAgentId: string, opts: PreBootSendOpts, deps?: SshDeps): Promise<void>;
+//# sourceMappingURL=pre-boot-send.d.ts.map

package/dist/bootstrap/reach.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent-facing host reach metadata: how to SSH to a target for bootstrap.
+ *
+ * This is the subset the agent's SSH helper needs — the connection
+ * coordinates only. It deliberately does NOT carry the `sshKeySecret` ref:
+ * the orchestrator resolves the scoped secret server-side and hands the agent
+ * the already-resolved private key separately, so the secret ref never reaches
+ * the agent. `sshPort` is the OS-sshd port for bring-up; a pre-boot dropbear
+ * port is supplied per-call via `SshExecOpts.port`.
+ */
+export interface HostReach {
+    agentId: string;
+    address: string | null;
+    sshUser: string | null;
+    sshPort: number | null;
+}
+//# sourceMappingURL=reach.d.ts.map

package/dist/bootstrap/ssh-exec.d.ts

@@ -0,0 +1,58 @@
+import type { HostReach } from './reach.js';
+/** Host-key verification mode for the SSH connection. */
+export type SshHostKeyMode = 'accept-new' | 'strict';
+/** Result of an SSH invocation: exit code is reported, never thrown away. */
+export interface SshResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface SshExecOpts {
+    /** Piped to the remote command's stdin (e.g. a LUKS passphrase to cryptroot-unlock). */
+    stdin?: string;
+    /** Override the default SSH port (22). E.g. 2222 for a dropbear initramfs prompt. */
+    port?: number;
+    /**
+     * Host-key verification. Defaults to `accept-new` — the dropbear initramfs
+     * host key differs from the OS sshd key, so a pinned OS entry must not be
+     * reused. `strict` enforces a known_hosts match.
+     */
+    hostKeyMode?: SshHostKeyMode;
+}
+/**
+ * Low-level process spawn boundary, injectable so unit tests can assert the
+ * exact argv / env / stdin without running a real `ssh`. Mirrors the relevant
+ * subset of `child_process.spawn`'s contract.
+ */
+export interface SpawnFn {
+    (command: string, args: string[], opts: {
+        env: NodeJS.ProcessEnv;
+        stdin?: string;
+    }): Promise<SshResult>;
+}
+/** Default spawn boundary backed by `node:child_process.spawn`. */
+export declare const defaultSpawn: SpawnFn;
+/** Deps for the SSH helper — the spawn boundary is injectable for tests. */
+export interface SshDeps {
+    spawnFn?: SpawnFn;
+}
+/**
+ * Run a command on the target over SSH using an ephemeral, in-memory key.
+ *
+ * The key is loaded into a per-call ssh-agent (never written to disk) and the
+ * agent is killed in `finally`. The remote command's exit code / stdout /
+ * stderr are returned verbatim — a non-zero exit is reported, not swallowed
+ * (a pre-boot unlock legitimately drops the session, so the caller decides
+ * what a "success" looks like).
+ */
+export declare function sshExec(reach: HostReach, privateKey: string, command: string, opts?: SshExecOpts, deps?: SshDeps): Promise<SshResult>;
+/**
+ * Ship local bytes to a remote path over SSH (`ssh 'cat > path'`), using the
+ * same ephemeral-key discipline. Throws on a non-zero exit (a push must
+ * succeed end-to-end, unlike a pre-boot unlock).
+ */
+export declare function sshPush(reach: HostReach, privateKey: string, localBytes: string, remotePath: string, opts?: {
+    port?: number;
+    hostKeyMode?: SshHostKeyMode;
+}, deps?: SshDeps): Promise<void>;
+//# sourceMappingURL=ssh-exec.d.ts.map

package/dist/execution/cache/cache-phase.d.ts

@@ -10,20 +10,37 @@ export interface CachePhaseDeps {
     cache: CacheApi;
     /** Emit a runner→agent IPC message (the masked send). */
     sendIpc: (msg: RunnerToAgentMessage) => void;
-    /** Monotonic pseudo-step index allocator (continues after real steps + hooks). */
-    nextStepIndex: () => number;
+    /**
+     * Allocate the next cache pseudo-step index for `ownerStepIndex` (the real
+     * step the cache op belongs to, or {@link JOB_CACHE_OWNER} for job-level
+     * cache). Each owner draws from a disjoint block above every real-step and
+     * hook index, so two concurrently-running steps' cache pseudo-steps never
+     * collide.
+     */
+    nextStepIndex: (ownerStepIndex: number) => number;
 }
+/** Owner sentinel for job-level (not step-scoped) cache restore/save. */
+export declare const JOB_CACHE_OWNER = -1;
+/**
+ * Build the cache pseudo-step index allocator. Each owner (a real step index, or
+ * {@link JOB_CACHE_OWNER}) gets its own disjoint block of {@link CACHE_INDEX_BLOCK}
+ * indices, all above every real-step and hook index (`stepCount * 3 + 100`). A
+ * step's two-or-more cache pseudo-steps are a pure function of its own owner
+ * index, so concurrent children never collide. Under sequential execution the
+ * emitted indices stay above all real/hook indices exactly as before.
+ */
+export declare function createCacheStepIndexAllocator(stepCount: number): (ownerStepIndex: number) => number;
 /**
  * Restore every spec, surfacing each as a `cache:restore` pseudo-step. Returns
  * a map keyed by spec key recording whether the EXACT key hit (so the save
  * phase can skip a redundant save of an entry that already exists).
  */
-export declare function restoreCacheSpecs(specs: CacheSpec[], deps: CachePhaseDeps): Promise<Map<string, CacheRestoreOutcome>>;
+export declare function restoreCacheSpecs(specs: CacheSpec[], deps: CachePhaseDeps, ownerStepIndex: number): Promise<Map<string, CacheRestoreOutcome>>;
 /**
  * Save every spec whose EXACT key did not already hit on restore (immutable +
  * no redundant save), surfacing each as a `cache:save` pseudo-step. A spec
  * whose restore matched a different key via a `restoreKeys` prefix is still
  * saved under its exact key.
  */
-export declare function saveCacheSpecs(specs: CacheSpec[], restoreResults: Map<string, CacheRestoreOutcome>, deps: CachePhaseDeps): Promise<void>;
+export declare function saveCacheSpecs(specs: CacheSpec[], restoreResults: Map<string, CacheRestoreOutcome>, deps: CachePhaseDeps, ownerStepIndex: number): Promise<void>;
 //# sourceMappingURL=cache-phase.d.ts.map

package/dist/execution/cache/index.d.ts

@@ -5,5 +5,5 @@
  * `ctx.cache` API factory plus its transport interface.
  */
 export { createCacheApi, packCachePaths, extractCacheTarball, downloadAndExtractCache, resolveCachePath, type CacheTransport, type CacheRoots, } from './cache-engine.js';
-export { restoreCacheSpecs, saveCacheSpecs, type CachePhaseDeps, type CacheRestoreOutcome, } from './cache-phase.js';
+export { restoreCacheSpecs, saveCacheSpecs, createCacheStepIndexAllocator, JOB_CACHE_OWNER, type CachePhaseDeps, type CacheRestoreOutcome, } from './cache-phase.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/execution/init-runner.d.ts

@@ -5,7 +5,8 @@ import { type MatrixValues } from '@kici-dev/engine';
  * Only fields that were flagged as dynamic and successfully resolved are set.
  */
 export interface InitResult {
-    environmentName?: string;
+    /** Resolved bound-environment names, in merge order (one per `environments` element). */
+    environmentNames?: string[];
     env?: Record<string, string>;
     concurrencyGroup?: string;
     /**

package/dist/execution/job-runner.d.ts

@@ -215,6 +215,18 @@ export declare class JobRunner {
      * failure diagnostics, and send the terminal `job.status` message.
      */
     private reportExecutionResult;
+    /**
+     * Handle a bring-up job: bring up a temporary init-runner on a declared-but-
+     * un-agented host over SSH (fresh-box bootstrap convergence). The orchestrator
+     * dispatches this synthetic `__bringup__` job to an agent holding the
+     * `kici:capability:ssh-transport` capability; here we run the agent-side
+     * `ensureInitRunner` helper (the privileged resolve is relayed to the
+     * orchestrator, the SSH transport happens in this agent process — never
+     * reaching workflow code). No clone, no sandbox — the init-runner then
+     * connects under the target's agent id and the orchestrator's pinned-hold
+     * drains the target's bootstrap steps onto it.
+     */
+    private handleBringupJob;
     /**
      * Handle a build-only job.
      *

package/dist/execution/rule-evaluator.d.ts

@@ -1,11 +1,13 @@
-import type { RuleContext } from '@kici-dev/sdk';
+import type { RuleContext, FanoutPosition } from '@kici-dev/sdk';
 /**
  * Create RuleContext for agent-side rule evaluation.
  *
  * @param event - Event payload from the dispatch message
  * @param changedFiles - List of files changed in this event
  * @param env - Merged environment variables
+ * @param dispatchInputs - Operator dispatch inputs (`ctx.dispatchInputs`)
+ * @param fanout - Fan-out position (`ctx.fanout`); undefined on a non-fan-out job
  */
-export declare function createRuleContext(event: Record<string, unknown>, changedFiles?: string[], env?: Record<string, string | undefined>): RuleContext;
+export declare function createRuleContext(event: Record<string, unknown>, changedFiles?: string[], env?: Record<string, string | undefined>, dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>, fanout?: FanoutPosition): RuleContext;
 export { evaluateRules, type RuleEvaluationResult } from '@kici-dev/sdk';
 //# sourceMappingURL=rule-evaluator.d.ts.map

package/dist/execution/sandbox/capture-context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Run `fn` with `stepIndex` as the active console-capture attribution for the
+ * duration of its async execution (including everything it awaits).
+ */
+export declare function runInStepCapture<T>(stepIndex: number, fn: () => Promise<T>): Promise<T>;
+/**
+ * The step index whose run is currently on the async stack, or `-1` when no
+ * capture scope is active (workflow-level / between-steps output).
+ */
+export declare function currentCaptureStepIndex(): number;
+//# sourceMappingURL=capture-context.d.ts.map

package/dist/execution/sandbox/ipc-protocol.d.ts

@@ -24,13 +24,27 @@ interface StepStartMessage {
     stepName: string;
     /** Distinguishes regular steps from hook executions (e.g., 'hook:onCancel', 'hook:cleanup'). Defaults to 'step'. */
     step_type?: string;
+    /**
+     * Initial state for the step. Defaults to `running`. A parallel-group child
+     * queued behind `maxParallel` is announced as `pending` before it acquires a
+     * slot; it later emits a second `step.start` with `running` when it launches.
+     */
+    state?: 'running' | 'pending';
+    /** Step concurrency role; absent means an ordinary sequential step. */
+    concurrencyKind?: string;
+    /** Parallel-group correlation id shared by a group's children (e.g. `g0`). */
+    groupId?: string;
 }
-/** A step has completed (success, failure, or a check-mode skip). */
+/** A step has completed (success, failure, check-mode skip, or fail-fast cancel). */
 interface StepCompleteMessage {
     type: 'step.complete';
     stepIndex: number;
-    status: 'success' | 'failed' | 'skipped';
+    status: 'success' | 'failed' | 'skipped' | 'cancelled';
     durationMs: number;
+    /** Step concurrency role; absent means an ordinary sequential step. */
+    concurrencyKind?: string;
+    /** Parallel-group correlation id shared by a group's children (e.g. `g0`). */
+    groupId?: string;
     error?: {
         message: string;
         exitCode?: number;
@@ -410,6 +424,20 @@ export interface JobExecutionRequest {
         platform?: string;
         arch?: string;
     };
+    /**
+     * Operator-supplied, validated + coerced + defaulted workflow-dispatch inputs
+     * (from `kici run --input`), exposed to steps + rules as `ctx.dispatchInputs`.
+     * Absent for webhook runs.
+     */
+    dispatchInputs?: Record<string, unknown>;
+    /**
+     * For a fan-out child (`runsOnAll` host or matrix combination): the 0-based
+     * deterministic position in the fan-out, assembled into `ctx.fanout`. Absent
+     * for non-fan-out jobs.
+     */
+    fanoutIndex?: number;
+    /** For a fan-out child: the number of children in this fan-out. */
+    fanoutTotal?: number;
     /** Secrets to merge into step environment (highest precedence). */
     secrets?: Record<string, string>;
     /** Namespaced secrets by context name for ctx.secrets['context-name'].KEY access. */
@@ -440,7 +468,7 @@ export interface JobExecutionRequest {
     provider?: string;
     /** Whether to checkout the repo (default: true). */
     checkout?: boolean;
-    /** Whether this job is part of a test run triggered by `kici test`. */
+    /** Whether this job is part of a developer-initiated run triggered by `kici run`. */
     isTestRun?: boolean;
     /**
      * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`).

package/dist/execution/sandbox/parallel-scheduler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Concurrency-aware scheduler for `parallel()` step groups.
+ *
+ * A parallel group's children each run as their own observable step (own logs,
+ * status, timing, retry, cache, hooks — all task-scoped by the Phase 0 per-task
+ * isolation) through the same `runStepIteration` machinery the sequential loop
+ * uses. Children launch behind a `maxParallel` window (queued children report
+ * `pending`); the group joins at a barrier. On the first non-`continueOnError`
+ * child failure when `failFast`, every in-flight sibling's per-task abort
+ * controller is fired so its step race rejects and it is reported `cancelled`
+ * (which is NOT a failure).
+ */
+import { type StepLoopOptions, type StepNode } from './step-loop.js';
+import type { SandboxStepResult } from './types.js';
+type ParallelNode = Extract<StepNode, {
+    kind: 'parallel';
+}>;
+/** Outcome of running one parallel group. */
+export interface ParallelGroupOutcome {
+    /** True when at least one non-`continueOnError` child failed. */
+    failed: boolean;
+    /** Name of the first failing child (drives the job failure reason). */
+    failedStepName?: string;
+    /** Per-child results, in child array order. */
+    results: SandboxStepResult[];
+}
+/**
+ * Run a parallel group: launch children with a bounded-concurrency window, join
+ * at a barrier, and fail-fast-cancel in-flight siblings on the first hard
+ * failure.
+ */
+export declare function runParallelGroup(node: ParallelNode, opts: StepLoopOptions): Promise<ParallelGroupOutcome>;
+export {};
+//# sourceMappingURL=parallel-scheduler.d.ts.map

package/dist/execution/sandbox/step-loop.d.ts

@@ -5,11 +5,41 @@
  * Extracted for testability: the workflow-runner's main() handles IPC, clone, deps,
  * module loading, and calls this loop for step execution with hooks.
  */
-import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord } from '@kici-dev/sdk';
+import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord, FanoutPosition } from '@kici-dev/sdk';
 import { CheckMode } from '@kici-dev/engine';
 import type { RunnerToAgentMessage } from './ipc-protocol.js';
 import type { SandboxStepResult } from './types.js';
 import { type CachePhaseDeps } from '../cache/index.js';
+/**
+ * Thrown inside the step race when a step's own per-task abort controller fires
+ * (parallel fail-fast cancels an in-flight sibling). Distinguished from a
+ * timeout/job-deadline reject so the loop reports the step as `cancelled`
+ * (which is NOT a failure) rather than `failed`.
+ */
+export declare class StepCancelledError extends Error {
+    readonly name = "StepCancelledError";
+    constructor(stepName: string);
+}
+/**
+ * A node in the concurrency-aware step walk. A `sequential` node is one ordinary
+ * step; a `parallel` node is a `parallel()` group whose children each carry their
+ * own flat `stepIndex` (the group wrapper consumes no index).
+ */
+export type StepNode = {
+    kind: 'sequential';
+    step: Step;
+    stepIndex: number;
+} | {
+    kind: 'parallel';
+    groupId: string;
+    name: string;
+    failFast: boolean;
+    maxParallel?: number;
+    children: {
+        step: Step;
+        stepIndex: number;
+    }[];
+};
 /** Job-level hooks passed to the step loop. */
 export interface JobHooks {
     beforeStep?: HookInput;
@@ -21,7 +51,32 @@ export interface JobHooks {
 }
 /** Options for the step execution loop. */
 export interface StepLoopOptions {
+    /**
+     * Flat list of every executable step (sequential steps + parallel-group
+     * children inlined in flat-stepIndex order). `steps.length` is the flat step
+     * count used to derive hook pseudo-indices. The structural walk order (which
+     * entries are grouped) is carried separately by `stepNodes`.
+     */
     steps: Step[];
+    /**
+     * Structural walk order: sequential steps and parallel groups in array order.
+     * When present, the loop walks these nodes (dispatching parallel groups to the
+     * concurrency-aware scheduler); when absent, it walks `steps` sequentially with
+     * the array index as the stepIndex (unit-harness back-compat).
+     */
+    stepNodes?: StepNode[];
+    /**
+     * Abort the per-task controller for `stepIndex` (parallel fail-fast). Wired to
+     * the workflow-runner's `stepAbortControllers` map so an aborted sibling's
+     * `ctx.signal` fires and its step race rejects with {@link StepCancelledError}.
+     */
+    abortStep?: (stepIndex: number) => void;
+    /**
+     * Returns the per-task abort signal for `stepIndex` (the same controller
+     * `abortStep` triggers). The step race watches it so a fail-fast abort
+     * interrupts an in-flight step even if its body ignores `ctx.signal`.
+     */
+    getStepAbortSignal?: (stepIndex: number) => AbortSignal | undefined;
     /**
      * Run mode for idempotent steps. `apply` (default) converges; `check` /
      * `check-fail-on-drift` preview drift and never invoke a checked step's apply.
@@ -29,6 +84,12 @@ export interface StepLoopOptions {
     checkMode?: CheckMode;
     /** Factory that creates a StepContext for a given step index and name. */
     createStepContext: (stepIndex: number, stepName: string) => StepContext;
+    /**
+     * Run `fn` inside the step's console-capture scope so any console output it
+     * (or its hooks) produces attributes to `stepIndex`. Defaults to calling `fn`
+     * directly when absent (unit harnesses without capture wiring).
+     */
+    runWithStepCapture?: <T>(stepIndex: number, fn: () => Promise<T>) => Promise<T>;
     sendIpc: (msg: RunnerToAgentMessage) => void;
     defaultTimeoutMs: number;
     outputsMap: OutputsMap;
@@ -36,6 +97,10 @@ export interface StepLoopOptions {
     event: Record<string, unknown>;
     /** Environment variables for rule context. */
     env: Record<string, string | undefined>;
+    /** Operator dispatch inputs for the rule context (`ctx.dispatchInputs`). */
+    dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>;
+    /** Fan-out position for the rule context (`ctx.fanout`); undefined on a non-fan-out job. */
+    fanout?: FanoutPosition;
     /** Job-level hooks. */
     jobHooks?: JobHooks;
     /**
@@ -59,36 +124,38 @@ export interface StepLoopOptions {
     /** Job start time (epoch ms) for outcome metadata duration. */
     startTime?: number;
     /**
-     * Returns the secret key names accessed by the most recently created step context.
-     * Called after each step completes to include in step.complete IPC messages.
+     * Returns the secret key names accessed by the step context created for
+     * `stepIndex`. Called after each step completes to include in step.complete
+     * IPC messages.
      */
-    getSecretsAccessLog?: () => string[];
+    getSecretsAccessLog?: (stepIndex: number) => string[];
     /**
-     * Tear down per-step state created by the most recent `createStepContext`
-     * call. Invoked from the step-loop's `finally` after the step completes
+     * Tear down per-step state created by the `createStepContext` call for
+     * `stepIndex`. Invoked from the step-loop's `finally` after the step completes
      * (success, failure, rule-skip, or timeout) so resources like the
      * `ctx.secrets.mountFile` tmpdir get removed even on the failure paths.
      * Never throws -- errors are logged by the wired implementation.
      */
-    disposeStepResources?: () => Promise<void>;
+    disposeStepResources?: (stepIndex: number) => Promise<void>;
     /**
-     * Returns the IPC `step.secret_mount` records collected by the most
-     * recently created step context. Emitted on step completion so the
-     * orchestrator can persist the audit trail alongside `secretsAccessed`.
+     * Returns the IPC `step.secret_mount` records collected by the step context
+     * created for `stepIndex`. Emitted on step completion so the orchestrator can
+     * persist the audit trail alongside `secretsAccessed`.
      */
-    getSecretMountRecords?: () => StepSecretMountRecord[];
+    getSecretMountRecords?: (stepIndex: number) => StepSecretMountRecord[];
     /**
      * Before a step's run function executes, point KICI_ENV / KICI_PATH at fresh
-     * temp files for this step. Invoked once per executed step (NOT for rule-skipped
+     * temp files for this step (keyed by `stepIndex` so concurrent steps never
+     * share a delta file). Invoked once per executed step (NOT for rule-skipped
      * steps). The workflow-runner owns the file lifecycle.
      */
-    beforeStepEnvFiles?: () => Promise<void>;
+    beforeStepEnvFiles?: (stepIndex: number) => Promise<void>;
     /**
-     * After a step's run function completes (success OR failure), read the
-     * KICI_ENV / KICI_PATH files, apply the delta via applyEnvDelta, and truncate
-     * them for the next step. Never throws -- errors are logged by the wired impl.
+     * After a step's run function completes (success OR failure), read this
+     * step's KICI_ENV / KICI_PATH files, apply the delta via applyEnvDelta, and
+     * release them. Never throws -- errors are logged by the wired impl.
      */
-    afterStepApplyEnvFiles?: () => Promise<void>;
+    afterStepApplyEnvFiles?: (stepIndex: number) => Promise<void>;
     /**
      * Block an `approval` step (`when: 'always'`) pending an orchestrator-side
      * approval hold. The runner sends the normalized requirement and awaits the
@@ -141,6 +208,18 @@ interface StepLoopResult {
     stepResults: SandboxStepResult[];
     failureReason?: string;
 }
+/**
+ * Per-step iteration outcome returned by `runStepIteration`.
+ */
+export interface StepIterationOutcome {
+    /** The result to append to the running stepResults list. */
+    result: SandboxStepResult;
+    /** When true, the loop must break (failed step without continueOnError). */
+    shouldBreak: boolean;
+    /** Set when the step failed; carried into completion-hook outcome metadata. */
+    failedStepName?: string;
+}
+export declare function runStepIteration(step: Step, stepIndex: number, opts: StepLoopOptions): Promise<StepIterationOutcome>;
 /**
  * Execute the step loop with hook integration and step-level rule evaluation.
  *

package/dist/execution/sandbox/step-task-registry.d.ts

@@ -0,0 +1,26 @@
+import type { StepSecretMountRecord, TrackedStepSecrets } from '@kici-dev/sdk';
+/** Per-step secrets handle + its teardown closure, keyed by step index. */
+export interface StepTaskSlot {
+    secrets: TrackedStepSecrets;
+    dispose: () => Promise<void>;
+}
+/**
+ * Per-task replacement for the runner's former `currentStepSecrets` /
+ * `currentStepDispose` single-slots.
+ *
+ * The runner used to remember only the *most recent* step's secrets handle and
+ * dispose closure; the access-log / mount-record / dispose reader callbacks read
+ * that single slot. Under sequential execution that is correct (one step at a
+ * time), but two concurrently-running steps would clobber each other's
+ * secrets-audit trail. Keying every slot by the step's index keeps each step's
+ * audit trail and teardown isolated — sequential behavior is identical, Phase 1
+ * concurrency is correct.
+ */
+export declare class StepTaskRegistry {
+    #private;
+    set(stepIndex: number, slot: StepTaskSlot): void;
+    getAccessLog(stepIndex: number): string[];
+    getMountRecords(stepIndex: number): StepSecretMountRecord[];
+    dispose(stepIndex: number): Promise<void>;
+}
+//# sourceMappingURL=step-task-registry.d.ts.map

package/dist/execution/sandbox/types.d.ts

@@ -150,8 +150,8 @@ export interface SandboxStepResult {
     name: string;
     /** Zero-based index of the step within the job. */
     stepIndex: number;
-    /** Step execution status. */
-    status: 'success' | 'failed' | 'skipped';
+    /** Step execution status. `cancelled` = a parallel sibling fail-fast cancel. */
+    status: 'success' | 'failed' | 'skipped' | 'cancelled';
     /** Step duration in milliseconds. */
     durationMs: number;
     /** Error details when status is 'failed'. */

package/dist/execution/sandbox/workflow-runner.d.ts

@@ -15,7 +15,7 @@
  */
 import { ExecutionJobStatus } from '@kici-dev/engine';
 import type { StepContext } from '@kici-dev/sdk';
-import type { NeedsContext } from '@kici-dev/sdk';
+import type { NeedsContext, FanoutPosition } from '@kici-dev/sdk';
 import type { OutputsMap, StepRefMap, TrackedStepSecrets } from '@kici-dev/sdk';
 import type { RunnerToAgentMessage, JobExecutionRequest } from './ipc-protocol.js';
 import { LogMasker } from './log-masker.js';
@@ -35,7 +35,34 @@ export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[]
  * NOT serialized across the process boundary. This means zx $ runs natively
  * inside this process with full shell access.
  */
-export declare function createSandboxStepContext(workDir: string, stepIndex: number, stepName: string, request: JobExecutionRequest, maskedSendFn: (msg: RunnerToAgentMessage) => void, outputsMap: OutputsMap, refMap: StepRefMap, operatorSecretKeys: Set<string>, secretOutputs: Map<string, string>, jobOutputsMap: OutputsMap, secrets: TrackedStepSecrets, masker: LogMasker): StepContext;
+export declare function createSandboxStepContext(workDir: string, stepIndex: number, stepName: string, request: JobExecutionRequest, maskedSendFn: (msg: RunnerToAgentMessage) => void, outputsMap: OutputsMap, refMap: StepRefMap, operatorSecretKeys: Set<string>, secretOutputs: Map<string, string>, jobOutputsMap: OutputsMap, secrets: TrackedStepSecrets, masker: LogMasker, signal: AbortSignal): StepContext;
+/**
+ * Derive the fan-out position (`ctx.fanout`) from a dispatch request. Returns
+ * `undefined` for a non-fan-out job (no `fanoutTotal`), so `ctx.fanout` is only
+ * set for `runsOnAll` host children and matrix combinations.
+ */
+export declare function deriveFanout(request: JobExecutionRequest): FanoutPosition | undefined;
 /** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
 export declare function rawPayloadFromEvent(event: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * Build the step loop's KICI_ENV/KICI_PATH callbacks with a per-step delta-file
+ * pair (keyed by step index). `beforeStepEnvFiles(stepIndex)` lazily creates the
+ * step's pair and points the runner's process.env at it (each step's zx $
+ * snapshots process.env at context creation, which happens AFTER this
+ * before-hook, so the shell sees them; the pre-fork env allowlist does not
+ * re-filter runtime-set vars). `afterStepApplyEnvFiles(stepIndex)` applies that
+ * step's delta and releases the pair.
+ *
+ * Env-isolation contract: under sequential execution this is identical to a
+ * single shared pair truncated between steps — each step still sees only its own
+ * delta. The pair is now per-step so two concurrently-running steps cannot
+ * corrupt each other's delta file. `process.env.KICI_ENV` / `process.env.KICI_PATH`
+ * remain process-global, so Phase 1 forbids `setEnv` / `addPath` / `$KICI_ENV`
+ * writes inside `parallel()` children (compile-time validation); Phase 0 only
+ * makes the file pair per-task.
+ */
+export declare function buildStepEnvFileHooks(operatorSecretKeys: Set<string>, maskedSend: (msg: RunnerToAgentMessage) => void): {
+    beforeStepEnvFiles: (stepIndex: number) => Promise<void>;
+    afterStepApplyEnvFiles: (stepIndex: number) => Promise<void>;
+};
 //# sourceMappingURL=workflow-runner.d.ts.map