@kici-dev/agent 0.1.22 → 0.1.24

package/dist/workflow-runner.js

@@ -7,10 +7,10 @@ import os, { homedir, tmpdir } from "node:os";
 import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { $ } from "zx";
 import { createLogger, deriveSharedSecret, initZx, normalizeLineEndings, sha256, sha256File, toErrorMessage } from "@kici-dev/shared";
-import { CacheOutcome, CacheStepType, CheckMode, CheckStepOutcome, ExecutionJobStatus, ExecutionStepStatus, TimeoutReason } from "@kici-dev/engine";
-import { buildKiciApi, buildNeedsContext, createStepSecrets, evaluateRules, isDynamicJobFn, normalizeApproval, normalizeCacheSpecs, provenanceSubjectIsPath, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
+import { CacheOutcome, CacheStepType, CheckMode, CheckStepOutcome, ExecutionJobStatus, ExecutionStepStatus, StepConcurrencyKind, TimeoutReason } from "@kici-dev/engine";
+import { buildKiciApi, buildNeedsContext, createStepSecrets, evaluateRules, isDynamicJobFn, isParallelGroup, normalizeApproval, normalizeCacheSpecs, provenanceSubjectIsPath, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
 import { OIDC_TOKEN_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/oidc-token-relay";
-import { sha256File as sha256File$1 } from "@kici-dev/core";
+import { computeBackoffDelay, sha256File as sha256File$1 } from "@kici-dev/core";
 import { calculateJwkThumbprint, decodeJwt, exportJWK, generateKeyPair } from "jose";
 import { IN_TOTO_PAYLOAD_TYPE, KICI_PROVENANCE_AUDIENCE, KICI_PROVENANCE_BUNDLE_MEDIA_TYPE } from "@kici-dev/engine/provenance/bundle";
 import { IN_TOTO_STATEMENT_TYPE, KICI_WORKFLOW_BUILD_TYPE, SLSA_PROVENANCE_PREDICATE_TYPE } from "@kici-dev/engine/provenance/schema";
@@ -23,6 +23,7 @@ import { createGunzip } from "node:zlib";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { c, x } from "tar";
 import { runIdempotentStep } from "@kici-dev/core/idempotency";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { PNPM_IGNORE_BUILD_GATE_ARG, PackageManager, YarnFlavor, detectPackageManagerFromManifests, detectYarnFlavor } from "@kici-dev/shared/package-manager";
@@ -689,29 +690,34 @@ function createCacheApi(workDir, transport, roots) {
 		}
 	};
 }
-//#endregion
-//#region src/execution/cache/cache-phase.ts
-/**
-* Declarative cache phase (sandbox-side).
-*
-* Restores a list of {@link CacheSpec} before the work that depends on them
-* (a job before its steps, or a step before its `run`) and saves them after
-* (on an exact-key miss). Each operation surfaces as a `cache:restore` /
-* `cache:save` pseudo-step — a `step.start` + `step.complete` IPC pair whose
-* `step_type` comes from {@link CacheStepType} — exactly mirroring how hooks
-* render as `hook:*` pseudo-steps. The `step.complete` `data` carries the
-* {@link CacheOutcome} (plus key / matchedKey / bytes) so the agent can feed a
-* `run.event` and the dashboard can render hit/miss/saved inline.
-*/
+/** Block size reserved per owner for cache pseudo-step indices. */
+const CACHE_INDEX_BLOCK = 1e3;
+/**
+* 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.
+*/
+function createCacheStepIndexAllocator(stepCount) {
+	const cacheBase = stepCount * 3 + 100;
+	const counters = /* @__PURE__ */ new Map();
+	return (ownerStepIndex) => {
+		const n = counters.get(ownerStepIndex) ?? 0;
+		counters.set(ownerStepIndex, n + 1);
+		return cacheBase + (ownerStepIndex + 1) * CACHE_INDEX_BLOCK + n;
+	};
+}
 /**
 * 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).
 */
-async function restoreCacheSpecs(specs, deps) {
+async function restoreCacheSpecs(specs, deps, ownerStepIndex) {
 	const results = /* @__PURE__ */ new Map();
 	for (const spec of specs) {
-		const stepIndex = deps.nextStepIndex();
+		const stepIndex = deps.nextStepIndex(ownerStepIndex);
 		deps.sendIpc({
 			type: "step.start",
 			stepIndex,
@@ -761,10 +767,10 @@ async function restoreCacheSpecs(specs, deps) {
 * whose restore matched a different key via a `restoreKeys` prefix is still
 * saved under its exact key.
 */
-async function saveCacheSpecs(specs, restoreResults, deps) {
+async function saveCacheSpecs(specs, restoreResults, deps, ownerStepIndex) {
 	for (const spec of specs) {
 		if (restoreResults.get(spec.key)?.matchedKey === spec.key) continue;
-		const stepIndex = deps.nextStepIndex();
+		const stepIndex = deps.nextStepIndex(ownerStepIndex);
 		deps.sendIpc({
 			type: "step.start",
 			stepIndex,
@@ -1106,17 +1112,160 @@ initZx();
 * @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
 */
-function createRuleContext(event, changedFiles = [], env = {}) {
+function createRuleContext(event, changedFiles = [], env = {}, dispatchInputs = {}, fanout) {
 	return {
 		event,
 		changedFiles,
 		env,
+		dispatchInputs,
+		...fanout && { fanout },
 		$
 	};
 }
 //#endregion
+//#region src/execution/sandbox/parallel-scheduler.ts
+/**
+* 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).
+*/
+/**
+* Wrap `sendIpc` so a child's own `step.start` / `step.complete` messages carry
+* the parallel-child concurrency role + the group id. Cache/secret pseudo-step
+* messages (different stepIndex) pass through untouched.
+*/
+function stampChildSend(sendIpc, childStepIndex, groupId) {
+	return (msg) => {
+		if ((msg.type === "step.start" || msg.type === "step.complete") && msg.stepIndex === childStepIndex) {
+			sendIpc({
+				...msg,
+				concurrencyKind: StepConcurrencyKind.enum["parallel-child"],
+				groupId
+			});
+			return;
+		}
+		sendIpc(msg);
+	};
+}
+/** Announce a child queued behind the `maxParallel` window as `pending`. */
+function emitPending(opts, child, groupId) {
+	opts.sendIpc({
+		type: "step.start",
+		stepIndex: child.stepIndex,
+		stepName: child.step.name,
+		state: "pending",
+		concurrencyKind: StepConcurrencyKind.enum["parallel-child"],
+		groupId
+	});
+}
+/** Mark a child that never launched (fail-fast already tripped) as `cancelled`. */
+function emitCancelledSkip(opts, child, groupId) {
+	opts.sendIpc({
+		type: "step.start",
+		stepIndex: child.stepIndex,
+		stepName: child.step.name,
+		concurrencyKind: StepConcurrencyKind.enum["parallel-child"],
+		groupId
+	});
+	opts.sendIpc({
+		type: "step.complete",
+		stepIndex: child.stepIndex,
+		status: "cancelled",
+		durationMs: 0,
+		concurrencyKind: StepConcurrencyKind.enum["parallel-child"],
+		groupId
+	});
+	return {
+		name: child.step.name,
+		stepIndex: child.stepIndex,
+		status: "cancelled",
+		durationMs: 0
+	};
+}
+/**
+* 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.
+*/
+async function runParallelGroup(node, opts) {
+	const { children, failFast, groupId } = node;
+	const limit = node.maxParallel && node.maxParallel > 0 ? node.maxParallel : children.length;
+	const results = new Array(children.length);
+	const inFlight = /* @__PURE__ */ new Set();
+	let failed = false;
+	let failedStepName;
+	for (let i = limit; i < children.length; i++) emitPending(opts, children[i], groupId);
+	let cursor = 0;
+	const worker = async () => {
+		for (;;) {
+			const idx = cursor++;
+			if (idx >= children.length) return;
+			const child = children[idx];
+			if (failFast && failed) {
+				results[idx] = emitCancelledSkip(opts, child, groupId);
+				continue;
+			}
+			const childOpts = {
+				...opts,
+				sendIpc: stampChildSend(opts.sendIpc, child.stepIndex, groupId)
+			};
+			inFlight.add(child.stepIndex);
+			try {
+				const outcome = await runStepIteration(child.step, child.stepIndex, childOpts);
+				results[idx] = outcome.result;
+				if (outcome.shouldBreak) {
+					if (!failed) {
+						failed = true;
+						failedStepName = outcome.failedStepName ?? child.step.name;
+					}
+					if (failFast) {
+						for (const sibling of inFlight) if (sibling !== child.stepIndex) opts.abortStep?.(sibling);
+					}
+				}
+			} finally {
+				inFlight.delete(child.stepIndex);
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, children.length) }, () => worker()));
+	return {
+		failed,
+		failedStepName,
+		results
+	};
+}
+//#endregion
 //#region src/execution/sandbox/step-loop.ts
+/**
+* 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`.
+*/
+var StepCancelledError = class StepCancelledError extends Error {
+	name = "StepCancelledError";
+	constructor(stepName) {
+		super(`Step '${stepName}' was cancelled by parallel fail-fast`);
+		Object.setPrototypeOf(this, StepCancelledError.prototype);
+	}
+};
+/**
+* Resolve the capture-scope wrapper from options, falling back to a direct call
+* when no capture wiring is present (unit harnesses).
+*/
+function captureWrap(opts) {
+	return opts.runWithStepCapture ?? ((_stepIndex, fn) => fn());
+}
 /** Result of a rejected drift gate: the run was declined by a reviewer. */
 var DriftGateRejectedError = class extends Error {
 	constructor(reason) {
@@ -1211,6 +1360,7 @@ async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, output
 	const startTime = Date.now();
 	const abortController = new AbortController();
 	const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
+	const stepAbortSignal = opts.getStepAbortSignal?.(stepIndex);
 	try {
 		const phase = await Promise.race([
 			runStepWithCheckMode(step, stepIndex, ctx, checkMode, sendFn, opts),
@@ -1228,14 +1378,22 @@ async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, output
 				jobDeadlineSignal.addEventListener("abort", () => {
 					reject(/* @__PURE__ */ new Error(`Step '${step.name}' aborted: job timeout exceeded`));
 				});
+			}),
+			new Promise((_, reject) => {
+				if (!stepAbortSignal) return;
+				if (stepAbortSignal.aborted) {
+					reject(new StepCancelledError(step.name));
+					return;
+				}
+				stepAbortSignal.addEventListener("abort", () => reject(new StepCancelledError(step.name)));
 			})
 		]);
 		clearTimeout(timeoutId);
 		const durationMs = Date.now() - startTime;
 		const outputsPayload = phase.outputs != null ? phase.outputs : void 0;
 		if (outputsPayload) outputsMap.set(step.name, outputsPayload);
-		const secretsAccessed = getSecretsAccessLog?.();
-		emitSecretMountEvents(getSecretMountRecords?.(), stepIndex, sendFn);
+		const secretsAccessed = getSecretsAccessLog?.(stepIndex);
+		emitSecretMountEvents(getSecretMountRecords?.(stepIndex), stepIndex, sendFn);
 		const stepStatus = phase.status === "skipped" ? ExecutionStepStatus.enum.skipped : ExecutionStepStatus.enum.success;
 		sendFn({
 			type: "step.complete",
@@ -1259,10 +1417,27 @@ async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, output
 		clearTimeout(timeoutId);
 		const durationMs = Date.now() - startTime;
 		const error = e instanceof Error ? e : new Error(String(e));
+		if (e instanceof StepCancelledError) {
+			const secretsAccessed = getSecretsAccessLog?.(stepIndex);
+			emitSecretMountEvents(getSecretMountRecords?.(stepIndex), stepIndex, sendFn);
+			sendFn({
+				type: "step.complete",
+				stepIndex,
+				status: ExecutionStepStatus.enum.cancelled,
+				durationMs,
+				...secretsAccessed !== void 0 && { secretsAccessed }
+			});
+			return {
+				name: step.name,
+				stepIndex,
+				status: ExecutionStepStatus.enum.cancelled,
+				durationMs
+			};
+		}
 		const exitCode = extractExitCode(e);
 		const signal = extractSignal(e);
-		const secretsAccessed = getSecretsAccessLog?.();
-		emitSecretMountEvents(getSecretMountRecords?.(), stepIndex, sendFn);
+		const secretsAccessed = getSecretsAccessLog?.(stepIndex);
+		emitSecretMountEvents(getSecretMountRecords?.(stepIndex), stepIndex, sendFn);
 		sendFn({
 			type: "step.complete",
 			stepIndex,
@@ -1316,7 +1491,7 @@ function extractSignal(error) {
 */
 async function evaluateStepRulesAndMaybeSkip(step, stepIndex, opts) {
 	if (!step.rules || step.rules.length === 0) return null;
-	const ruleCtx = createRuleContext(opts.event, [], opts.env);
+	const ruleCtx = createRuleContext(opts.event, [], opts.env, opts.dispatchInputs ?? {}, opts.fanout);
 	const ruleResult = await evaluateRules(step.rules, ruleCtx, step.name);
 	if (ruleResult.allPassed) return null;
 	opts.sendIpc({
@@ -1391,7 +1566,7 @@ async function maybeGateStepApproval(step, stepIndex, opts) {
 		stepIndex,
 		line: `[kici] Step '${step.name}' ${why}.`
 	});
-	await opts.disposeStepResources?.();
+	await opts.disposeStepResources?.(stepIndex);
 	return {
 		result: {
 			name: step.name,
@@ -1417,15 +1592,16 @@ async function runObserverHook(args) {
 		startTime: opts.startTime ?? Date.now(),
 		...failedStep !== void 0 && { failedStep }
 	});
-	const hookResult = await executeHook({
+	const ctx = opts.createStepContext(stepIndex, step.name);
+	const hookResult = await captureWrap(opts)(hookStepIndex, () => executeHook({
 		hook,
-		stepContext: opts.createStepContext(stepIndex, step.name),
+		stepContext: ctx,
 		outcome,
 		hookType,
 		stepIndex: hookStepIndex,
 		sendIpc: opts.sendIpc,
 		timeout: 3e5
-	});
+	}));
 	if (!hookResult.success) opts.sendIpc({
 		type: "log.line",
 		stepIndex,
@@ -1442,10 +1618,43 @@ async function runObserverHook(args) {
 * `ctx.secrets.mountFile` tmpdir, any env vars set via `exposeFile`) is
 * removed even when the step throws, times out, or rule-skips.
 */
+/**
+* Run a step through its retry policy. Each call to `executeStepInLoop` is one
+* attempt: it sets up its own per-attempt timeout from `step.timeout` and returns
+* a `SandboxStepResult` (it never throws — a failed attempt is reported as a
+* `failed` status with an `error`). A failed attempt is retried while attempts
+* remain AND `retryIf(reconstructedError)` is true; backoff sleeps between
+* attempts. The retry loop runs to completion BEFORE the caller applies
+* `continueOnError` to the final outcome.
+*/
+async function runStepWithRetry(step, stepIndex, ctx, timeoutMs, opts) {
+	const retry = step.retry;
+	const max = retry?.maxAttempts ?? 1;
+	let result;
+	for (let n = 1; n <= max; n++) {
+		result = await executeStepInLoop(step, stepIndex, ctx, timeoutMs, opts.sendIpc, opts.outputsMap, opts.getSecretsAccessLog, opts.getSecretMountRecords, opts.jobDeadlineSignal, opts.checkMode ?? CheckMode.enum.apply, opts);
+		if (result.status !== ExecutionStepStatus.enum.failed) return result;
+		const err = new Error(result.error?.message ?? `Step '${step.name}' failed`);
+		if (!(n < max && (retry?.retryIf?.(err) ?? true))) break;
+		const delay = computeBackoffDelay(n, {
+			maxAttempts: max,
+			delayMs: retry.delayMs,
+			backoff: retry.backoff,
+			maxDelayMs: retry.maxDelayMs
+		});
+		opts.sendIpc({
+			type: "log.line",
+			stepIndex,
+			line: `[kici] Step '${step.name}' attempt ${n}/${max} failed: ${err.message}; retrying in ${delay}ms`
+		});
+		await new Promise((r) => setTimeout(r, delay));
+	}
+	return result;
+}
 async function runStepIteration(step, stepIndex, opts) {
 	const skippedResult = await evaluateStepRulesAndMaybeSkip(step, stepIndex, opts);
 	if (skippedResult) {
-		await opts.disposeStepResources?.();
+		await opts.disposeStepResources?.(stepIndex);
 		return {
 			result: skippedResult,
 			shouldBreak: false
@@ -1462,18 +1671,18 @@ async function runStepIteration(step, stepIndex, opts) {
 		opts
 	});
 	const stepCacheSpecs = opts.cachePhaseDeps ? normalizeCacheSpecs(step.cache) : [];
-	const stepCacheRestore = stepCacheSpecs.length > 0 && opts.cachePhaseDeps ? await restoreCacheSpecs(stepCacheSpecs, opts.cachePhaseDeps) : /* @__PURE__ */ new Map();
+	const stepCacheRestore = stepCacheSpecs.length > 0 && opts.cachePhaseDeps ? await restoreCacheSpecs(stepCacheSpecs, opts.cachePhaseDeps, stepIndex) : /* @__PURE__ */ new Map();
 	try {
-		await opts.beforeStepEnvFiles?.();
+		await opts.beforeStepEnvFiles?.(stepIndex);
 		const ctx = opts.createStepContext(stepIndex, step.name);
 		const timeoutMs = step.timeout ?? opts.defaultTimeoutMs;
 		let result;
 		try {
-			result = await executeStepInLoop(step, stepIndex, ctx, timeoutMs, opts.sendIpc, opts.outputsMap, opts.getSecretsAccessLog, opts.getSecretMountRecords, opts.jobDeadlineSignal, opts.checkMode ?? CheckMode.enum.apply, opts);
+			result = await captureWrap(opts)(stepIndex, () => runStepWithRetry(step, stepIndex, ctx, timeoutMs, opts));
 		} finally {
-			await opts.afterStepApplyEnvFiles?.();
+			await opts.afterStepApplyEnvFiles?.(stepIndex);
 		}
-		if (stepCacheSpecs.length > 0 && opts.cachePhaseDeps && result.status === ExecutionStepStatus.enum.success) await saveCacheSpecs(stepCacheSpecs, stepCacheRestore, opts.cachePhaseDeps);
+		if (stepCacheSpecs.length > 0 && opts.cachePhaseDeps && result.status === ExecutionStepStatus.enum.success) await saveCacheSpecs(stepCacheSpecs, stepCacheRestore, opts.cachePhaseDeps, stepIndex);
 		if (opts.jobHooks?.afterStep) await runObserverHook({
 			hook: opts.jobHooks.afterStep,
 			hookType: "afterStep",
@@ -1493,7 +1702,7 @@ async function runStepIteration(step, stepIndex, opts) {
 			shouldBreak: false
 		};
 	} finally {
-		await opts.disposeStepResources?.();
+		await opts.disposeStepResources?.(stepIndex);
 	}
 }
 /**
@@ -1509,14 +1718,15 @@ async function runCompletionHook(args) {
 		stepIndex: -1,
 		line: `[kici] Running ${hookType} hook...`
 	});
-	const hookResult = await executeHook({
+	const ctx = opts.createStepContext(hookStepIndex, hookType);
+	const hookResult = await captureWrap(opts)(hookStepIndex, () => executeHook({
 		hook,
-		stepContext: opts.createStepContext(hookStepIndex, hookType),
+		stepContext: ctx,
 		outcome,
 		hookType,
 		stepIndex: hookStepIndex,
 		sendIpc: opts.sendIpc
-	});
+	}));
 	if (hookResult.success) {
 		opts.sendIpc({
 			type: "log.line",
@@ -1614,9 +1824,24 @@ async function executeStepLoop(opts) {
 	const startTime = opts.startTime ?? Date.now();
 	const stepResults = [];
 	const state = { failed: false };
-	for (const [i, step] of opts.steps.entries()) {
+	const nodes = opts.stepNodes ?? opts.steps.map((step, i) => ({
+		kind: "sequential",
+		step,
+		stepIndex: i
+	}));
+	for (const node of nodes) {
 		if (opts.isAborted?.()) break;
-		const outcome = await runStepIteration(step, i, opts);
+		if (node.kind === "parallel") {
+			const groupOutcome = await runParallelGroup(node, opts);
+			stepResults.push(...groupOutcome.results);
+			if (groupOutcome.failed) {
+				state.failed = true;
+				state.failedStepName = groupOutcome.failedStepName;
+				break;
+			}
+			continue;
+		}
+		const outcome = await runStepIteration(node.step, node.stepIndex, opts);
 		stepResults.push(outcome.result);
 		if (outcome.failedStepName) {
 			state.failed = true;
@@ -1637,6 +1862,69 @@ async function executeStepLoop(opts) {
 	};
 }
 //#endregion
+//#region src/execution/sandbox/capture-context.ts
+/**
+* Attributes captured console output to the step whose run is currently on the
+* async call stack.
+*
+* The monkey-patched `process.stdout/stderr.write` reads
+* {@link currentCaptureStepIndex} to decide which `step-N.log` a console line
+* belongs to. Keying this on the async execution context (rather than a single
+* module global) makes attribution correct when more than one step body runs
+* concurrently: each step's `run` executes inside its own
+* {@link runInStepCapture} scope, so its writes resolve to its own index even
+* while a sibling step is mid-flight. Under sequential execution exactly one
+* scope is active at a time, identical to the former global.
+*/
+const stepCaptureStore = new AsyncLocalStorage();
+/**
+* Run `fn` with `stepIndex` as the active console-capture attribution for the
+* duration of its async execution (including everything it awaits).
+*/
+function runInStepCapture(stepIndex, fn) {
+	return stepCaptureStore.run(stepIndex, fn);
+}
+/**
+* The step index whose run is currently on the async stack, or `-1` when no
+* capture scope is active (workflow-level / between-steps output).
+*/
+function currentCaptureStepIndex() {
+	return stepCaptureStore.getStore() ?? -1;
+}
+//#endregion
+//#region src/execution/sandbox/step-task-registry.ts
+/**
+* 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.
+*/
+var StepTaskRegistry = class {
+	#slots = /* @__PURE__ */ new Map();
+	set(stepIndex, slot) {
+		this.#slots.set(stepIndex, slot);
+	}
+	getAccessLog(stepIndex) {
+		return this.#slots.get(stepIndex)?.secrets.getAccessLog() ?? [];
+	}
+	getMountRecords(stepIndex) {
+		const slot = this.#slots.get(stepIndex);
+		return slot ? [...slot.secrets.getMountRecords()] : [];
+	}
+	async dispose(stepIndex) {
+		const slot = this.#slots.get(stepIndex);
+		if (!slot) return;
+		this.#slots.delete(stepIndex);
+		await slot.dispose();
+	}
+};
+//#endregion
 //#region src/execution/env-init/init-phase.ts
 /** Default init timeout when a spec sets none: 10 minutes. */
 const DEFAULT_INIT_TIMEOUT_MS = 600 * 1e3;
@@ -3111,8 +3399,8 @@ function logSubprocessStreams(e, tokens) {
 * no Rolldown step at runtime. `@kici-dev/sdk` and host-repo deps resolve via
 * Node's normal ESM lookup against `.kici/node_modules/`.
 */
-const AGENT_SDK_VERSION = "0.1.22";
-const AGENT_SDK_BUNDLE_HASH = "4b26a42978f77e29db110d47523ec947d3d673c3109fc48141c1a62814bde7a1";
+const AGENT_SDK_VERSION = "0.1.24";
+const AGENT_SDK_BUNDLE_HASH = "031712cf8cd02f483365113aad7e946da982110d544b177eb05edcc0d4421253";
 /**
 * Register the `@kici-dev/core/ts-loader-hook` oxc-transform ESM loader hook so
 * subsequent dynamic `import()` calls for `.ts` / `.tsx` files transform on the
@@ -3474,7 +3762,7 @@ async function applyOverlay(config) {
 */
 init_download();
 init_dep_restore();
-const AGENT_VERSION = "0.1.22";
+const AGENT_VERSION = "0.1.24";
 process.on("uncaughtException", (err) => {
 	process.stderr.write(`[workflow-runner] UNCAUGHT EXCEPTION: ${err.message}\n`);
 	if (err.stack) process.stderr.write(`[workflow-runner] Stack: ${err.stack}\n`);
@@ -3497,12 +3785,6 @@ const isForkMode = typeof process.send === "function";
 const origStdoutWrite = process.stdout.write.bind(process.stdout);
 const origStderrWrite = process.stderr.write.bind(process.stderr);
 /**
-* Current step index for console.log/console.error capture.
-* When >= 0, process.stdout/stderr writes are intercepted and sent as
-* log.line IPC messages for the given step. Set to -1 outside step execution.
-*/
-let captureStepIndex = -1;
-/**
 * Workflow-level capture flag for the pre-step `prepare` phase
 * (module load, concurrency-group evaluation, rule evaluation).
 *
@@ -3513,17 +3795,18 @@ let captureStepIndex = -1;
 * rule check functions lands in the job's workflow-level log file
 * (`executions/{runId}/job-{name}/step--1.log`) alongside runner narration.
 *
-* Mutually exclusive with `captureStepIndex >= 0` — the step loop resets
-* this flag to false before setting `captureStepIndex` to a real step index.
+* Mutually exclusive with a step capture scope: the step loop resets this flag
+* to false before any step runs inside its {@link runInStepCapture} scope (the
+* async-context source of {@link currentCaptureStepIndex}).
 */
 let capturePrepareActive = false;
 /** The maskedSend function used by the output capture. Set during main(). */
 let captureSendFn = null;
 function captureIsActive() {
-	return (captureStepIndex >= 0 || capturePrepareActive) && captureSendFn !== null;
+	return (currentCaptureStepIndex() >= 0 || capturePrepareActive) && captureSendFn !== null;
 }
 function captureTargetIndex() {
-	return captureStepIndex >= 0 ? captureStepIndex : -1;
+	return currentCaptureStepIndex();
 }
 /**
 * Install monkey-patches on process.stdout.write and process.stderr.write
@@ -3672,6 +3955,14 @@ let jobTimedOutMs;
 */
 const jobDeadlineAbort = new AbortController();
 /**
+* Aborted when the job is being torn down by cancellation (abort IPC / SIGTERM),
+* as distinct from the wall-clock deadline (`jobDeadlineAbort`). Each step's
+* `ctx.signal` composes this with the deadline signal and its own per-step
+* controller, so a cancelled job cooperatively unwinds in-flight step bodies
+* that opted into `ctx.signal`. Inert for the rest of the runner today.
+*/
+const jobCancelAbort = new AbortController();
+/**
 * Pending promises for event.emit requests awaiting responses from the agent.
 *
 * Key: requestId (correlates EventEmitRequest -> EventEmitResponse)
@@ -4035,17 +4326,16 @@ function buildAttestProvenanceFn(request, workDir, getIdToken) {
 * post-loop save phase skip exact-key hits.
 */
 async function setupJobCache(stepCwd, stepCount, jobCache, sendIpc) {
-	let cacheStepCursor = stepCount * 3 + 100;
 	const cachePhaseDeps = {
 		cache: createCacheApi(stepCwd, buildCacheTransport()),
 		sendIpc,
-		nextStepIndex: () => cacheStepCursor++
+		nextStepIndex: createCacheStepIndexAllocator(stepCount)
 	};
 	const jobCacheSpecs = normalizeCacheSpecs(jobCache);
 	return {
 		cachePhaseDeps,
 		jobCacheSpecs,
-		jobCacheRestore: jobCacheSpecs.length > 0 ? await restoreCacheSpecs(jobCacheSpecs, cachePhaseDeps) : /* @__PURE__ */ new Map()
+		jobCacheRestore: jobCacheSpecs.length > 0 ? await restoreCacheSpecs(jobCacheSpecs, cachePhaseDeps, -1) : /* @__PURE__ */ new Map()
 	};
 }
 /**
@@ -4058,7 +4348,7 @@ async function setupJobCache(stepCwd, stepCount, jobCache, sendIpc) {
 */
 async function maybeSaveJobCache(specs, restoreResults, deps, succeeded) {
 	if (specs.length === 0 || !succeeded) return;
-	await saveCacheSpecs(specs, restoreResults, deps);
+	await saveCacheSpecs(specs, restoreResults, deps, -1);
 }
 /**
 * Dispatch an agent-to-runner message to the appropriate pending handler.
@@ -4067,6 +4357,7 @@ async function maybeSaveJobCache(specs, restoreResults, deps, succeeded) {
 function dispatchAgentMessage(msg) {
 	if (msg.type === "abort") {
 		aborted = true;
+		jobCancelAbort.abort();
 		if (msg.force) forceAborted = true;
 	} else if (msg.type === "event.emit.response") {
 		const pending = pendingEmitResponses.get(msg.requestId);
@@ -4099,6 +4390,7 @@ else getStdinRl().on("line", (line) => {
 });
 process.on("SIGTERM", () => {
 	aborted = true;
+	jobCancelAbort.abort();
 });
 /**
 * Create a Logger that sends log lines via IPC.
@@ -4333,7 +4625,7 @@ function buildSandboxShell(cwd, stepIndex, maskedSendFn) {
 * NOT serialized across the process boundary. This means zx $ runs natively
 * inside this process with full shell access.
 */
-function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedSendFn, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, secrets, masker) {
+function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedSendFn, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, secrets, masker, signal) {
 	const step$ = buildSandboxShell(workDir, stepIndex, maskedSendFn);
 	const log = createIpcLogger(stepIndex, stepName, maskedSendFn);
 	const rawPayload = rawPayloadFromEvent(request.event);
@@ -4352,6 +4644,7 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 	return {
 		$: step$,
 		log,
+		signal,
 		env: process.env,
 		setEnv: (key, value) => {
 			applyEnvDelta({
@@ -4407,12 +4700,32 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 		...request.matrixValues && { matrix: request.matrixValues },
 		...request.host && { host: request.host },
 		...request.agent && { agent: request.agent },
+		...(() => {
+			const fanout = deriveFanout(request);
+			return fanout ? { fanout } : {};
+		})(),
+		dispatchInputs: request.dispatchInputs ?? {},
 		...(() => {
 			const needs = buildStepNeedsContext(request.jobNeeds, request.upstreamJobOutputs, request.upstreamJobStatuses);
 			return needs ? { needs } : {};
 		})()
 	};
 }
+/**
+* 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.
+*/
+function deriveFanout(request) {
+	if (request.fanoutTotal === void 0) return void 0;
+	const index = request.fanoutIndex ?? 0;
+	return {
+		index,
+		total: request.fanoutTotal,
+		first: index === 0,
+		last: index === request.fanoutTotal - 1
+	};
+}
 /** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
 function rawPayloadFromEvent(event) {
 	if (!event) return void 0;
@@ -4905,7 +5218,7 @@ async function runCancelPathHooks(args) {
 		const ctx = createStepCtxWithCapture(hookStepIndex, label);
 		let hookResult;
 		try {
-			hookResult = await executeHook({
+			hookResult = await runInStepCapture(hookStepIndex, () => executeHook({
 				hook,
 				stepContext: ctx,
 				outcome: failedStep ? {
@@ -4915,9 +5228,9 @@ async function runCancelPathHooks(args) {
 				hookType,
 				stepIndex: hookStepIndex,
 				sendIpc: maskedSend
-			});
+			}));
 		} finally {
-			await disposeStepResources();
+			await disposeStepResources(hookStepIndex);
 		}
 		hookStepIndex++;
 		if (!hookResult.success) {
@@ -4968,29 +5281,66 @@ async function extractAndNormalizeSteps(workflow, request, apiTransport) {
 	} else rawSteps = extractSteps(workflow, request.jobName);
 	const refMap = /* @__PURE__ */ new WeakMap();
 	let stepCounter = 0;
-	return {
-		normalizedSteps: rawSteps.map((stepOrFn) => {
-			if (typeof stepOrFn === "function") {
-				stepCounter++;
-				const name = `step-${stepCounter}`;
-				refMap.set(stepOrFn, name);
-				return {
-					_tag: "Step",
-					name,
-					run: stepOrFn,
-					outputs: void 0
-				};
-			}
-			const s = stepOrFn;
-			if (!s.name) {
-				stepCounter++;
+	const coerce = (stepOrFn) => {
+		if (typeof stepOrFn === "function") {
+			stepCounter++;
+			const name = `step-${stepCounter}`;
+			refMap.set(stepOrFn, name);
+			return {
+				_tag: "Step",
+				name,
+				run: stepOrFn,
+				outputs: void 0
+			};
+		}
+		const s = stepOrFn;
+		if (!s.name) {
+			stepCounter++;
+			return {
+				...s,
+				name: `step-${stepCounter}`
+			};
+		}
+		return s;
+	};
+	const normalizedSteps = [];
+	const nodes = [];
+	let flatIndex = 0;
+	let groupOrdinal = 0;
+	for (const entry of rawSteps) {
+		if (isParallelGroup(entry)) {
+			const groupId = `g${groupOrdinal++}`;
+			const children = entry.steps.map((child) => {
+				const step = coerce(child);
+				const stepIndex = flatIndex++;
+				normalizedSteps.push(step);
 				return {
-					...s,
-					name: `step-${stepCounter}`
+					step,
+					stepIndex
 				};
-			}
-			return s;
-		}),
+			});
+			nodes.push({
+				kind: "parallel",
+				groupId,
+				name: entry.name ?? groupId,
+				failFast: entry.failFast,
+				...entry.maxParallel !== void 0 && { maxParallel: entry.maxParallel },
+				children
+			});
+			continue;
+		}
+		const step = coerce(entry);
+		const stepIndex = flatIndex++;
+		normalizedSteps.push(step);
+		nodes.push({
+			kind: "sequential",
+			step,
+			stepIndex
+		});
+	}
+	return {
+		normalizedSteps,
+		nodes,
 		refMap,
 		driftDroppedJobs
 	};
@@ -5026,7 +5376,7 @@ function buildOutputInfrastructure(request, refMap) {
 */
 async function maybeSkipJobOnRules(job, request, normalizedSteps) {
 	if (!job?.rules || job.rules.length === 0) return false;
-	const ruleCtx = createRuleContext(request.event ?? {}, [], process.env);
+	const ruleCtx = createRuleContext(request.event ?? {}, [], process.env, request.dispatchInputs ?? {}, deriveFanout(request));
 	if ((await evaluateRules(job.rules, ruleCtx, request.jobName)).allPassed) return false;
 	const skippedResults = normalizedSteps.map((s, i) => ({
 		name: s.name,
@@ -5087,22 +5437,40 @@ async function applyEnvFilesDelta(envFiles, operatorSecretKeys, maskedSend) {
 	await truncateEnvFiles(envFiles);
 }
 /**
-* Build the step loop's KICI_ENV/KICI_PATH callbacks over the shared `envFiles`.
-* `beforeStepEnvFiles` points the runner's process.env at the files (each step's
-* zx $ snapshots process.env at context creation, which happens AFTER this
+* 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` applies + truncates the
-* delta, mirroring the init phase's env port.
-*/
-function buildStepEnvFileHooks(envFiles, operatorSecretKeys, maskedSend) {
+* 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.
+*/
+function buildStepEnvFileHooks(operatorSecretKeys, maskedSend) {
+	const perStep = /* @__PURE__ */ new Map();
 	return {
-		beforeStepEnvFiles: async () => {
-			process.env.KICI_ENV = envFiles.envFile;
-			process.env.KICI_PATH = envFiles.pathFile;
+		beforeStepEnvFiles: async (stepIndex) => {
+			let files = perStep.get(stepIndex);
+			if (!files) {
+				files = await createEnvFiles(tmpdir());
+				perStep.set(stepIndex, files);
+			}
+			process.env.KICI_ENV = files.envFile;
+			process.env.KICI_PATH = files.pathFile;
 		},
-		afterStepApplyEnvFiles: async () => {
+		afterStepApplyEnvFiles: async (stepIndex) => {
+			const files = perStep.get(stepIndex);
+			if (!files) return;
+			perStep.delete(stepIndex);
 			try {
-				await applyEnvFilesDelta(envFiles, operatorSecretKeys, maskedSend);
+				await applyEnvFilesDelta(files, operatorSecretKeys, maskedSend);
 			} catch (err) {
 				maskedSend({
 					type: "log.line",
@@ -5237,7 +5605,7 @@ async function main() {
 		});
 		return waitForApiResponse(reqId);
 	};
-	const { normalizedSteps, refMap, driftDroppedJobs } = await extractAndNormalizeSteps(workflow, request, apiTransport);
+	const { normalizedSteps, nodes, refMap, driftDroppedJobs } = await extractAndNormalizeSteps(workflow, request, apiTransport);
 	const { operatorSecretKeys, outputsMap, secretOutputs, jobOutputsMap } = buildOutputInfrastructure(request, refMap);
 	const job = findJob(workflow, request.jobName);
 	await maybeSkipJobOnRules(job, request, normalizedSteps);
@@ -5247,33 +5615,43 @@ async function main() {
 	flushOutputCapture();
 	capturePrepareActive = false;
 	const stepCwd = sourceDir;
-	const envFiles = await createEnvFiles(tmpdir());
 	await runInitPhaseOrFailJob({
 		job,
 		stepCwd,
-		envFiles,
+		envFiles: await createEnvFiles(tmpdir()),
 		operatorSecretKeys,
 		maskedSend
 	});
 	const { cachePhaseDeps, jobCacheSpecs, jobCacheRestore } = await setupJobCache(stepCwd, normalizedSteps.length, job?.cache, maskedSend);
-	let currentStepSecrets = null;
-	let currentStepDispose = null;
+	const stepTasks = new StepTaskRegistry();
+	const stepAbortControllers = /* @__PURE__ */ new Map();
 	const createStepCtxWithCapture = (stepIndex, stepName) => {
-		captureStepIndex = stepIndex;
+		const stepAbort = new AbortController();
+		stepAbortControllers.set(stepIndex, stepAbort);
+		const signal = AbortSignal.any([
+			stepAbort.signal,
+			jobCancelAbort.signal,
+			jobDeadlineAbort.signal
+		]);
 		const handle = buildStepSecrets(request, masker, () => {});
-		currentStepSecrets = handle.secrets;
-		currentStepDispose = handle.dispose;
-		const ctx = createSandboxStepContext(stepCwd, stepIndex, stepName, request, maskedSend, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, handle.secrets, masker);
+		stepTasks.set(stepIndex, {
+			secrets: handle.secrets,
+			dispose: handle.dispose
+		});
+		const ctx = createSandboxStepContext(stepCwd, stepIndex, stepName, request, maskedSend, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, handle.secrets, masker, signal);
 		if (globalRepoInfo) {
 			ctx.workflowRepo = globalRepoInfo.workflowRepo;
 			ctx.sourceRepo = globalRepoInfo.sourceRepo;
 		}
 		return ctx;
 	};
-	const stepEnvHooks = buildStepEnvFileHooks(envFiles, operatorSecretKeys, maskedSend);
+	const stepEnvHooks = buildStepEnvFileHooks(operatorSecretKeys, maskedSend);
 	const jobStartTime = Date.now();
 	const loopResult = await executeStepLoop({
 		steps: normalizedSteps,
+		stepNodes: nodes,
+		abortStep: (stepIndex) => stepAbortControllers.get(stepIndex)?.abort(),
+		getStepAbortSignal: (stepIndex) => stepAbortControllers.get(stepIndex)?.signal,
 		checkMode: request.checkMode,
 		createStepContext: createStepCtxWithCapture,
 		sendIpc: maskedSend,
@@ -5281,24 +5659,22 @@ async function main() {
 		outputsMap,
 		event: request.event ?? {},
 		env: process.env,
+		dispatchInputs: request.dispatchInputs ?? {},
+		fanout: deriveFanout(request),
 		jobHooks,
 		cachePhaseDeps,
 		isAborted: () => aborted,
 		jobDeadlineSignal: jobDeadlineAbort.signal,
 		startTime: jobStartTime,
-		getSecretsAccessLog: () => {
+		runWithStepCapture: runInStepCapture,
+		getSecretsAccessLog: (stepIndex) => {
 			flushOutputCapture();
-			captureStepIndex = -1;
-			return currentStepSecrets?.getAccessLog() ?? [];
-		},
-		getSecretMountRecords: () => {
-			return currentStepSecrets ? [...currentStepSecrets.getMountRecords()] : [];
+			return stepTasks.getAccessLog(stepIndex);
 		},
-		disposeStepResources: async () => {
-			const disposeFn = currentStepDispose;
-			currentStepDispose = null;
-			currentStepSecrets = null;
-			if (disposeFn) await disposeFn();
+		getSecretMountRecords: (stepIndex) => stepTasks.getMountRecords(stepIndex),
+		disposeStepResources: (stepIndex) => {
+			stepAbortControllers.delete(stepIndex);
+			return stepTasks.dispose(stepIndex);
 		},
 		beforeStepEnvFiles: stepEnvHooks.beforeStepEnvFiles,
 		afterStepApplyEnvFiles: stepEnvHooks.afterStepApplyEnvFiles,
@@ -5318,11 +5694,9 @@ async function main() {
 			jobStartTime,
 			outputsMap,
 			createStepCtxWithCapture,
-			disposeStepResources: async () => {
-				const disposeFn = currentStepDispose;
-				currentStepDispose = null;
-				currentStepSecrets = null;
-				if (disposeFn) await disposeFn();
+			disposeStepResources: (stepIndex) => {
+				stepAbortControllers.delete(stepIndex);
+				return stepTasks.dispose(stepIndex);
 			},
 			maskedSend
 		});
@@ -5389,6 +5763,6 @@ main().catch((error) => {
 	setTimeout(() => process.exit(1), 100);
 });
 //#endregion
-export { buildStepNeedsContext, createSandboxStepContext, rawPayloadFromEvent };
+export { buildStepEnvFileHooks, buildStepNeedsContext, createSandboxStepContext, deriveFanout, rawPayloadFromEvent };
 
 //# sourceMappingURL=workflow-runner.js.map