@kici-dev/agent 0.0.0 → 0.1.2

package/dist/workflow-runner.js

@@ -0,0 +1,2978 @@
+import { fileURLToPath as __cjs_fileURLToPath } from "node:url";
+import { dirname as __cjs_dirname } from "node:path";
+__cjs_dirname(__cjs_fileURLToPath(import.meta.url));
+import { register } from "node:module";
+import { createInterface } from "node:readline";
+import crypto, { createHash, randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import fsPromises, { mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import os, { tmpdir } from "node:os";
+import path, { dirname, join } from "node:path";
+import { $ } from "zx";
+import { createLogger, deriveSharedSecret, initZx, normalizeLineEndings, sha256, sha256File, toErrorMessage } from "@kici-dev/shared";
+import { ExecutionJobStatus, ExecutionStepStatus } from "@kici-dev/engine";
+import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
+import "node:child_process";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { x } from "tar";
+import https from "node:https";
+import http from "node:http";
+import.meta.url;
+//#endregion
+//#region src/execution/sandbox/log-masker.ts
+/**
+* Secret value masking for log lines.
+*
+* Replaces all occurrences of registered secret values with '***' in log output.
+* Used by the workflow runner to prevent secret leaks in IPC log messages.
+*
+* Performance: Builds a single combined regex from all secret values, so each
+* log line is scanned in a single pass (not O(secrets * lines)).
+*/
+/** Minimum length for a secret value to be maskable (avoids false positives). */
+const MIN_MASK_LENGTH = 3;
+/**
+* Escape regex special characters in a string.
+*/
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Masks secret values in log lines.
+*
+* Usage:
+* ```ts
+* const masker = new LogMasker();
+* masker.registerSecrets({ TOKEN: 'abc123', SHORT: 'ab' });
+* masker.mask('Token is abc123'); // 'Token is ***'
+* // 'ab' is NOT masked (< 3 chars)
+* ```
+*/
+var LogMasker = class {
+	pattern = null;
+	/**
+	* Register secret values to be masked in log output.
+	*
+	* Values shorter than 3 characters are skipped to avoid false positives.
+	* Base64-encoded variants of each qualifying secret are also registered,
+	* preventing leaks when secrets appear base64-encoded in logs (e.g.,
+	* Authorization: Basic headers, base64-encoded config values).
+	* Values are sorted by length descending so longer values are matched first
+	* (prevents partial masking when one secret is a substring of another).
+	*/
+	registerSecrets(secrets) {
+		const seen = /* @__PURE__ */ new Set();
+		const values = [];
+		for (const value of Object.values(secrets)) if (value.length >= MIN_MASK_LENGTH && !seen.has(value)) {
+			seen.add(value);
+			values.push(value);
+			const b64 = Buffer.from(value).toString("base64");
+			if (b64.length >= MIN_MASK_LENGTH && !seen.has(b64)) {
+				seen.add(b64);
+				values.push(b64);
+			}
+		}
+		if (values.length === 0) {
+			this.pattern = null;
+			return;
+		}
+		values.sort((a, b) => b.length - a.length);
+		this.pattern = new RegExp(values.map((v) => escapeRegExp(v)).join("|"), "g");
+	}
+	/**
+	* Mask all registered secret values in a log line.
+	*
+	* Returns the line unchanged if no secrets are registered.
+	*/
+	mask(line) {
+		if (!this.pattern) return line;
+		this.pattern.lastIndex = 0;
+		return line.replace(this.pattern, "***");
+	}
+	/**
+	* Returns true if any maskable secrets are registered.
+	*/
+	hasSecrets() {
+		return this.pattern !== null;
+	}
+};
+//#endregion
+//#region src/execution/sandbox/secret-merge.ts
+/**
+* Secret merging utilities for the workflow runner.
+*
+* Separated from workflow-runner.ts to allow unit testing without
+* triggering the runner's top-level side effects (process handlers, main()).
+*/
+/**
+* Merge orchestrator-level secrets with auto-flattened context keys.
+*
+* Precedence (last wins):
+* 1. Orchestrator-level secrets (lowest)
+* 2. Context-flattened keys in declaration order (each context's keys overlay previous)
+*
+* This means: context-flattened keys override orchestrator-level secrets,
+* and for collisions between contexts, last declared context wins.
+*/
+function buildMergedFlatSecrets(orchestratorSecrets, namespacedSecrets) {
+	const merged = { ...orchestratorSecrets };
+	for (const contextSecrets of Object.values(namespacedSecrets)) Object.assign(merged, contextSecrets);
+	return merged;
+}
+//#endregion
+//#region src/execution/hook-executor.ts
+/** Default hook timeout: 5 minutes */
+const DEFAULT_HOOK_TIMEOUT_MS = 300 * 1e3;
+/**
+* Build outcome metadata from execution state.
+*
+* Duration is calculated as elapsed time since startTime.
+*/
+function buildOutcomeMetadata(opts) {
+	return {
+		status: opts.status,
+		reason: opts.reason,
+		failedStep: opts.failedStep,
+		stepOutputs: opts.stepOutputs,
+		duration: Date.now() - opts.startTime
+	};
+}
+/**
+* Normalize a HookInput (bare function, { run, timeout }, or HookConfig) into a HookConfig.
+*/
+function normalizeHook(hook, hookType) {
+	if (typeof hook === "object" && "name" in hook && "type" in hook) return hook;
+	if (typeof hook === "function") return {
+		name: hookType,
+		type: hookType,
+		run: hook
+	};
+	if (typeof hook === "object" && "run" in hook) return {
+		name: hookType,
+		type: hookType,
+		run: hook.run,
+		timeout: hook.timeout
+	};
+	throw new Error(`Invalid hook input for ${hookType}`);
+}
+/**
+* Execute a single hook with timeout enforcement and IPC reporting.
+*
+* Sends step.start and step.complete IPC messages with step_type = 'hook:{hookType}'.
+* The hook runs in the same sandbox context as regular steps.
+*/
+async function executeHook(opts) {
+	const { stepContext, outcome, hookType, stepIndex, sendIpc } = opts;
+	const normalized = normalizeHook(opts.hook, hookType);
+	const timeoutMs = normalized.timeout ?? opts.timeout ?? DEFAULT_HOOK_TIMEOUT_MS;
+	sendIpc({
+		type: "step.start",
+		stepIndex,
+		stepName: normalized.name,
+		step_type: `hook:${hookType}`
+	});
+	const startTime = Date.now();
+	const mergedCtx = {
+		...stepContext,
+		outcome
+	};
+	const abortController = new AbortController();
+	const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
+	try {
+		await Promise.race([normalized.run(mergedCtx), new Promise((_, reject) => {
+			abortController.signal.addEventListener("abort", () => {
+				reject(/* @__PURE__ */ new Error(`Hook '${normalized.name}' timed out after ${timeoutMs}ms`));
+			});
+		})]);
+		clearTimeout(timeoutId);
+		sendIpc({
+			type: "step.complete",
+			stepIndex,
+			status: "success",
+			durationMs: Date.now() - startTime,
+			step_type: `hook:${hookType}`
+		});
+		return { success: true };
+	} catch (e) {
+		clearTimeout(timeoutId);
+		const durationMs = Date.now() - startTime;
+		const error = toErrorMessage(e);
+		sendIpc({
+			type: "step.complete",
+			stepIndex,
+			status: "failed",
+			durationMs,
+			error: { message: error },
+			step_type: `hook:${hookType}`
+		});
+		return {
+			success: false,
+			error
+		};
+	}
+}
+//#endregion
+//#region src/execution/rule-evaluator.ts
+initZx();
+/**
+* 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
+*/
+function createRuleContext(event, changedFiles = [], env = {}) {
+	return {
+		event,
+		changedFiles,
+		env,
+		$
+	};
+}
+//#endregion
+//#region src/execution/sandbox/step-loop.ts
+/**
+* Execute a single step with timeout enforcement.
+*
+* Timeout pattern using Promise.race + AbortController, with IPC status reporting.
+*/
+async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, outputsMap, getSecretsAccessLog, getSecretMountRecords) {
+	sendFn({
+		type: "step.start",
+		stepIndex,
+		stepName: step.name
+	});
+	const startTime = Date.now();
+	const abortController = new AbortController();
+	const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
+	try {
+		const result = await Promise.race([step.run(ctx), new Promise((_, reject) => {
+			abortController.signal.addEventListener("abort", () => {
+				reject(/* @__PURE__ */ new Error(`Step '${step.name}' timed out after ${timeoutMs}ms`));
+			});
+		})]);
+		clearTimeout(timeoutId);
+		const durationMs = Date.now() - startTime;
+		const outputsPayload = result != null ? result : void 0;
+		if (outputsPayload) outputsMap.set(step.name, outputsPayload);
+		const secretsAccessed = getSecretsAccessLog?.();
+		emitSecretMountEvents(getSecretMountRecords?.(), stepIndex, sendFn);
+		sendFn({
+			type: "step.complete",
+			stepIndex,
+			status: ExecutionStepStatus.enum.success,
+			durationMs,
+			...outputsPayload && { outputs: outputsPayload },
+			...secretsAccessed !== void 0 && { secretsAccessed }
+		});
+		return {
+			name: step.name,
+			stepIndex,
+			status: ExecutionStepStatus.enum.success,
+			durationMs,
+			...outputsPayload && { outputs: outputsPayload }
+		};
+	} catch (e) {
+		clearTimeout(timeoutId);
+		const durationMs = Date.now() - startTime;
+		const error = e instanceof Error ? e : new Error(String(e));
+		const exitCode = extractExitCode(e);
+		const signal = extractSignal(e);
+		const secretsAccessed = getSecretsAccessLog?.();
+		emitSecretMountEvents(getSecretMountRecords?.(), stepIndex, sendFn);
+		sendFn({
+			type: "step.complete",
+			stepIndex,
+			status: ExecutionStepStatus.enum.failed,
+			durationMs,
+			error: {
+				message: error.message,
+				...exitCode !== void 0 && { exitCode },
+				...signal !== void 0 && { signal }
+			},
+			...secretsAccessed !== void 0 && { secretsAccessed }
+		});
+		return {
+			name: step.name,
+			stepIndex,
+			status: ExecutionStepStatus.enum.failed,
+			durationMs,
+			error: {
+				message: error.message,
+				...exitCode !== void 0 && { exitCode },
+				...signal !== void 0 && { signal }
+			}
+		};
+	}
+}
+/**
+* Emit one `step.secret_mount` IPC event per `mountFile` / `exposeFile` call
+* the step performed. Called from both the success and failure paths so the
+* orchestrator's audit trail records every mount regardless of step outcome.
+*/
+function emitSecretMountEvents(records, stepIndex, sendFn) {
+	if (!records || records.length === 0) return;
+	for (const record of records) sendFn({
+		type: "step.secret_mount",
+		stepIndex,
+		sources: record.sources,
+		target: record.target,
+		kind: record.kind,
+		...record.envVar !== void 0 && { envVar: record.envVar }
+	});
+}
+function extractExitCode(error) {
+	if (error && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number") return error.exitCode;
+}
+function extractSignal(error) {
+	if (error && typeof error === "object" && "signal" in error && typeof error.signal === "string") return error.signal;
+}
+/**
+* Evaluate step-level rules. Returns a 'skipped' result + emits IPC when a rule
+* fails; returns null when the step should run normally.
+*/
+async function evaluateStepRulesAndMaybeSkip(step, stepIndex, opts) {
+	if (!step.rules || step.rules.length === 0) return null;
+	const ruleCtx = createRuleContext(opts.event, [], opts.env);
+	const ruleResult = await evaluateRules(step.rules, ruleCtx, step.name);
+	if (ruleResult.allPassed) return null;
+	opts.sendIpc({
+		type: "step.start",
+		stepIndex,
+		stepName: step.name
+	});
+	opts.sendIpc({
+		type: "step.complete",
+		stepIndex,
+		status: ExecutionStepStatus.enum.failed,
+		durationMs: 0
+	});
+	opts.sendIpc({
+		type: "log.line",
+		stepIndex,
+		line: `[kici] Step '${step.name}' skipped: rule '${ruleResult.results.find((r) => !r.passed)?.label}' did not pass`
+	});
+	return {
+		name: step.name,
+		stepIndex,
+		status: ExecutionStepStatus.enum.skipped,
+		durationMs: 0
+	};
+}
+/**
+* Run a single observer hook (beforeStep / afterStep). Failures only emit a
+* log line — they never change job status. Centralises the per-call boilerplate
+* so the per-step body can stay flat.
+*/
+async function runObserverHook(args) {
+	const { hook, hookType, step, stepIndex, hookStepIndex, failedStep, opts } = args;
+	const outcome = buildOutcomeMetadata({
+		status: failedStep !== void 0 ? ExecutionStepStatus.enum.failed : ExecutionStepStatus.enum.success,
+		stepOutputs: Object.fromEntries(opts.outputsMap),
+		startTime: opts.startTime ?? Date.now(),
+		...failedStep !== void 0 && { failedStep }
+	});
+	const hookResult = await executeHook({
+		hook,
+		stepContext: opts.createStepContext(stepIndex, step.name),
+		outcome,
+		hookType,
+		stepIndex: hookStepIndex,
+		sendIpc: opts.sendIpc,
+		timeout: 3e5
+	});
+	if (!hookResult.success) opts.sendIpc({
+		type: "log.line",
+		stepIndex,
+		line: `[kici] ${hookType} hook failed: ${hookResult.error} (continuing -- hooks are observers)`
+	});
+}
+/**
+* Execute one iteration of the step loop: step rules → beforeStep → execute →
+* afterStep → failure-handling. Returns a typed outcome the loop uses to
+* accumulate results, decide whether to break, and remember the failed step.
+*
+* Wraps the per-step lifecycle in a `try / finally` that calls
+* `opts.disposeStepResources()` so per-step state (the
+* `ctx.secrets.mountFile` tmpdir, any env vars set via `exposeFile`) is
+* removed even when the step throws, times out, or rule-skips.
+*/
+async function runStepIteration(step, stepIndex, opts) {
+	const skippedResult = await evaluateStepRulesAndMaybeSkip(step, stepIndex, opts);
+	if (skippedResult) {
+		await opts.disposeStepResources?.();
+		return {
+			result: skippedResult,
+			shouldBreak: false
+		};
+	}
+	if (opts.jobHooks?.beforeStep) await runObserverHook({
+		hook: opts.jobHooks.beforeStep,
+		hookType: "beforeStep",
+		step,
+		stepIndex,
+		hookStepIndex: opts.steps.length + stepIndex * 2,
+		opts
+	});
+	try {
+		const result = await executeStepInLoop(step, stepIndex, opts.createStepContext(stepIndex, step.name), step.timeout ?? opts.defaultTimeoutMs, opts.sendIpc, opts.outputsMap, opts.getSecretsAccessLog, opts.getSecretMountRecords);
+		if (opts.jobHooks?.afterStep) await runObserverHook({
+			hook: opts.jobHooks.afterStep,
+			hookType: "afterStep",
+			step,
+			stepIndex,
+			hookStepIndex: opts.steps.length + stepIndex * 2 + 1,
+			failedStep: result.status === ExecutionStepStatus.enum.failed ? step.name : void 0,
+			opts
+		});
+		if (result.status === ExecutionStepStatus.enum.failed) return {
+			result,
+			shouldBreak: !step.continueOnError,
+			failedStepName: step.name
+		};
+		return {
+			result,
+			shouldBreak: false
+		};
+	} finally {
+		await opts.disposeStepResources?.();
+	}
+}
+/**
+* Execute one named completion hook (onSuccess / onFailure / cleanup) and
+* return the updated `CompletionState`. Treated as the single source of truth
+* for the "promote to failed + concat reason" pattern that the three completion
+* hooks share.
+*/
+async function runCompletionHook(args) {
+	const { hook, hookType, hookStepIndex, outcome, state, promoteToFailed, opts } = args;
+	opts.sendIpc({
+		type: "log.line",
+		stepIndex: -1,
+		line: `[kici] Running ${hookType} hook...`
+	});
+	const hookResult = await executeHook({
+		hook,
+		stepContext: opts.createStepContext(hookStepIndex, hookType),
+		outcome,
+		hookType,
+		stepIndex: hookStepIndex,
+		sendIpc: opts.sendIpc
+	});
+	if (hookResult.success) {
+		opts.sendIpc({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[kici] ${hookType} hook completed`
+		});
+		return state;
+	}
+	opts.sendIpc({
+		type: "log.line",
+		stepIndex: -1,
+		line: `[kici] ${hookType} hook failed: ${hookResult.error}`
+	});
+	const reasonFragment = `Hook ${hookType} failed: ${hookResult.error}`;
+	return {
+		failed: state.failed || promoteToFailed,
+		failedStepName: state.failedStepName,
+		failureReason: state.failureReason ? `${state.failureReason}; ${reasonFragment}` : reasonFragment
+	};
+}
+/**
+* Run the job-completion hook sequence after the per-step loop ends:
+* onSuccess (or onFailure), then cleanup (always). The cleanup outcome is
+* recomputed so it reflects any failures introduced by onSuccess/onFailure.
+*/
+async function runJobCompletionHooks(opts, initial, outputsMap, startTime) {
+	const { jobHooks } = opts;
+	const initialFinalStatus = initial.failed ? ExecutionStepStatus.enum.failed : ExecutionStepStatus.enum.success;
+	const jobOutcome = buildOutcomeMetadata({
+		status: initialFinalStatus,
+		stepOutputs: Object.fromEntries(outputsMap),
+		startTime,
+		...initial.failedStepName && {
+			failedStep: initial.failedStepName,
+			reason: `Step '${initial.failedStepName}' failed`
+		}
+	});
+	let state = initial;
+	let hookStepIndex = opts.steps.length;
+	if (initialFinalStatus === ExecutionStepStatus.enum.success && jobHooks?.onSuccess) {
+		state = await runCompletionHook({
+			hook: jobHooks.onSuccess,
+			hookType: "onSuccess",
+			hookStepIndex,
+			outcome: jobOutcome,
+			state,
+			promoteToFailed: true,
+			opts
+		});
+		hookStepIndex++;
+	} else if (initialFinalStatus === ExecutionStepStatus.enum.failed && jobHooks?.onFailure) {
+		state = await runCompletionHook({
+			hook: jobHooks.onFailure,
+			hookType: "onFailure",
+			hookStepIndex,
+			outcome: jobOutcome,
+			state,
+			promoteToFailed: false,
+			opts
+		});
+		hookStepIndex++;
+	}
+	if (jobHooks?.cleanup) {
+		const cleanupOutcome = buildOutcomeMetadata({
+			status: state.failed ? ExecutionStepStatus.enum.failed : ExecutionStepStatus.enum.success,
+			stepOutputs: Object.fromEntries(outputsMap),
+			startTime,
+			...state.failedStepName && { failedStep: state.failedStepName },
+			...state.failureReason && { reason: state.failureReason }
+		});
+		state = await runCompletionHook({
+			hook: jobHooks.cleanup,
+			hookType: "cleanup",
+			hookStepIndex,
+			outcome: cleanupOutcome,
+			state,
+			promoteToFailed: true,
+			opts
+		});
+	}
+	return state;
+}
+/**
+* Execute the step loop with hook integration and step-level rule evaluation.
+*
+* Hook execution order:
+* - beforeStep -> step -> afterStep (per step)
+* - onSuccess or onFailure (after all steps)
+* - cleanup (always, after onSuccess/onFailure)
+*
+* Hooks are observers: beforeStep/afterStep failures do NOT affect step execution.
+* Only completion hooks (onSuccess/onFailure/cleanup) can change job status to failed.
+*/
+async function executeStepLoop(opts) {
+	const startTime = opts.startTime ?? Date.now();
+	const stepResults = [];
+	const state = { failed: false };
+	for (const [i, step] of opts.steps.entries()) {
+		if (opts.isAborted?.()) break;
+		const outcome = await runStepIteration(step, i, opts);
+		stepResults.push(outcome.result);
+		if (outcome.failedStepName) {
+			state.failed = true;
+			state.failedStepName = outcome.failedStepName;
+		}
+		if (outcome.shouldBreak) break;
+	}
+	if (opts.isAborted?.()) return {
+		status: "aborted",
+		stepResults,
+		failureReason: state.failureReason ?? (state.failed ? `Step '${state.failedStepName}' failed` : void 0)
+	};
+	const finalState = await runJobCompletionHooks(opts, state, opts.outputsMap, startTime);
+	return {
+		status: finalState.failed ? ExecutionStepStatus.enum.failed : ExecutionStepStatus.enum.success,
+		stepResults,
+		failureReason: finalState.failureReason
+	};
+}
+//#endregion
+//#region src/checkout/ssh-auth.ts
+/**
+* Materialize an SSH private key (and optional pinned known_hosts) into a
+* tempdir and build the `GIT_SSH_COMMAND` that `git clone` needs.
+*
+* Permissions:
+*   - private key mode 0o600 (required by OpenSSH — refuses to use world-
+*     readable keys).
+*   - known_hosts mode 0o600.
+*   - tempdir mode 0o700.
+*
+* SSH flags composed:
+*   - `-i <keyfile>` — identity file.
+*   - `-o IdentitiesOnly=yes` — don't try other keys from ssh-agent / ~/.ssh.
+*   - `-o BatchMode=yes` — never prompt for passwords / passphrases.
+*   - host-key checking flags based on `hostKeyPolicy`.
+*/
+async function setupSshAuth(opts) {
+	if (opts.hostKeyPolicy === "pinned" && !opts.knownHosts) throw new Error("pinned hostKeyPolicy requires knownHosts content");
+	const tempDir = await mkdtemp(join(tmpdir(), "kici-ssh-"));
+	const keyPath = join(tempDir, "id");
+	await writeFile(keyPath, opts.privateKey.endsWith("\n") ? opts.privateKey : `${opts.privateKey}\n`, { mode: 384 });
+	const knownHostsPath = join(tempDir, "known_hosts");
+	await writeFile(knownHostsPath, opts.hostKeyPolicy === "pinned" ? opts.knownHosts : "", { mode: 384 });
+	const parts = [
+		"ssh",
+		"-i",
+		escapeShellArg(keyPath),
+		"-o",
+		"IdentitiesOnly=yes",
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		`UserKnownHostsFile=${escapeShellArg(knownHostsPath)}`
+	];
+	if (opts.hostKeyPolicy === "pinned") parts.push("-o", "StrictHostKeyChecking=yes");
+	else parts.push("-o", "StrictHostKeyChecking=accept-new");
+	return {
+		gitSshCommand: parts.join(" "),
+		tempDir,
+		async cleanup() {
+			await rm(tempDir, {
+				recursive: true,
+				force: true
+			});
+		}
+	};
+}
+/**
+* Quote a path for inclusion in `GIT_SSH_COMMAND`. We use single-quote
+* wrapping so backslashes and spaces survive git's shell-parse of the
+* command value.
+*/
+function escapeShellArg(value) {
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}
+//#endregion
+//#region src/checkout/git-clone.ts
+/**
+* Strip auth credentials from git error messages to prevent token leakage.
+* Node's execFileSync includes the full command line (including -c http.extraHeader
+* and GIT_SSH_COMMAND flags) in error messages, which would expose Base64-encoded
+* tokens or the absolute path of a temporary SSH key file in logs.
+*/
+function sanitizeGitError(error) {
+	if (!(error instanceof Error)) return new Error(String(error));
+	const sanitized = new Error(redactSensitive(error.message));
+	sanitized.stack = error.stack ? redactSensitive(error.stack) : void 0;
+	return sanitized;
+}
+function redactSensitive(input) {
+	return input.replace(/http\.extraHeader=Authorization: Basic \S+/g, "http.extraHeader=Authorization: Basic [REDACTED]").replace(/'[^']*kici-ssh-[^']*'/g, "'[REDACTED_SSH_PATH]'").replace(/\S*kici-ssh-\S+/g, "[REDACTED_SSH_PATH]");
+}
+/**
+* Shallow-clone a git repository at a specific ref with optional token auth.
+*
+* Token authentication uses git's `-c http.extraHeader` mechanism which keeps
+* the token out of the clone URL (not visible in `git remote -v` or logs).
+*
+* After clone, verifies that HEAD matches the expected SHA to prevent
+* wrong-ref execution.
+*
+* @throws Error if clone fails or SHA does not match
+*/
+async function gitClone(options) {
+	const { repoUrl, ref, sha, workDir, token, gitAuth, depth = 1 } = options;
+	const auth = gitAuth ? gitAuth : token ? {
+		kind: "basic",
+		user: "x-access-token",
+		secret: token
+	} : void 0;
+	const args = [];
+	const envEntries = {};
+	let needsCustomEnv = false;
+	let safeDirCleanup;
+	if (repoUrl.startsWith("file://")) {
+		const { mkdtemp, writeFile, rm } = await import("node:fs/promises");
+		const { tmpdir } = await import("node:os");
+		const path = await import("node:path");
+		const dir = await mkdtemp(path.join(tmpdir(), "kici-gitcfg-"));
+		const cfgPath = path.join(dir, "config");
+		await writeFile(cfgPath, "[safe]\n	directory = *\n", { mode: 384 });
+		envEntries.GIT_CONFIG_GLOBAL = cfgPath;
+		needsCustomEnv = true;
+		safeDirCleanup = async () => {
+			await rm(dir, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+		};
+	}
+	let sshSetup;
+	try {
+		if (auth?.kind === "basic") {
+			const user = auth.user ?? "x-access-token";
+			const basic = Buffer.from(`${user}:${auth.secret}`).toString("base64");
+			args.push("-c", `http.extraHeader=Authorization: Basic ${basic}`);
+		} else if (auth?.kind === "ssh") {
+			sshSetup = await setupSshAuth({
+				privateKey: auth.secret,
+				hostKeyPolicy: auth.sshHostKeyPolicy,
+				knownHosts: auth.sshKnownHostsPem
+			});
+			envEntries.GIT_SSH_COMMAND = sshSetup.gitSshCommand;
+			needsCustomEnv = true;
+		}
+		const env = needsCustomEnv ? {
+			...process.env,
+			...envEntries
+		} : void 0;
+		if (ref) args.push("clone", "--depth", String(depth), "--branch", ref, repoUrl, workDir);
+		else args.push("clone", "--depth", String(depth), repoUrl, workDir);
+		const { execFileSync } = await import("node:child_process");
+		try {
+			execFileSync("git", args, {
+				stdio: "pipe",
+				timeout: 12e4,
+				...env && { env }
+			});
+		} catch (err) {
+			throw sanitizeGitError(err);
+		}
+		if (!sha || sha === "HEAD") return;
+		const envOpts = env ? { env } : {};
+		if (!execFileSync("git", [
+			"-C",
+			workDir,
+			"rev-parse",
+			"HEAD"
+		], {
+			encoding: "utf-8",
+			timeout: 1e4,
+			...envOpts
+		}).trim().startsWith(sha)) {
+			const fetchArgs = [];
+			if (auth?.kind === "basic") {
+				const user = auth.user ?? "x-access-token";
+				const basic = Buffer.from(`${user}:${auth.secret}`).toString("base64");
+				fetchArgs.push("-c", `http.extraHeader=Authorization: Basic ${basic}`);
+			}
+			fetchArgs.push("fetch", "--depth", "50", "origin", sha);
+			try {
+				execFileSync("git", [
+					"-C",
+					workDir,
+					...fetchArgs
+				], {
+					stdio: "pipe",
+					timeout: 12e4,
+					...envOpts
+				});
+			} catch (err) {
+				throw sanitizeGitError(err);
+			}
+			execFileSync("git", [
+				"-C",
+				workDir,
+				"checkout",
+				sha
+			], {
+				stdio: "pipe",
+				timeout: 3e4,
+				...envOpts
+			});
+			const recheckedSha = execFileSync("git", [
+				"-C",
+				workDir,
+				"rev-parse",
+				"HEAD"
+			], {
+				encoding: "utf-8",
+				timeout: 1e4,
+				...envOpts
+			}).trim();
+			if (!recheckedSha.startsWith(sha)) throw new Error(`SHA mismatch: expected ${sha}, got ${recheckedSha}`);
+		}
+	} finally {
+		if (sshSetup) await sshSetup.cleanup().catch(() => {});
+		if (safeDirCleanup) await safeDirCleanup();
+	}
+}
+//#endregion
+//#region src/execution/dep-restore.ts
+/**
+* Dependency restoration from cached tarballs.
+*
+* Downloads a pre-built dependency tarball, verifies SHA-256 integrity,
+* and extracts to .kici/node_modules/ in the work directory.
+*
+* HTTP/HTTPS downloads use a streaming pipeline (response -> hash transform ->
+* gunzip -> tar extract) to avoid buffering entire tarballs in memory.
+* file:// URLs use a buffer-based approach (local, no streaming benefit).
+*
+* Streaming downloads have a 5-minute timeout and up to 2 retries.
+*/
+const logger$3 = createLogger({ prefix: "dep-restore" });
+/** Download timeout: 5 minutes. */
+const DOWNLOAD_TIMEOUT_MS$1 = 300 * 1e3;
+/**
+* Compute SHA-256 hash of a buffer.
+*/
+function computeHash(data) {
+	return sha256(data);
+}
+/**
+* Extract a gzip tarball from a buffer into the target directory.
+* Used for file:// URLs where streaming provides no benefit.
+*/
+async function extractTarball(data, targetDir) {
+	await mkdir(targetDir, { recursive: true });
+	const readable = Readable.from(data);
+	await new Promise((resolve, reject) => {
+		readable.pipe(x({
+			cwd: targetDir,
+			gzip: true
+		})).on("finish", resolve).on("error", reject);
+	});
+}
+/**
+* Stream download and extract an HTTP/HTTPS tarball.
+*
+* Computes SHA-256 hash on the fly via a Transform stream.
+* Returns the computed hash of the compressed tarball data.
+*/
+async function streamFetchAndExtract(url, targetDir) {
+	const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS$1) });
+	if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+	if (!response.body) throw new Error("No response body");
+	const nodeStream = Readable.fromWeb(response.body);
+	const hash = createHash("sha256");
+	const hashTransform = new Transform({ transform(chunk, _encoding, callback) {
+		hash.update(chunk);
+		callback(null, chunk);
+	} });
+	await mkdir(targetDir, { recursive: true });
+	await pipeline(nodeStream, hashTransform, createGunzip(), x({ cwd: targetDir }));
+	return hash.digest("hex");
+}
+/**
+* Path-relative-to-`.kici/` glob that matches every scratch dir
+* `extractIntoScratch` may create. Surfaced so the clone phase can register
+* it in `.git/info/exclude` (see `excludeScratchFromGit`) — keeping the glob
+* and the exclude rule in the same file means future renames of the scratch
+* dir prefix can't fall out of sync with the git-ignore wiring.
+*/
+const SCRATCH_DIR_BASENAME_PREFIX = ".dep-restore-scratch-";
+/**
+* Glob suitable for `.gitignore` / `.git/info/exclude` that matches every
+* scratch dir created by `extractIntoScratch`, anchored to the workflow
+* working tree's `.kici/` subdir.
+*/
+const SCRATCH_DIR_GIT_EXCLUDE_GLOB = `.kici/${SCRATCH_DIR_BASENAME_PREFIX}*`;
+/**
+* Extract the dep tarball into a per-attempt scratch dir so retries never race
+* with still-draining I/O from a previous failed attempt.
+*
+* When `pipeline()` rejects on a network error or AbortSignal timeout, the
+* underlying `tar.x` continues flushing pending file writes for an unbounded
+* window after the promise settles — `pipeline` does not block on async
+* filesystem side effects. If the next retry then runs `rm -rf` on the same
+* `node_modules/`, the walk races with those writes and `rmdir` fails with
+* ENOTEMPTY (new files keep appearing under a directory we just emptied).
+*
+* We sidestep the race entirely by extracting each attempt into a unique
+* scratch dir under `.kici/`. Failed attempts leave orphan scratch dirs whose
+* draining writes are harmless — the next attempt does not touch them. On
+* success we `fs.rename` `${scratchDir}/node_modules` into the final location
+* (atomic on the same filesystem), then best-effort clean the scratch dir.
+*
+* Scratch dirs land inside the customer's cloned working tree, so the clone
+* phase registers `SCRATCH_DIR_GIT_EXCLUDE_GLOB` in `.git/info/exclude` to
+* keep them out of `git status` for any workflow step that shells out to git.
+* See `excludeScratchFromGit`.
+*/
+async function extractIntoScratch(url, kiciDir, attempt) {
+	const scratchDir = join(kiciDir, `${SCRATCH_DIR_BASENAME_PREFIX}${process.pid}-${attempt}-${Date.now()}`);
+	await mkdir(scratchDir, { recursive: true });
+	return {
+		scratchDir,
+		hash: await streamFetchAndExtract(url, scratchDir)
+	};
+}
+/**
+* Append `SCRATCH_DIR_GIT_EXCLUDE_GLOB` to `${repoWorkDir}/.git/info/exclude`
+* so any in-flight or orphaned dep-restore scratch dirs are invisible to
+* `git status` / `git add` inside the customer's cloned working tree.
+*
+* Why `.git/info/exclude` and not `.gitignore`:
+* - `.gitignore` lives in the customer's repo and is committed; we MUST NOT
+*   modify it. Doing so would surface the rule in their PRs and create a
+*   diff customers never asked for.
+* - `.git/info/exclude` is per-clone, on-disk only, and exactly the git
+*   mechanism for "ignore these patterns in THIS working tree". Git creates
+*   an empty (template-commented) file on `git init` / `git clone`, so it
+*   already exists by the time we're called.
+*
+* Why this lives next to `extractIntoScratch`:
+* - The exclude glob is tied 1:1 to the scratch dir naming convention. If
+*   the prefix ever changes, the rule must change too. Defining both in the
+*   same file means a rename touches one place, not two.
+*
+* Best-effort: if the exclude file is missing (e.g. caller sandbox blocked
+* `git clone` and the dir layout differs) we log and continue — failing the
+* job over a missing git ignore wiring would be worse than the cosmetic
+* issue we're solving.
+*
+* Idempotent: callers may invoke this multiple times (dual-clone path, retry
+* after partial setup). We skip the append if the glob is already present.
+*
+* @param repoWorkDir - The git working tree root (the dir that contains
+*   `.git/`). For normal workflows this is the agent's job workDir; for
+*   global workflows it is the workflow repo dir (whose `.kici/` carries
+*   the scratch dirs).
+*/
+async function excludeScratchFromGit(repoWorkDir) {
+	const excludePath = join(repoWorkDir, ".git", "info", "exclude");
+	try {
+		const existing = await fsPromises.readFile(excludePath, "utf-8").catch(() => "");
+		if (existing.split("\n").some((line) => line.trim() === SCRATCH_DIR_GIT_EXCLUDE_GLOB)) return;
+		const suffix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+		await fsPromises.appendFile(excludePath, `${suffix}# kici: hide dep-restore scratch dirs from customer git status\n${SCRATCH_DIR_GIT_EXCLUDE_GLOB}\n`);
+	} catch (err) {
+		logger$3.warn("Failed to register scratch dir glob in .git/info/exclude", {
+			excludePath,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+}
+/**
+* Rewrite localhost URLs to use the orchestrator host.
+*
+* The orchestrator rewrites file:// cache URLs to http://localhost:PORT/...
+* but agent containers can't reach localhost. This utility replaces the
+* host with the orchestrator's host derived from KICI_ORCHESTRATOR_URL.
+*/
+function resolveOrchestratorUrl(url) {
+	if (!url.match(/^https?:\/\/(localhost|127\.0\.0\.1)[:/]/)) return url;
+	const orchestratorUrl = process.env.KICI_ORCHESTRATOR_URL;
+	if (!orchestratorUrl) return url;
+	try {
+		const orchestratorParsed = new URL(orchestratorUrl.replace(/^ws/, "http"));
+		const parsed = new URL(url);
+		parsed.hostname = orchestratorParsed.hostname;
+		return parsed.toString();
+	} catch {
+		return url;
+	}
+}
+/**
+* Restore dependencies from a cached tarball.
+*
+* For HTTP/HTTPS URLs: uses a streaming pipeline (response -> hash -> gunzip -> tar)
+* with a 5-minute timeout and up to 2 retries. This avoids buffering entire tarballs
+* in memory, eliminating memory spikes proportional to tarball size.
+*
+* For file:// URLs: uses a buffer-based approach (local, no streaming benefit).
+*
+* @param workDir - Root directory of the cloned repository
+* @param depsUrl - URL to the dependency tarball (http://, https://, or file://)
+* @param depsHash - Optional expected SHA-256 hash of the tarball
+*/
+async function restoreDeps(workDir, depsUrl, depsHash) {
+	depsUrl = resolveOrchestratorUrl(depsUrl);
+	logger$3.info("Downloading dependency tarball", { url: depsUrl });
+	const kiciDir = join(workDir, ".kici");
+	if (depsUrl.startsWith("file://")) {
+		const localPath = fileURLToPath(depsUrl);
+		const data = await fsPromises.readFile(localPath);
+		if (depsHash) {
+			const actualHash = computeHash(data);
+			if (actualHash !== depsHash) throw new Error(`Dep tarball hash mismatch: expected ${depsHash}, got ${actualHash}`);
+		}
+		await extractTarball(data, kiciDir);
+		const sizeMB = (data.length / (1024 * 1024)).toFixed(2);
+		logger$3.info("Dependencies restored from cache (file)", {
+			sizeMB,
+			targetDir: kiciDir
+		});
+		return;
+	}
+	if (!depsUrl.startsWith("http://") && !depsUrl.startsWith("https://")) throw new Error(`Unsupported deps URL scheme: ${depsUrl}`);
+	let lastError;
+	for (let attempt = 0; attempt <= 2; attempt++) {
+		if (attempt > 0) logger$3.warn("Retrying dep tarball download", {
+			attempt,
+			url: depsUrl
+		});
+		try {
+			const { scratchDir, hash } = await extractIntoScratch(depsUrl, kiciDir, attempt);
+			if (depsHash && hash !== depsHash) throw new Error(`Dep tarball hash mismatch: expected ${depsHash}, got ${hash}`);
+			await fsPromises.rename(join(scratchDir, "node_modules"), join(kiciDir, "node_modules"));
+			try {
+				await fsPromises.rm(scratchDir, {
+					recursive: true,
+					force: true
+				});
+			} catch (cleanupErr) {
+				logger$3.warn("Scratch dir cleanup failed (orphan left behind)", {
+					scratchDir,
+					error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
+				});
+			}
+			logger$3.info("Dependencies restored from cache (stream)", { targetDir: kiciDir });
+			return;
+		} catch (err) {
+			lastError = err instanceof Error ? err : new Error(String(err));
+			logger$3.warn("Dep tarball download failed", {
+				attempt,
+				error: lastError.message
+			});
+		}
+	}
+	throw new Error(`Dep tarball download failed after 3 attempts: ${lastError?.message}`);
+}
+//#endregion
+//#region src/execution/npm-resolver.ts
+/**
+* Resolve the npm CLI path relative to the running Node.js binary.
+*
+* Used both at startup (builder role readiness check) and at install time
+* (dep-installer). Centralizes the resolution logic so it stays consistent.
+*
+* Resolution strategy:
+* 1. Check standard Node.js layout paths relative to process.execPath
+* 2. Fall back to bare 'npm' on PATH (development environments)
+*/
+/**
+* Resolve the npm CLI path from the current Node.js binary.
+*
+* Checks standard Node.js distribution layout paths:
+* - {nodeDir}/../lib/node_modules/npm/bin/npm-cli.js (Linux/macOS installed)
+* - {nodeDir}/node_modules/npm/bin/npm-cli.js (Windows / some layouts)
+*
+* Returns undefined npmCliPath if neither is found (caller can fall back to PATH).
+*/
+function resolveNpm() {
+	const nodeExe = process.execPath;
+	const nodeDir = dirname(nodeExe);
+	return {
+		npmCliPath: [join(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"), join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js")].find((p) => existsSync(p)),
+		nodeExe,
+		nodeDir
+	};
+}
+//#endregion
+//#region src/execution/npm-registry-config.ts
+/**
+* Apply private-npm-registry auth to a workflow's `.kici/.npmrc` for the
+* lifetime of one `npm install` invocation, then restore the file on cleanup.
+*
+* Why a closure-cleanup pattern (mirrors `setupSshAuth.cleanup()` in
+* `packages/agent/src/checkout/git-clone.ts`): the customer's committed
+* `.kici/.npmrc` may carry literal `${VAR}` placeholders or an unrelated
+* scope mapping. We must NOT clobber it permanently — we just want to
+* append the agent-managed registry/auth lines for this single install,
+* then revert.
+*
+* Token bytes never end up in the on-disk `.npmrc`. Each registry's token
+* is exposed as a job-scoped env var (`KICI_NPM_TOKEN_${jobIdShort}_<i>`)
+* and the on-disk auth line carries the env var reference (`${VAR}`). npm
+* substitutes at read time. The job-scoped nonce makes the env var name
+* unguessable from outside the install subprocess.
+*
+* Merge order: customer-committed `.npmrc` lines come FIRST, agent-generated
+* lines come LAST. npm's last-wins semantics make the agent's line shadow
+* any literal `_authToken=...` the customer accidentally committed for a
+* registry KiCI manages — refuses to let a committed secret beat a managed
+* one.
+*
+* `installEnvSecrets` is a separate channel for customers who prefer the
+* "commit a `.kici/.npmrc` with `${MY_TOKEN}` and supply MY_TOKEN as a
+* scoped secret" pattern (Option C in the design doc). Each entry becomes
+* an env var on the install subprocess; the customer's existing `.npmrc`
+* uses it as `${MY_TOKEN}`.
+*/
+/** No-op result returned when nothing needs to be applied. */
+function noopResult() {
+	return {
+		extraEnv: {},
+		tokensForRedaction: [],
+		cleanup: async () => {}
+	};
+}
+/** Build the synthesized env-var name for registry index `i`. */
+function tokenEnvName(jobIdShort, index) {
+	return `KICI_NPM_TOKEN_${jobIdShort}_${index}`;
+}
+/** Render the agent-managed block of `.npmrc` lines. */
+function renderAgentLines(registries, jobIdShort) {
+	if (registries.length === 0) return "";
+	const lines = [];
+	for (let i = 0; i < registries.length; i++) {
+		const reg = registries[i];
+		const envVar = tokenEnvName(jobIdShort, i);
+		const authKey = reg.url.replace(/^https?:/, "");
+		if (reg.scope) lines.push(`${reg.scope}:registry=${reg.url}`);
+		else lines.push(`registry=${reg.url}`);
+		lines.push(`${authKey}:_authToken=\${${envVar}}`);
+		if (reg.alwaysAuth) lines.push(`${authKey}:always-auth=true`);
+	}
+	return `# kici-managed: applied for one npm install only\n${lines.join("\n")}\n`;
+}
+/** Read original `.npmrc` bytes; null if the file does not exist. */
+async function readOriginalNpmrc(npmrcPath) {
+	try {
+		return await readFile(npmrcPath, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
+* Apply the merged `.npmrc` and return env + redaction + cleanup. Caller
+* runs the npm install with `extraEnv` merged in, then awaits cleanup()
+* inside the install's `finally`.
+*/
+async function applyNpmRegistryConfig(args) {
+	const registries = args.npmRegistries ?? [];
+	const installEnvSecrets = args.installEnvSecrets ?? {};
+	if (registries.length === 0 && Object.keys(installEnvSecrets).length === 0) return noopResult();
+	const npmrcPath = join(args.kiciDir, ".npmrc");
+	const original = await readOriginalNpmrc(npmrcPath);
+	const tokenEnv = {};
+	const tokensForRedaction = [];
+	for (let i = 0; i < registries.length; i++) {
+		tokenEnv[tokenEnvName(args.jobIdShort, i)] = registries[i].token;
+		tokensForRedaction.push(registries[i].token);
+	}
+	for (const value of Object.values(installEnvSecrets)) if (value) tokensForRedaction.push(value);
+	const agentBlock = renderAgentLines(registries, args.jobIdShort);
+	const merged = `${original ?? ""}${original && !original.endsWith("\n") ? "\n" : ""}${agentBlock}`;
+	if (agentBlock.length > 0) await writeFile(npmrcPath, merged, {
+		encoding: "utf8",
+		mode: 384
+	});
+	const cleanup = async () => {
+		if (agentBlock.length === 0) return;
+		try {
+			if (original === null) await unlink(npmrcPath).catch(() => {});
+			else await writeFile(npmrcPath, original, { encoding: "utf8" });
+		} catch {}
+	};
+	return {
+		extraEnv: {
+			...installEnvSecrets,
+			...tokenEnv
+		},
+		tokensForRedaction,
+		cleanup
+	};
+}
+/** Mask every token in `tokensForRedaction` out of `input` before logging. */
+function redactNpmOutput(input, tokens) {
+	if (!input) return input;
+	let out = input;
+	for (const token of tokens) {
+		if (!token) continue;
+		out = out.split(token).join("***REDACTED***");
+	}
+	return out;
+}
+//#endregion
+//#region src/execution/dep-installer.ts
+/**
+* Inline dependency installation for graceful degradation.
+*
+* When dep cache is unavailable or download fails, the agent falls back
+* to running npm install directly.
+*
+* Only npm is supported — it ships with every Node.js installation.
+* .kici/package.json is required — its presence signals deps should be installed.
+*
+* Security: npm runs with an isolated per-invocation cache directory to prevent
+* cache poisoning across build jobs. A malicious package.json in one repo cannot
+* taint the cache used by subsequent builds. The same pressure rules out letting
+* lifecycle scripts see synthesized auth env vars — npm runs with
+* `--ignore-scripts` whenever a private registry is configured.
+*/
+const logger$2 = createLogger({ prefix: "dep-installer" });
+/**
+* Install dependencies inline using npm.
+*
+* Falls back to this when the dep cache is unavailable or download fails.
+*
+* npm runs with an isolated cache directory (created in os.tmpdir()) to prevent
+* cache poisoning between build jobs. The cache is removed after installation.
+*
+* If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, the helper
+* synthesizes a job-scoped `.kici/.npmrc` overlay for the install, restores
+* the original file in `finally`, and runs npm with `--ignore-scripts` so
+* lifecycle scripts in committed `package.json` cannot exfiltrate the
+* synthesized token env vars.
+*
+* @param kiciDir - Path to the .kici/ directory containing package.json
+* @param opts    - Optional registry / installEnv configuration. When absent,
+*                  behavior is identical to the pre-private-registry version.
+*/
+async function installDeps(kiciDir, opts = {}) {
+	logger$2.info("Installing deps inline", {
+		packageManager: "npm",
+		dir: kiciDir
+	});
+	process.stderr.write(`[dep-installer:trace] starting install: pm=npm, cwd=${kiciDir}\n`);
+	const startTime = Date.now();
+	const hasPrivateRegistry = (opts.npmRegistries?.length ?? 0) > 0 || (opts.installEnvSecrets ? Object.keys(opts.installEnvSecrets).length > 0 : false);
+	const registryConfig = await applyNpmRegistryConfig({
+		kiciDir,
+		npmRegistries: opts.npmRegistries,
+		installEnvSecrets: opts.installEnvSecrets,
+		jobIdShort: opts.jobIdShort ?? "00000000"
+	});
+	try {
+		const { npmCliPath, nodeExe, nodeDir } = resolveNpm();
+		const npmCmd = "install";
+		const cacheDir = await mkdtemp(join(tmpdir(), "kici-npm-cache-"));
+		const { NODE_ENV: _, ...restEnv } = process.env;
+		const envWithNode = {
+			...restEnv,
+			...registryConfig.extraEnv,
+			PATH: `${nodeDir}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
+		};
+		const { execFileSync: execFile } = await import("node:child_process");
+		const buildArgs = (...prefix) => {
+			const args = [
+				...prefix,
+				npmCmd,
+				"--cache",
+				cacheDir
+			];
+			if (hasPrivateRegistry) args.push("--ignore-scripts");
+			return args;
+		};
+		try {
+			if (npmCliPath) {
+				process.stderr.write(`[dep-installer:trace] running: ${nodeExe} ${npmCliPath} ${npmCmd} --cache ${cacheDir}${hasPrivateRegistry ? " --ignore-scripts" : ""}\n`);
+				execFile(nodeExe, buildArgs(npmCliPath), {
+					cwd: kiciDir,
+					env: envWithNode,
+					timeout: 6e5,
+					stdio: "pipe"
+				});
+			} else {
+				process.stderr.write(`[dep-installer:trace] running: npm ${npmCmd} --cache ${cacheDir}${hasPrivateRegistry ? " --ignore-scripts" : ""}\n`);
+				execFile("npm", buildArgs(), {
+					cwd: kiciDir,
+					env: envWithNode,
+					timeout: 6e5,
+					stdio: "pipe"
+				});
+			}
+		} finally {
+			await rm(cacheDir, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+		}
+	} catch (e) {
+		const msg = toErrorMessage(e);
+		const tokens = registryConfig.tokensForRedaction;
+		process.stderr.write(`[dep-installer:trace] INSTALL FAILED: ${redactNpmOutput(msg, tokens)}\n`);
+		if (e && typeof e === "object" && "stdout" in e) process.stderr.write(`[dep-installer:trace] stdout: ${redactNpmOutput(String(e.stdout), tokens).slice(0, 500)}\n`);
+		if (e && typeof e === "object" && "stderr" in e) process.stderr.write(`[dep-installer:trace] stderr: ${redactNpmOutput(String(e.stderr), tokens).slice(0, 500)}\n`);
+		throw e;
+	} finally {
+		await registryConfig.cleanup();
+	}
+	const durationMs = Date.now() - startTime;
+	process.stderr.write(`[dep-installer:trace] install complete: ${durationMs}ms\n`);
+	logger$2.info("Deps installed inline", {
+		packageManager: "npm",
+		durationMs
+	});
+}
+//#endregion
+//#region src/execution/workflow-loader.ts
+/**
+* Workflow module loading: transforms `.ts` workflow files on import via the
+* shared oxc-transform ESM loader hook. Customer workflow code is imported
+* directly from the cloned / extracted source tree — no intermediate bundle,
+* 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.1";
+const AGENT_SDK_BUNDLE_HASH = "675aafe4de03e677785ef2794d8f34951b14e2bd1e6f0ea825953d6c2abfe128";
+/**
+* Register the shared oxc-transform ESM loader hook so subsequent dynamic
+* `import()` calls for `.ts` / `.tsx` files transform on the fly. Idempotent
+* at our level via the `hookRegistered` flag; Node also tolerates repeated
+* `register()` calls by stacking layers, but we avoid the noise.
+*/
+let hookRegistered = false;
+function ensureLoaderHookRegistered() {
+	if (hookRegistered) return;
+	register("@kici-dev/shared/ts-loader-hook", import.meta.url);
+	hookRegistered = true;
+}
+/**
+* Compute content hash for a workflow (same formula as `@kici-dev/compiler`
+* lockfile/hasher.ts). Used to verify the loaded source matches the lock
+* file's contentHash when `expectedContentHash` is provided.
+*
+* Line endings in `rawSource` (and inside `assetDigest`) are normalized to LF
+* before hashing. This matches the compiler-side normalization in
+* `@kici-dev/compiler` `lockfile/hasher.ts` so Windows agents — where Git's
+* `core.autocrlf=true` system default checks out text files with CRLF — agree
+* with lockfiles compiled on Linux (LF).
+*/
+function computeContentHash(rawSource, assetDigest) {
+	let input = `5:${normalizeLineEndings(rawSource)}`;
+	if (assetDigest !== void 0 && assetDigest.length > 0) input += `\0${normalizeLineEndings(assetDigest)}`;
+	return sha256(input);
+}
+async function buildAssetDigestFromResolvedPaths(workDir, resolvedPaths) {
+	const parts = [];
+	for (const rel of resolvedPaths) {
+		const abs = path.join(workDir, rel);
+		try {
+			const content = await fsPromises.readFile(abs, "utf-8");
+			parts.push(`${rel}\n${content}`);
+		} catch {
+			parts.push(`${rel}\n`);
+		}
+	}
+	return parts.join("");
+}
+/**
+* Load a workflow module by dynamic-importing its source file.
+*
+* Registers the oxc-transform loader hook (idempotent), then dynamic-imports
+* the `.ts` file. Transitive imports resolve against the workspace's
+* `node_modules/` the same way any `tsx`-style runner would — so host-repo
+* helpers and `@kici-dev/sdk` Just Work.
+*
+* When `expectedContentHash` is provided, verifies the raw source matches
+* the hash in the lock file. Drift between source and lock file produces a
+* descriptive error that surfaces the baked agent SDK fingerprint (useful
+* when debugging "is the agent running a stale build?").
+*/
+async function loadWorkflowSource(workDir, sourceFile, expectedContentHash, resolvedHashFiles) {
+	ensureLoaderHookRegistered();
+	const filePath = path.join(workDir, sourceFile);
+	if (expectedContentHash) {
+		const rawSource = await fsPromises.readFile(filePath, "utf-8");
+		let assetDigest;
+		if (resolvedHashFiles?.length) assetDigest = await buildAssetDigestFromResolvedPaths(workDir, resolvedHashFiles);
+		const actualHash = computeContentHash(rawSource, assetDigest);
+		if (actualHash !== expectedContentHash) throw new Error(`Lock file is out of date: workflow source changed without regenerating kici.lock.json (expected contentHash ${expectedContentHash}, got ${actualHash}, agent baked @kici-dev/sdk@${AGENT_SDK_VERSION} bundleHash=${AGENT_SDK_BUNDLE_HASH}). Run 'kici compile' and commit the updated lock file.`);
+	}
+	return { module: await import(pathToFileURL(filePath).href + `?t=${Date.now()}`) };
+}
+/**
+* Type guard for Workflow shape (discriminant: `_tag === 'Workflow'`).
+*/
+function isWorkflow(value) {
+	return typeof value === "object" && value !== null && "_tag" in value && value._tag === "Workflow";
+}
+/**
+* Extract a workflow by name from a module's exports.
+*
+* Searches:
+* 1. Default export (single Workflow or array of Workflows)
+* 2. Named exports
+*/
+function extractWorkflow(module, workflowName) {
+	if (module.default) {
+		const defaultExport = module.default;
+		if (isWorkflow(defaultExport) && defaultExport.name === workflowName) return defaultExport;
+		if (Array.isArray(defaultExport)) {
+			const found = defaultExport.find((item) => isWorkflow(item) && item.name === workflowName);
+			if (found) return found;
+		}
+	}
+	for (const [, value] of Object.entries(module)) if (isWorkflow(value) && value.name === workflowName) return value;
+	throw new Error(`Workflow '${workflowName}' not found in module exports`);
+}
+/**
+* Extract a dynamic job function from a workflow by index.
+*/
+function extractDynamicJobFn(workflow, index) {
+	if (index < 0 || index >= workflow.jobs.length) throw new Error(`Job index ${index} out of bounds (workflow '${workflow.name}' has ${workflow.jobs.length} jobs)`);
+	const item = workflow.jobs[index];
+	if (!isDynamicJobFn(item)) throw new Error(`Job at index ${index} in workflow '${workflow.name}' is not a dynamic job fn`);
+	return item;
+}
+/**
+* Extract steps from a static job within a workflow.
+*/
+function extractSteps(workflow, jobName) {
+	for (const item of workflow.jobs) if (!isDynamicJobFn(item) && item.name === jobName) return item.steps;
+	throw new Error(`Static job '${jobName}' not found in workflow '${workflow.name}'`);
+}
+/**
+* Extract steps from a job generated by a DynamicJobFn.
+*
+* Re-evaluates the DynamicJobFn to get the generated Job[] array, then finds
+* the job by name and returns its steps. This is necessary because
+* DynamicJobFn-generated jobs' step functions are closures that can only be
+* obtained by calling the DynamicJobFn again.
+*
+* The function must be deterministic: given the same event context, it should
+* return the same jobs with the same step functions. When `expectedJobNames`
+* is provided, the re-evaluated output is compared against the original eval.
+* A sibling mismatch logs a warning; a missing target job throws a clear
+* determinism error.
+*/
+async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event, env, apiTransport, expectedJobNames) {
+	const dynamicFn = extractDynamicJobFn(workflow, dynamicIndex);
+	const { $ } = await import("zx");
+	const { createLogger } = await import("@kici-dev/shared");
+	const { buildKiciApi } = await import("@kici-dev/sdk");
+	const log = createLogger({ prefix: `dynamic-job-fn:${workflow.name}` });
+	const kici = buildKiciApi(apiTransport ?? (() => Promise.reject(/* @__PURE__ */ new Error("Agent API not available during re-evaluation"))));
+	const generatedJobs = await dynamicFn({
+		$,
+		ctx: {
+			workflow: { name: workflow.name },
+			event
+		},
+		log,
+		env,
+		kici
+	});
+	const actualNames = generatedJobs.map((j) => j.name);
+	let droppedJobs = [];
+	if (expectedJobNames) {
+		const expectedSet = new Set(expectedJobNames);
+		const actualSet = new Set(actualNames);
+		const missing = expectedJobNames.filter((n) => !actualSet.has(n));
+		const extra = actualNames.filter((n) => !expectedSet.has(n));
+		droppedJobs = missing.filter((n) => n !== jobName);
+		if (missing.length > 0 || extra.length > 0) {
+			const detail = (missing.length > 0 ? `missing: [${missing.join(", ")}]` : "") + (missing.length > 0 && extra.length > 0 ? "; " : "") + (extra.length > 0 ? `unexpected: [${extra.join(", ")}]` : "");
+			if (missing.includes(jobName)) throw new Error(`DynamicJobFn non-deterministic re-evaluation: job '${jobName}' no longer exists (workflow '${workflow.name}', index ${dynamicIndex}). Original eval produced: [${expectedJobNames.join(", ")}], re-eval produced: [${actualNames.join(", ")}]. DynamicJobFn must return the same jobs given the same event context. See docs/architecture/dynamic-jobs.md for guidance.`);
+			log.warn(`DynamicJobFn non-deterministic re-evaluation detected (workflow '${workflow.name}', index ${dynamicIndex}): ${detail}. Target job '${jobName}' still exists — proceeding. DynamicJobFn should return the same jobs given the same event context.`);
+		}
+	}
+	for (const genJob of generatedJobs) if (genJob.name === jobName) return {
+		steps: genJob.steps,
+		droppedJobs
+	};
+	throw new Error(`Generated job '${jobName}' not found in DynamicJobFn output (workflow '${workflow.name}', index ${dynamicIndex}). Available: ${actualNames.join(", ")}`);
+}
+//#endregion
+//#region src/execution/download.ts
+/**
+* Shared HTTP/HTTPS download utility.
+*
+* Extracted from workflow-loader.ts to avoid duplication across
+* dep-restore.ts and workflow-loader.ts.
+*/
+/** Download timeout: 5 minutes. */
+const DOWNLOAD_TIMEOUT_MS = 300 * 1e3;
+/**
+* Download content from an HTTP/HTTPS URL.
+*
+* Includes a 5-minute timeout to prevent the agent from hanging indefinitely
+* on slow or unresponsive endpoints.
+*
+* @param url - The URL to download from
+* @returns The response body as a Buffer
+*/
+function downloadUrl(url) {
+	return new Promise((resolve, reject) => {
+		(url.startsWith("https:") ? https : http).get(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) }, (res) => {
+			if (res.statusCode && (res.statusCode < 200 || res.statusCode >= 300)) {
+				reject(/* @__PURE__ */ new Error(`HTTP ${res.statusCode} downloading from ${url}`));
+				res.resume();
+				return;
+			}
+			const chunks = [];
+			res.on("data", (chunk) => chunks.push(chunk));
+			res.on("end", () => resolve(Buffer.concat(chunks)));
+			res.on("error", reject);
+		}).on("error", reject);
+	});
+}
+//#endregion
+//#region src/execution/source-restore.ts
+/**
+* `.kici/` source tarball restoration for execution agents.
+*
+* Downloads a pre-built `.kici/` source tarball from the orchestrator's cache
+* and extracts it into `workDir/` so the workflow entry point becomes
+* importable. Mirrors the shape of `dep-restore.ts` but without the streaming
+* optimization — source tarballs are tiny (kilobytes, not the hundreds of
+* megabytes a `node_modules/` tarball carries).
+*
+* Note on integrity: `dispatch.sourceTarHash` is the workflow `contentHash`
+* (computed over the raw source per `workflow-loader.ts::computeContentHash`),
+* not the SHA-256 of the tarball bytes. The shared S3 cache key is derived
+* from that same contentHash, so a signed GET URL from the orchestrator
+* already establishes provenance for restored tarballs. Every
+* `loadWorkflowSource` call site — build, init, and dynamic eval — passes
+* the dispatched `contentHash` (and `resolvedHashFiles` when present) so
+* the lock-vs-source drift gate fires at each author-TS load site, not
+* only the build phase. That closes the corner cases where init or eval
+* runs without a preceding build (cache infrastructure unavailable, or a
+* build job that failed but left dynamic dispatch in flight).
+*/
+const logger$1 = createLogger({ prefix: "source-restore" });
+async function extractSourceTarball(data, targetDir) {
+	await mkdir(targetDir, { recursive: true });
+	const readable = Readable.from(data);
+	await new Promise((resolve, reject) => {
+		readable.pipe(x({
+			cwd: targetDir,
+			gzip: true
+		})).on("finish", resolve).on("error", reject);
+	});
+}
+async function restoreSource(workDir, sourceTarUrl) {
+	sourceTarUrl = resolveOrchestratorUrl(sourceTarUrl);
+	logger$1.info("Restoring .kici/ source from tarball", { sourceTarUrl });
+	const startTime = Date.now();
+	let data;
+	if (sourceTarUrl.startsWith("file://")) {
+		const localPath = fileURLToPath(sourceTarUrl);
+		data = await fsPromises.readFile(localPath);
+	} else if (sourceTarUrl.startsWith("http://") || sourceTarUrl.startsWith("https://")) data = await downloadUrl(sourceTarUrl);
+	else throw new Error(`Unsupported source tarball URL scheme: ${sourceTarUrl}`);
+	await extractSourceTarball(data, workDir);
+	const durationMs = Date.now() - startTime;
+	logger$1.info(".kici/ source restored", {
+		sizeKB: (data.length / 1024).toFixed(2),
+		durationMs
+	});
+}
+//#endregion
+//#region src/execution/overlay-applier.ts
+/**
+* Agent-side overlay application.
+*
+* Downloads an encrypted tarball uploaded by the CLI, decrypts it using
+* X25519 ECDH shared secret, verifies file checksums from the manifest,
+* and applies the overlay (file additions/modifications + deletions)
+* on top of the cloned repository.
+*
+* Wire format: [12-byte IV][16-byte auth tag][ciphertext]
+* Same encryption scheme as packages/compiler/src/remote/encryption.ts.
+*/
+const logger = createLogger({ prefix: "overlay-applier" });
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+/**
+* Decrypt an encrypted buffer using AES-256-GCM.
+*
+* Wire format: [12-byte IV][16-byte auth tag][ciphertext]
+*/
+function decryptBuffer(encrypted, aesKey) {
+	if (encrypted.length < IV_LENGTH + AUTH_TAG_LENGTH) throw new Error(`Tarball decryption failed: encrypted data too short (${encrypted.length} bytes, minimum ${IV_LENGTH + AUTH_TAG_LENGTH} bytes)`);
+	const iv = encrypted.subarray(0, IV_LENGTH);
+	const authTag = encrypted.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+	const ciphertext = encrypted.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+	const decipher = crypto.createDecipheriv("aes-256-gcm", aesKey, iv);
+	decipher.setAuthTag(authTag);
+	try {
+		return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+	} catch (err) {
+		throw new Error(`Tarball decryption failed: ${toErrorMessage(err)}`);
+	}
+}
+/**
+* Apply an overlay tarball to a cloned repository.
+*
+* Flow:
+* 1. Download encrypted tarball from tarballUrl
+* 2. Derive ECDH shared secret from orchestratorPrivateKey + cliPublicKey
+* 3. Decrypt tarball using AES-256-GCM
+* 4. Extract tar.gz to temp directory
+* 5. Read manifest.json and verify checksums
+* 6. Copy files to repoDir preserving directory structure
+* 7. Apply deletions from manifest
+* 8. Clean up temp files
+*/
+async function applyOverlay(config) {
+	const { tarballUrl, cliPublicKey, orchestratorPrivateKey, repoDir } = config;
+	const tmpDir = await fsPromises.mkdtemp(path.join(os.tmpdir(), "kici-overlay-"));
+	try {
+		logger.info("Downloading overlay tarball", { url: tarballUrl.replace(/\?.*$/, "?[redacted]") });
+		let encryptedData;
+		try {
+			encryptedData = await downloadUrl(tarballUrl);
+		} catch (err) {
+			throw new Error(`Overlay download failed from ${tarballUrl.replace(/\?.*$/, "?[redacted]")}: ${toErrorMessage(err)}`);
+		}
+		const cliPubKeyBuf = Buffer.from(cliPublicKey, "base64");
+		const aesKey = deriveSharedSecret(Buffer.from(orchestratorPrivateKey, "base64"), cliPubKeyBuf);
+		const decryptedData = decryptBuffer(encryptedData, aesKey);
+		logger.info("Extracting overlay tarball", { size: decryptedData.length });
+		const extractDir = path.join(tmpDir, "extracted");
+		await fsPromises.mkdir(extractDir, { recursive: true });
+		try {
+			const readable = Readable.from(decryptedData);
+			await new Promise((resolve, reject) => {
+				readable.pipe(x({
+					cwd: extractDir,
+					gzip: true
+				})).on("finish", resolve).on("error", reject);
+			});
+		} catch (err) {
+			throw new Error(`Overlay extraction failed: ${toErrorMessage(err)}`);
+		}
+		const manifestPath = path.join(extractDir, ".kici-overlay-tmp", "manifest.json");
+		let manifestContent;
+		try {
+			manifestContent = await fsPromises.readFile(manifestPath, "utf-8");
+		} catch {
+			throw new Error("Overlay manifest not found: expected .kici-overlay-tmp/manifest.json in tarball");
+		}
+		const manifest = JSON.parse(manifestContent);
+		const checksumFiles = Object.keys(manifest.checksums);
+		const failedChecksums = [];
+		for (const file of checksumFiles) {
+			const extractedPath = path.join(extractDir, file);
+			try {
+				const actualHash = await sha256File(extractedPath);
+				if (actualHash !== manifest.checksums[file]) failedChecksums.push(`${file}: expected ${manifest.checksums[file]}, got ${actualHash}`);
+			} catch {
+				failedChecksums.push(`${file}: file not found in tarball`);
+			}
+		}
+		if (failedChecksums.length > 0) throw new Error(`Overlay checksum verification failed for ${failedChecksums.length} file(s):\n` + failedChecksums.map((f) => `  - ${f}`).join("\n"));
+		let filesApplied = 0;
+		for (const file of checksumFiles) {
+			const srcPath = path.join(extractDir, file);
+			const destPath = path.join(repoDir, file);
+			await fsPromises.mkdir(path.dirname(destPath), { recursive: true });
+			await fsPromises.copyFile(srcPath, destPath);
+			filesApplied++;
+		}
+		let filesDeleted = 0;
+		for (const file of manifest.deletions) {
+			const targetPath = path.join(repoDir, file);
+			try {
+				await fsPromises.unlink(targetPath);
+				filesDeleted++;
+			} catch {
+				logger.debug("Deletion target not found, skipping", { file });
+			}
+		}
+		logger.info("Overlay applied successfully", {
+			filesApplied,
+			filesDeleted
+		});
+		return {
+			filesApplied,
+			filesDeleted,
+			verified: true
+		};
+	} finally {
+		await fsPromises.rm(tmpDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+//#endregion
+//#region src/execution/sandbox/workflow-runner.ts
+/**
+* Workflow Runner -- standalone entry point that runs INSIDE the sandbox.
+*
+* This is the code that actually executes customer workflows in isolation.
+* The agent process never loads or executes customer code -- only this runner does.
+*
+* Supports two IPC modes:
+* - Fork IPC: Used by bare-metal (bwrap) and Firecracker backends. Messages go
+*   via Node.js IPC channel (process.send / process.on('message')).
+* - Stdio IPC: Used by container backend (docker exec). JSON-line messages flow
+*   bidirectionally: agent writes to container stdin, runner writes to stdout.
+*
+* This file is compiled alongside the agent by rolldown (existing build), but
+* runs as a SEPARATE process spawned by the sandbox backend.
+*/
+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`);
+	process.exit(99);
+});
+process.on("unhandledRejection", (reason) => {
+	const msg = toErrorMessage(reason);
+	const stack = reason instanceof Error ? reason.stack : void 0;
+	process.stderr.write(`[workflow-runner] UNHANDLED REJECTION: ${msg}\n`);
+	if (stack) process.stderr.write(`[workflow-runner] Stack: ${stack}\n`);
+	process.exit(98);
+});
+/** Whether we are running in fork IPC mode (Node IPC channel available). */
+const isForkMode = typeof process.send === "function";
+/**
+* Saved references to the original stdout/stderr write functions.
+* Used by sendMessage (container mode IPC) and output capture to avoid
+* infinite recursion when process.stdout.write is monkey-patched.
+*/
+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).
+*
+* When true, process.stdout/stderr writes are captured and emitted as
+* log.line IPC messages with `stepIndex: -1` — the same bucket already used
+* by existing meta-messages like `[kici] Concurrency group: ...`. This means
+* user console.log inside module top-level, concurrency-group functions, and
+* 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.
+*/
+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;
+}
+function captureTargetIndex() {
+	return captureStepIndex >= 0 ? captureStepIndex : -1;
+}
+/**
+* Install monkey-patches on process.stdout.write and process.stderr.write
+* so that console.log() / console.error() calls from customer step code
+* are captured and forwarded as log.line IPC messages.
+*
+* Without this, only subprocess output (via ctx.$) goes through zx's log
+* callback. Direct console.log() calls from pure JS/TS step code would be
+* lost (stdout goes to a pipe the fork-runner drains for debugging, but
+* never enters the log streaming pipeline).
+*/
+function installOutputCapture() {
+	let stdoutBuf = "";
+	let stderrBuf = "";
+	process.stdout.write = ((chunk, encodingOrCb, cb) => {
+		if (captureIsActive() && captureSendFn) {
+			const text = typeof chunk === "string" ? chunk : chunk.toString(typeof encodingOrCb === "string" ? encodingOrCb : "utf8");
+			stdoutBuf += text;
+			const lines = stdoutBuf.split("\n");
+			stdoutBuf = lines.pop();
+			const stepIdx = captureTargetIndex();
+			for (const line of lines) if (line) captureSendFn({
+				type: "log.line",
+				stepIndex: stepIdx,
+				line
+			});
+		}
+		if (isForkMode) return origStdoutWrite(chunk, encodingOrCb, cb);
+		const callback = typeof encodingOrCb === "function" ? encodingOrCb : cb;
+		if (callback) callback();
+		return true;
+	});
+	process.stderr.write = ((chunk, encodingOrCb, cb) => {
+		if (captureIsActive() && captureSendFn) {
+			const text = typeof chunk === "string" ? chunk : chunk.toString(typeof encodingOrCb === "string" ? encodingOrCb : "utf8");
+			stderrBuf += text;
+			const lines = stderrBuf.split("\n");
+			stderrBuf = lines.pop();
+			const stepIdx = captureTargetIndex();
+			for (const line of lines) if (line) captureSendFn({
+				type: "log.line",
+				stepIndex: stepIdx,
+				line
+			});
+		}
+		return origStderrWrite(chunk, encodingOrCb, cb);
+	});
+}
+/**
+* Flush any remaining partial lines in the output capture buffers.
+* Called after each step completes to ensure no trailing output is lost.
+*/
+function flushOutputCapture() {
+	if (captureIsActive()) {
+		process.stdout.write("\n");
+		process.stderr.write("\n");
+	}
+}
+/**
+* Send a message from the runner to the agent.
+*
+* In fork mode: uses Node.js IPC channel (process.send).
+* In stdio mode: writes a JSON line to stdout via origStdoutWrite
+* (bypasses any monkey-patch on process.stdout.write).
+*/
+function sendMessage(msg) {
+	if (isForkMode) process.send(msg);
+	else origStdoutWrite(JSON.stringify(msg) + "\n");
+}
+/**
+* Readline interface for stdin in stdio (container) mode.
+* Created once and reused for both receiveRequest() and the response listener.
+*/
+let stdinRl = null;
+/**
+* Get or create the stdin readline interface for container/stdio mode.
+*/
+function getStdinRl() {
+	if (!stdinRl) {
+		process.stdin.setEncoding("utf-8");
+		stdinRl = createInterface({
+			input: process.stdin,
+			crlfDelay: Infinity
+		});
+	}
+	return stdinRl;
+}
+/**
+* Receive the execution request from the agent.
+*
+* In fork mode: listens for the first 'execute' message on the IPC channel.
+* In stdio mode: reads JSON-lines from stdin, resolves on the first 'execute' message.
+*
+* @returns The execute message containing the JobExecutionRequest.
+*/
+function receiveRequest() {
+	if (isForkMode) return new Promise((resolve) => {
+		const handler = (msg) => {
+			if (msg.type === "execute") {
+				process.removeListener("message", handler);
+				resolve(msg);
+			}
+		};
+		process.on("message", handler);
+	});
+	else return new Promise((resolve, reject) => {
+		const rl = getStdinRl();
+		const handler = (line) => {
+			try {
+				const parsed = JSON.parse(line);
+				if (parsed.type === "execute") {
+					rl.removeListener("line", handler);
+					resolve(parsed);
+				}
+			} catch (e) {
+				rl.removeListener("line", handler);
+				reject(/* @__PURE__ */ new Error(`Failed to parse stdin JSON: ${toErrorMessage(e)}`));
+			}
+		};
+		rl.on("line", handler);
+	});
+}
+initZx();
+$.verbose = false;
+$.quiet = false;
+/** Global abort flag. Set when abort message or SIGTERM is received. */
+let aborted = false;
+/**
+* Force cancel flag. When true, skip all remaining hooks and exit immediately.
+* Set when abort IPC arrives with force=true, or on second cancel while already cancelling.
+*/
+let forceAborted = false;
+/**
+* Pending promises for event.emit requests awaiting responses from the agent.
+*
+* Key: requestId (correlates EventEmitRequest -> EventEmitResponse)
+* Value: resolve/reject pair for the waiting ctx.emit() call
+*/
+const pendingEmitResponses = /* @__PURE__ */ new Map();
+/** Default timeout for event.emit responses (5 seconds per research doc). */
+const EMIT_RESPONSE_TIMEOUT_MS = 5e3;
+/**
+* Wait for an event.emit.response from the agent with the given requestId.
+*
+* On timeout, resolves with a synthetic success receipt and logs a warning
+* (per research doc pitfall 5: event was already persisted by orchestrator,
+* so it will still be routed even if the ack is lost).
+*/
+function waitForEmitResponse(requestId) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			pendingEmitResponses.delete(requestId);
+			process.stderr.write(`[workflow-runner] event.emit response timeout for requestId=${requestId} -- returning synthetic receipt\n`);
+			resolve({
+				type: "event.emit.response",
+				requestId,
+				deliveryId: `timeout-${requestId}`
+			});
+		}, EMIT_RESPONSE_TIMEOUT_MS);
+		pendingEmitResponses.set(requestId, {
+			resolve: (response) => {
+				clearTimeout(timer);
+				pendingEmitResponses.delete(requestId);
+				resolve(response);
+			},
+			reject: (err) => {
+				clearTimeout(timer);
+				pendingEmitResponses.delete(requestId);
+				resolve({
+					type: "event.emit.response",
+					requestId,
+					error: err.message
+				});
+			},
+			timer
+		});
+	});
+}
+/**
+* Pending promise for the concurrency.ack response from the agent.
+* Only one outstanding concurrency report per job (one workflow = one group).
+*/
+let pendingConcurrencyAck = null;
+/**
+* Wait for a concurrency.ack from the agent (relayed from orchestrator).
+* The timeout is configurable (default 30s) and fails the job on expiry.
+*/
+function waitForConcurrencyAck(timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			pendingConcurrencyAck = null;
+			reject(/* @__PURE__ */ new Error(`Concurrency group ack timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		pendingConcurrencyAck = {
+			resolve: (ack) => {
+				clearTimeout(timer);
+				pendingConcurrencyAck = null;
+				resolve(ack);
+			},
+			reject: (err) => {
+				clearTimeout(timer);
+				pendingConcurrencyAck = null;
+				reject(err);
+			},
+			timer
+		};
+	});
+}
+/**
+* Pending promises for agent.api.response messages from the agent.
+* Key: requestId, Value: resolve/reject pair.
+*/
+const pendingApiResponses = /* @__PURE__ */ new Map();
+const API_RESPONSE_TIMEOUT_MS = 15e3;
+/**
+* Wait for an agent.api.response from the agent with the given requestId.
+*/
+function waitForApiResponse(requestId) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			pendingApiResponses.delete(requestId);
+			reject(/* @__PURE__ */ new Error(`Agent API request timed out after ${API_RESPONSE_TIMEOUT_MS}ms`));
+		}, API_RESPONSE_TIMEOUT_MS);
+		pendingApiResponses.set(requestId, {
+			resolve: (result) => {
+				clearTimeout(timer);
+				pendingApiResponses.delete(requestId);
+				resolve(result);
+			},
+			reject: (err) => {
+				clearTimeout(timer);
+				pendingApiResponses.delete(requestId);
+				reject(err);
+			},
+			timer
+		});
+	});
+}
+/**
+* Dispatch an agent-to-runner message to the appropriate pending handler.
+* Shared between fork mode (IPC channel) and stdio mode (stdin readline).
+*/
+function dispatchAgentMessage(msg) {
+	if (msg.type === "abort") {
+		aborted = true;
+		if (msg.force) forceAborted = true;
+	} else if (msg.type === "event.emit.response") {
+		const pending = pendingEmitResponses.get(msg.requestId);
+		if (pending) pending.resolve(msg);
+	} else if (msg.type === "concurrency.ack") {
+		if (pendingConcurrencyAck) pendingConcurrencyAck.resolve(msg);
+	} else if (msg.type === "agent.api.response") {
+		const pending = pendingApiResponses.get(msg.requestId);
+		if (pending) if (msg.error) pending.reject(new Error(msg.error));
+		else pending.resolve(msg.result);
+	}
+}
+if (isForkMode) process.on("message", (msg) => {
+	dispatchAgentMessage(msg);
+});
+else getStdinRl().on("line", (line) => {
+	try {
+		const msg = JSON.parse(line);
+		if (msg.type !== "execute") dispatchAgentMessage(msg);
+	} catch {}
+});
+process.on("SIGTERM", () => {
+	aborted = true;
+});
+/**
+* Create a Logger that sends log lines via IPC.
+*
+* Each log call formats the line and sends it as a log.line IPC message.
+* Format matches the existing createStepLogger: [stepName] [level?] message args...
+*/
+function createIpcLogger(stepIndex, stepName, sendFn) {
+	const formatLine = (level, message, args) => {
+		const formatted = args.length > 0 ? `${message} ${args.join(" ")}` : message;
+		return `[${stepName}] ${level !== "info" ? `[${level}] ` : ""}${formatted}`;
+	};
+	return {
+		info: (message, ...args) => {
+			sendFn({
+				type: "log.line",
+				stepIndex,
+				line: formatLine("info", message, args)
+			});
+		},
+		warn: (message, ...args) => {
+			sendFn({
+				type: "log.line",
+				stepIndex,
+				line: formatLine("warn", message, args)
+			});
+		},
+		error: (message, ...args) => {
+			sendFn({
+				type: "log.line",
+				stepIndex,
+				line: formatLine("error", message, args)
+			});
+		},
+		debug: (message, ...args) => {
+			if (process.env.KICI_LOG_LEVEL === "debug") sendFn({
+				type: "log.line",
+				stepIndex,
+				line: formatLine("debug", message, args)
+			});
+		}
+	};
+}
+/**
+* Build StepSecrets from the job execution request, wired with the per-step
+* file-mount host (used by `ctx.secrets.mountFile` / `exposeFile`).
+*
+* Returns a `{ secrets, dispose }` handle: `secrets` is bound into the step
+* context, and `dispose` is invoked by the step-loop's `finally` to remove
+* the per-step tmpdir and clear any env vars set via `exposeFile`.
+*
+* The mounted-file content is registered with the active `LogMasker` so any
+* subprocess that echoes the credential gets `***`-replaced in the streamed
+* log -- same masker the rest of the runner uses, so masking is global, not
+* per-step.
+*/
+function buildStepSecrets(request, masker, onMaskerSecretsAdded) {
+	const mergedFlat = buildMergedFlatSecrets(request.secrets ?? {}, request.namespacedSecrets ?? {});
+	let stepTmpdir = null;
+	const exposedEnvVars = /* @__PURE__ */ new Set();
+	let mountCounter = 0;
+	const env = process.env;
+	async function ensureTmpdir() {
+		if (stepTmpdir === null) stepTmpdir = await fsPromises.mkdtemp(join(tmpdir(), "kici-secret-files-"));
+		return stepTmpdir;
+	}
+	return createStepSecrets(mergedFlat, env, request.secretMeta, {
+		host: {
+			async writeMountedFile(args) {
+				const dir = await ensureTmpdir();
+				mountCounter += 1;
+				const filePath = join(dir, args.name ?? `secret-${mountCounter}`);
+				await fsPromises.writeFile(filePath, args.content);
+				await fsPromises.chmod(filePath, args.mode);
+				masker.registerSecrets({ [`__mount_${mountCounter}__`]: args.content });
+				onMaskerSecretsAdded();
+				return filePath;
+			},
+			trackExposedEnv(envVar) {
+				exposedEnvVars.add(envVar);
+			}
+		},
+		cleanup: async () => {
+			for (const envVar of exposedEnvVars) {
+				delete env[envVar];
+				delete process.env[envVar];
+			}
+			exposedEnvVars.clear();
+			if (stepTmpdir !== null) {
+				await fsPromises.rm(stepTmpdir, {
+					recursive: true,
+					force: true
+				});
+				stepTmpdir = null;
+			}
+		},
+		onDisposeError: (err) => {
+			origStderrWrite(`[workflow-runner] secret-file cleanup error: ${err instanceof Error ? err.message : String(err)}\n`);
+		}
+	});
+}
+/**
+* Create a LogMasker initialized with all secret values from the request.
+*
+* Collects values from both flat secrets and all namespaced context secrets,
+* deduplicating before registration.
+*/
+function createSecretMasker(request) {
+	const masker = new LogMasker();
+	const allSecrets = {};
+	if (request.secrets) Object.assign(allSecrets, request.secrets);
+	if (request.namespacedSecrets) for (const contextSecrets of Object.values(request.namespacedSecrets)) Object.assign(allSecrets, contextSecrets);
+	masker.registerSecrets(allSecrets);
+	return masker;
+}
+/**
+* Create a StepContext natively inside the workflow runner.
+*
+* The context is reconstructed from the environment and IPC request fields --
+* 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) {
+	let zxLineBuf = "";
+	const step$ = $({
+		cwd: workDir,
+		env: { ...process.env },
+		verbose: false,
+		quiet: false,
+		log: ((entry) => {
+			if (entry.kind === "stdout" || entry.kind === "stderr") {
+				const text = typeof entry.data === "string" ? entry.data : String(entry.data ?? "");
+				zxLineBuf += text;
+				const lines = zxLineBuf.split("\n");
+				zxLineBuf = lines.pop();
+				for (const line of lines) if (line) maskedSendFn({
+					type: "log.line",
+					stepIndex,
+					line
+				});
+				return;
+			}
+		})
+	});
+	const log = createIpcLogger(stepIndex, stepName, maskedSendFn);
+	return {
+		$: step$,
+		log,
+		env: process.env,
+		setEnv: (key, value) => {
+			if (operatorSecretKeys.has(key)) {
+				log.warn(`Cannot override operator secret "${key}" via setEnv — value preserved`);
+				return;
+			}
+			process.env[key] = value;
+		},
+		addPath: (dir) => {
+			process.env.PATH = dir + ":" + (process.env.PATH ?? "");
+		},
+		inputs: {},
+		secrets,
+		workflow: { name: request.workflowName },
+		job: {
+			name: request.jobName,
+			runsOn: request.runsOn
+		},
+		isTestRun: request.isTestRun ?? false,
+		environment: request.environment,
+		emit: async (eventName, payload, options) => {
+			const reqId = randomUUID();
+			sendMessage({
+				type: "event.emit",
+				requestId: reqId,
+				eventName,
+				payload: payload ?? {},
+				...options?.target && { target: options.target }
+			});
+			const response = await waitForEmitResponse(reqId);
+			if (response.error) throw new Error(`Event emission failed: ${response.error}`);
+			return { deliveryId: response.deliveryId };
+		},
+		outputsOf: (ref) => {
+			return resolveStepOutputs(ref, outputsMap, refMap);
+		},
+		jobOutputs: (ref) => {
+			return resolveJobOutputs(ref, jobOutputsMap);
+		},
+		setSecretOutput: (key, value) => {
+			secretOutputs.set(key, value);
+		},
+		kici: buildKiciApi(async (method, params) => {
+			const reqId = randomUUID();
+			sendMessage({
+				type: "agent.api.request",
+				requestId: reqId,
+				method,
+				params: params ?? {}
+			});
+			return waitForApiResponse(reqId);
+		}),
+		...request.event && { rawPayload: request.event },
+		...request.provider && { provider: request.provider }
+	};
+}
+/**
+* Check if a file exists at the given path.
+*/
+function fileExists(p) {
+	return existsSync(p);
+}
+function trace(msg) {
+	origStderrWrite(`[workflow-runner:trace] ${msg}\n`);
+}
+/**
+* Send a job.complete + process.exit. Centralises the abort-mid-prepare path
+* (after clone / after deps / after rules) so the messages and exit code
+* stay consistent.
+*/
+function abortAndExit(reason) {
+	trace(reason);
+	flushOutputCapture();
+	capturePrepareActive = false;
+	sendMessage({
+		type: "job.complete",
+		status: ExecutionJobStatus.enum.failed,
+		stepResults: []
+	});
+	process.exit(1);
+}
+/**
+* Phase 1 — Clone the source / workflow repos (or skip when checkout=false).
+* Three modes: full-repo overlay-only (no clone), global dual-clone
+* (workflow + source), or single-repo clone. Each mode emits the same
+* progress IPC log lines as before.
+*/
+async function cloneRepoIfRequested(request, workDir, workflowDir, sourceDir, isGlobal) {
+	if (request.checkout === false) return;
+	if (request.fullRepo) {
+		trace("fullRepo mode -- skipping git clone, workspace from overlay");
+		await fsPromises.mkdir(workDir, { recursive: true });
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: "[workflow-runner] Full-repo mode: skipping git clone (workspace from overlay tarball)"
+		});
+		return;
+	}
+	if (isGlobal) {
+		trace(`starting dual-clone (global workflow)`);
+		await fsPromises.mkdir(workflowDir, { recursive: true });
+		await fsPromises.mkdir(sourceDir, { recursive: true });
+		const workflowAuth = request.workflowAuth ?? request.sourceAuth;
+		const sourceAuth = request.sourceAuth ?? request.workflowAuth;
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[workflow-runner] Global workflow: cloning workflow repo ${request.workflowRepoUrl} ref=${request.workflowRef} into ${workflowDir}`
+		});
+		await gitClone({
+			repoUrl: request.workflowRepoUrl,
+			ref: request.workflowRef ?? "",
+			sha: request.workflowSha ?? "",
+			workDir: workflowDir,
+			gitAuth: workflowAuth,
+			token: workflowAuth ? void 0 : request.token
+		});
+		trace("workflow repo clone complete");
+		await excludeScratchFromGit(workflowDir);
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[workflow-runner] Global workflow: cloning source repo ${request.repoUrl} ref=${request.ref} into ${sourceDir}`
+		});
+		await gitClone({
+			repoUrl: request.repoUrl,
+			ref: request.ref,
+			sha: request.sha,
+			workDir: sourceDir,
+			gitAuth: sourceAuth,
+			token: sourceAuth ? void 0 : request.token
+		});
+		trace("source repo clone complete");
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: "[workflow-runner] Dual-clone complete"
+		});
+		return;
+	}
+	trace("starting git clone");
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: `[workflow-runner] Cloning ${request.repoUrl} ref=${request.ref} into ${workDir}`
+	});
+	await gitClone({
+		repoUrl: request.repoUrl,
+		ref: request.ref,
+		sha: request.sha,
+		workDir,
+		gitAuth: request.sourceAuth,
+		token: request.sourceAuth ? void 0 : request.token
+	});
+	await excludeScratchFromGit(workDir);
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: "[workflow-runner] Clone complete"
+	});
+	trace("git clone complete");
+}
+/**
+* Phase 1b — Apply the encrypted overlay tarball when present (test runs
+* with uncommitted changes). For global workflows the overlay applies to the
+* workflow repo (the one carrying `.kici/`).
+*/
+async function applyOverlayIfRequested(request, workflowDir) {
+	if (!request.tarballUrl || !request.cliPublicKey || !request.orchestratorPrivateKey) return;
+	trace("applying overlay tarball");
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: "[workflow-runner] Applying overlay (uncommitted changes)"
+	});
+	const overlayResult = await applyOverlay({
+		tarballUrl: request.tarballUrl,
+		cliPublicKey: request.cliPublicKey,
+		orchestratorPrivateKey: request.orchestratorPrivateKey,
+		repoDir: workflowDir
+	});
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: `[workflow-runner] Overlay applied: ${overlayResult.filesApplied} files changed, ${overlayResult.filesDeleted} files deleted`
+	});
+	trace(`overlay applied: ${overlayResult.filesApplied} files, ${overlayResult.filesDeleted} deletions`);
+}
+/**
+* Phase 2 — Restore deps from cache (with hash-mismatch hard-fail) OR fall
+* back to inline install. Skipped when `.kici/package.json` doesn't exist.
+* For global workflows deps come from the workflow repo (where `.kici/` lives).
+*/
+async function installDependenciesIfNeeded(workflowDir, request) {
+	const kiciDir = join(workflowDir, ".kici");
+	const hasPackageJson = fileExists(join(kiciDir, "package.json"));
+	trace(`deps: kiciDir=${kiciDir}, hasPackageJson=${hasPackageJson}, depsUrl=${request.depsUrl ?? "none"}`);
+	if (!hasPackageJson) return;
+	if (request.depsUrl) {
+		trace("restoring deps from cache");
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[workflow-runner] Restoring deps from ${request.depsUrl}`
+		});
+		try {
+			await restoreDeps(workflowDir, request.depsUrl, request.depsHash);
+			sendMessage({
+				type: "log.line",
+				stepIndex: -1,
+				line: "[workflow-runner] Deps restored from cache"
+			});
+			trace("deps restored from cache");
+		} catch (err) {
+			if (err instanceof Error && err.message.includes("hash mismatch")) throw err;
+			trace(`cache restore failed: ${toErrorMessage(err)}, falling back`);
+			sendMessage({
+				type: "log.line",
+				stepIndex: -1,
+				line: `[workflow-runner] Cache restore failed (${toErrorMessage(err)}), falling back to inline install`
+			});
+			await installDeps(kiciDir, {
+				npmRegistries: request.npmRegistries,
+				installEnvSecrets: request.installEnvSecrets,
+				jobIdShort: request.jobIdShort
+			});
+			trace("fallback install complete");
+		}
+		return;
+	}
+	if (fileExists(join(kiciDir, "node_modules"))) {
+		trace("node_modules already exists, skipping install");
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: "[workflow-runner] Deps already present (node_modules exists), skipping install"
+		});
+		return;
+	}
+	trace("installing deps inline (no cache)");
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: "[workflow-runner] Installing deps inline (no cache)"
+	});
+	try {
+		await installDeps(kiciDir, {
+			npmRegistries: request.npmRegistries,
+			installEnvSecrets: request.installEnvSecrets,
+			jobIdShort: request.jobIdShort
+		});
+		trace("installDeps() returned successfully");
+	} catch (depErr) {
+		const depMsg = toErrorMessage(depErr);
+		const depStack = depErr instanceof Error ? depErr.stack : void 0;
+		trace(`installDeps THREW: ${depMsg}`);
+		if (depStack) trace(`installDeps stack: ${depStack}`);
+		throw depErr;
+	}
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: "[workflow-runner] Deps installed"
+	});
+	trace("deps installed IPC sent");
+}
+/**
+* Phase 2b — Restore the cached `.kici/` source tarball over the cloned
+* workflow root so the loaded workflow's contentHash matches the lock file
+* exactly. No-op when no `sourceTarUrl` was provided.
+*/
+async function restoreSourceTarballIfRequested(workflowRoot, request) {
+	if (!request.sourceTarUrl) return;
+	trace(`restoring .kici/ source from tarball url=${request.sourceTarUrl}`);
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: "[workflow-runner] Restoring .kici/ source from cached tarball"
+	});
+	await restoreSource(workflowRoot, request.sourceTarUrl);
+	trace("source tarball restored");
+}
+/**
+* Phase 3 — Install the stdout/stderr capture, then load the workflow module
+* via the oxc-transform ESM loader. Capture is enabled for the prepare phase
+* (module load → concurrency → rules) so user `console.log` lands in the
+* workflow-level log bucket (stepIndex: -1). On load failure we flush + clear
+* the prepare flag before rethrowing so the catch handler in main() doesn't
+* see stale buffer state.
+*/
+async function loadWorkflowModuleWithCapture(workflowRoot, request, isGlobal, maskedSend) {
+	let sourceFile = request.sourceFile ?? ".kici/workflows/ci.ts";
+	if (sourceFile && !sourceFile.startsWith(".kici/")) sourceFile = `.kici/${sourceFile}`;
+	trace(`loading workflow module, sourceFile=${sourceFile}, workflowRoot=${workflowRoot}, cachedSource=${!!request.sourceTarUrl}`);
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: `[workflow-runner] Loading workflow module${isGlobal ? " (global=true, from workflow repo)" : ""}`
+	});
+	captureSendFn = maskedSend;
+	installOutputCapture();
+	capturePrepareActive = true;
+	try {
+		const loaded = await loadWorkflowSource(workflowRoot, sourceFile, request.contentHash, request.resolvedHashFiles);
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: "[workflow-runner] Workflow module loaded"
+		});
+		trace(`workflow module loaded, exports=${Object.keys(loaded.module).join(",")}`);
+		return loaded;
+	} catch (err) {
+		flushOutputCapture();
+		capturePrepareActive = false;
+		throw err;
+	}
+}
+/**
+* Phase 4b — Evaluate the user-defined `concurrency.group(...)` function with
+* a timeout, report the resulting key to the orchestrator, and act on the
+* returned ack. `wait` and `cancel` paths exit the process directly (the run
+* is over from the runner's perspective). Returns 'proceed' to the caller in
+* the success path.
+*
+* Returns 'failed' instead of exiting when group evaluation throws, so
+* main() can keep its single exit-on-error point.
+*/
+async function evaluateConcurrencyGroupIfPresent(workflow, request) {
+	if (!workflow.concurrency?.group) return "proceed";
+	trace("evaluating concurrency group function");
+	const concurrencyTimeoutMs = request.concurrencyEvaluationTimeoutMs ?? 3e4;
+	const groupCtx = {
+		branch: request.branch ?? request.ref,
+		event: request.event ?? {}
+	};
+	try {
+		const ac = new AbortController();
+		const concurrencyTimer = setTimeout(() => ac.abort(), concurrencyTimeoutMs);
+		let groupKey;
+		try {
+			groupKey = await Promise.race([Promise.resolve(workflow.concurrency.group(groupCtx)), new Promise((_, reject) => {
+				ac.signal.addEventListener("abort", () => reject(/* @__PURE__ */ new Error(`Concurrency group evaluation timed out after ${concurrencyTimeoutMs}ms`)));
+			})]);
+		} finally {
+			clearTimeout(concurrencyTimer);
+		}
+		trace(`concurrency group evaluated: ${groupKey}`);
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[kici] Concurrency group: ${groupKey}`
+		});
+		sendMessage({
+			type: "concurrency.report",
+			group: groupKey
+		});
+		trace("waiting for concurrency ack");
+		let ack = await waitForConcurrencyAck(concurrencyTimeoutMs);
+		trace(`concurrency ack received: action=${ack.action}, reason=${ack.reason ?? "none"}`);
+		if (ack.action === "proceed") {
+			sendMessage({
+				type: "log.line",
+				stepIndex: -1,
+				line: "[kici] Concurrency: proceeding with execution"
+			});
+			return "proceed";
+		}
+		if (ack.action === "wait") {
+			sendMessage({
+				type: "log.line",
+				stepIndex: -1,
+				line: `[kici] Concurrency: queued${ack.reason ? ` (${ack.reason})` : ""}, waiting for slot to free`
+			});
+			const waitCapMs = Number.parseInt(process.env.KICI_CONCURRENCY_WAIT_TIMEOUT_MS ?? "", 10) || 36e5;
+			try {
+				ack = await waitForConcurrencyAck(waitCapMs);
+			} catch (waitErr) {
+				const waitErrMsg = toErrorMessage(waitErr);
+				sendMessage({
+					type: "log.line",
+					stepIndex: -1,
+					line: `[kici] [error] Concurrency wait timed out: ${waitErrMsg}`
+				});
+				sendMessage({
+					type: "job.complete",
+					status: ExecutionJobStatus.enum.failed,
+					stepResults: [],
+					error: `Concurrency wait timed out after ${waitCapMs}ms: ${waitErrMsg}`
+				});
+				process.exit(1);
+			}
+			trace(`concurrency follow-up ack: action=${ack.action}, reason=${ack.reason ?? "none"}`);
+			if (ack.action === "proceed") {
+				sendMessage({
+					type: "log.line",
+					stepIndex: -1,
+					line: "[kici] Concurrency: slot acquired, proceeding with execution"
+				});
+				return "proceed";
+			}
+			if (ack.action === "wait") {
+				sendMessage({
+					type: "log.line",
+					stepIndex: -1,
+					line: "[kici] [error] Concurrency: unexpected second `wait` ack; aborting"
+				});
+				sendMessage({
+					type: "job.complete",
+					status: ExecutionJobStatus.enum.failed,
+					stepResults: [],
+					error: "Concurrency: unexpected second wait ack"
+				});
+				process.exit(1);
+			}
+		}
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[kici] Concurrency: cancelled${ack.reason ? ` (${ack.reason})` : ""}`
+		});
+		sendMessage({
+			type: "job.complete",
+			status: ExecutionJobStatus.enum.failed,
+			stepResults: [],
+			error: `Cancelled by concurrency policy${ack.reason ? ": " + ack.reason : ""}`
+		});
+		process.exit(1);
+	} catch (err) {
+		const errMsg = toErrorMessage(err);
+		trace(`concurrency group evaluation failed: ${errMsg}`);
+		sendMessage({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[kici] [error] Concurrency group evaluation failed: ${errMsg}`
+		});
+		sendMessage({
+			type: "job.complete",
+			status: ExecutionJobStatus.enum.failed,
+			stepResults: [],
+			error: `Concurrency group evaluation failed: ${errMsg}`
+		});
+		process.exit(1);
+	}
+}
+/**
+* Phase 5 — Inject env vars and build the `RepoInfo` pair that step contexts
+* receive when the job is a global workflow. No-op for normal jobs.
+*/
+function setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir) {
+	if (!isGlobal) return void 0;
+	process.env.KICI_IS_GLOBAL_WORKFLOW = "true";
+	process.env.KICI_WORKFLOW_REPO_PATH = workflowDir;
+	process.env.KICI_SOURCE_REPO_PATH = sourceDir;
+	const sourceRepoIdentifier = request.repoUrl.replace(/\.git$/, "").replace(/^https?:\/\/[^/]+\//, "");
+	process.env.KICI_SOURCE_REPO = sourceRepoIdentifier;
+	process.env.KICI_SOURCE_BRANCH = request.ref;
+	process.env.KICI_SOURCE_SHA = request.sha;
+	process.env.KICI_WORKFLOW_REPO = request.workflowRepoIdentifier ?? "";
+	trace(`global workflow env vars injected: KICI_WORKFLOW_REPO_PATH=${workflowDir}, KICI_SOURCE_REPO_PATH=${sourceDir}`);
+	return {
+		workflowRepo: {
+			identifier: request.workflowRepoIdentifier ?? "",
+			path: workflowDir,
+			ref: request.workflowRef,
+			sha: request.workflowSha
+		},
+		sourceRepo: {
+			identifier: sourceRepoIdentifier,
+			path: sourceDir,
+			ref: request.ref,
+			sha: request.sha
+		}
+	};
+}
+/**
+* Phase 8 — Cancel-path hook execution. Runs the four cancel hooks
+* (step onCancel → step cleanup → job onCancel → job cleanup) inside-out,
+* accumulating any failure reasons into a compound `cancelFailureReason`.
+*
+* `forceAborted=true` short-circuits and runs none of the hooks; the caller
+* still flips finalStatus to failed (the fork-runner overrides it back to
+* `cancelled` based on its own state machine).
+*/
+async function runCancelPathHooks(args) {
+	const { forceAborted, normalizedSteps, loopResult, jobHooks, jobStartTime, outputsMap, createStepCtxWithCapture, disposeStepResources, maskedSend } = args;
+	if (forceAborted) {
+		maskedSend({
+			type: "log.line",
+			stepIndex: -1,
+			line: "[kici] Force cancel received, skipping all hooks"
+		});
+		return { finalStatus: ExecutionJobStatus.enum.failed };
+	}
+	maskedSend({
+		type: "log.line",
+		stepIndex: -1,
+		line: "[kici] Cancel received, running cancel hooks..."
+	});
+	const cancelOutcome = buildOutcomeMetadata({
+		status: ExecutionJobStatus.enum.cancelled,
+		reason: "Job cancelled",
+		stepOutputs: Object.fromEntries(outputsMap),
+		startTime: jobStartTime
+	});
+	let hookStepIndex = normalizedSteps.length + loopResult.stepResults.length;
+	let cancelFailureReason;
+	const concatReason = (existing, fragment) => existing ? `${existing}; ${fragment}` : fragment;
+	const runHook = async (hook, label, hookType, failedStep) => {
+		maskedSend({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[kici] Running ${label} hook...`
+		});
+		const ctx = createStepCtxWithCapture(hookStepIndex, label);
+		let hookResult;
+		try {
+			hookResult = await executeHook({
+				hook,
+				stepContext: ctx,
+				outcome: failedStep ? {
+					...cancelOutcome,
+					failedStep
+				} : cancelOutcome,
+				hookType,
+				stepIndex: hookStepIndex,
+				sendIpc: maskedSend
+			});
+		} finally {
+			await disposeStepResources();
+		}
+		hookStepIndex++;
+		if (!hookResult.success) {
+			const fragment = label === "onCancel" ? `cancelled (onCancel hook failed: ${hookResult.error})` : label.endsWith(":onCancel") ? `cancelled (step onCancel hook failed: ${hookResult.error})` : label.endsWith(":cleanup") ? `step cleanup hook failed: ${hookResult.error}` : label === "cleanup" ? `cleanup hook failed: ${hookResult.error}` : `${label} hook failed: ${hookResult.error}`;
+			cancelFailureReason = concatReason(cancelFailureReason, fragment);
+			maskedSend({
+				type: "log.line",
+				stepIndex: -1,
+				line: `[kici] ${label} hook failed: ${hookResult.error}`
+			});
+		} else maskedSend({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[kici] ${label} hook completed`
+		});
+	};
+	const lastStepIndex = loopResult.stepResults.length - 1;
+	const lastStep = lastStepIndex >= 0 ? normalizedSteps[lastStepIndex] : void 0;
+	if (lastStep?.onCancel) await runHook(lastStep.onCancel, `${lastStep.name}:onCancel`, "onCancel", lastStep.name);
+	if (lastStep?.cleanup) await runHook(lastStep.cleanup, `${lastStep.name}:cleanup`, "cleanup", lastStep.name);
+	if (jobHooks.onCancel) await runHook(jobHooks.onCancel, "onCancel", "onCancel");
+	if (jobHooks.cleanup) await runHook(jobHooks.cleanup, "cleanup", "cleanup");
+	maskedSend({
+		type: "log.line",
+		stepIndex: -1,
+		line: `[kici] Cancel complete, job status: ${cancelFailureReason ? "failed" : "cancelled"}`
+	});
+	return {
+		finalStatus: ExecutionJobStatus.enum.failed,
+		cancelFailureReason
+	};
+}
+/**
+* Phase 5 — Extract steps for the requested job (re-evaluating the dynamic
+* factory when `dynamicSource` is set, otherwise looking up the static job)
+* and normalise the result into the `Step[]` shape the step loop consumes.
+* Bare-function steps get auto-generated `step-N` names so the IPC reporting
+* and the StepRefMap (used by `.result` proxies) line up.
+*/
+async function extractAndNormalizeSteps(workflow, request, apiTransport) {
+	let rawSteps;
+	let driftDroppedJobs = [];
+	if (request.dynamicSource) {
+		const dynamicResult = await extractStepsFromDynamicJob(workflow, request.dynamicSource.index, request.jobName, request.dynamicSource.event, process.env, apiTransport, request.dynamicSource.expectedJobNames);
+		rawSteps = dynamicResult.steps;
+		driftDroppedJobs = dynamicResult.droppedJobs;
+		if (driftDroppedJobs.length > 0) trace(`Determinism drift: ${driftDroppedJobs.length} job(s) dropped: ${driftDroppedJobs.join(", ")}`);
+	} 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++;
+				return {
+					...s,
+					name: `step-${stepCounter}`
+				};
+			}
+			return s;
+		}),
+		refMap,
+		driftDroppedJobs
+	};
+}
+/**
+* Phase 6 — Build the output infrastructure: the per-step operator-secret
+* key set (used for setEnv override protection), and the output / job-output
+* maps that back `.result` proxies and `ctx.outputsOf()` / `ctx.jobOutputs()`.
+* Sets the SDK module globals as a side effect.
+*/
+function buildOutputInfrastructure(request, refMap) {
+	const operatorSecretKeys = /* @__PURE__ */ new Set();
+	if (request.secrets) for (const key of Object.keys(request.secrets)) operatorSecretKeys.add(key);
+	if (request.namespacedSecrets) for (const ctx of Object.values(request.namespacedSecrets)) for (const key of Object.keys(ctx)) operatorSecretKeys.add(key);
+	const outputsMap = /* @__PURE__ */ new Map();
+	const secretOutputs = /* @__PURE__ */ new Map();
+	setStepOutputsMap(outputsMap);
+	setStepRefMap(refMap);
+	const jobOutputsMap = /* @__PURE__ */ new Map();
+	if (request.upstreamJobOutputs) for (const [jobName, outputs] of Object.entries(request.upstreamJobOutputs)) jobOutputsMap.set(jobName, outputs);
+	setJobOutputsMap(jobOutputsMap);
+	return {
+		operatorSecretKeys,
+		outputsMap,
+		secretOutputs,
+		jobOutputsMap
+	};
+}
+/**
+* Phase 7 — Evaluate job-level rules. When any rule fails, send a
+* `job.complete{success}` with all steps marked skipped and exit 0.
+* Returns false when the caller should continue to step execution.
+*/
+async function maybeSkipJobOnRules(job, request, normalizedSteps) {
+	if (!job?.rules || job.rules.length === 0) return false;
+	const ruleCtx = createRuleContext(request.event ?? {}, [], process.env);
+	if ((await evaluateRules(job.rules, ruleCtx, request.jobName)).allPassed) return false;
+	const skippedResults = normalizedSteps.map((s, i) => ({
+		name: s.name,
+		stepIndex: i,
+		status: ExecutionStepStatus.enum.skipped,
+		durationMs: 0
+	}));
+	flushOutputCapture();
+	capturePrepareActive = false;
+	sendMessage({
+		type: "job.complete",
+		status: ExecutionJobStatus.enum.success,
+		stepResults: skippedResults
+	});
+	process.exit(0);
+}
+/**
+* Collect the six job-level hooks (beforeStep / afterStep / onSuccess /
+* onFailure / onCancel / cleanup) into a single typed object the step loop
+* and cancel-path consume.
+*/
+function collectJobHooks(job) {
+	const jobHooks = {};
+	if (!job) return jobHooks;
+	if (job.beforeStep) jobHooks.beforeStep = job.beforeStep;
+	if (job.afterStep) jobHooks.afterStep = job.afterStep;
+	if (job.onSuccess) jobHooks.onSuccess = job.onSuccess;
+	if (job.onFailure) jobHooks.onFailure = job.onFailure;
+	if (job.onCancel) jobHooks.onCancel = job.onCancel;
+	if (job.cleanup) jobHooks.cleanup = job.cleanup;
+	return jobHooks;
+}
+/**
+* Run the complete job execution lifecycle.
+*
+* 1. Receive execution request
+* 2. Git clone (if checkout enabled)
+* 3. Dependency handling (cache restore or inline install)
+* 4. Load workflow module (from bundle or source)
+* 5. Extract workflow and steps
+* 6. Evaluate rules (if any)
+* 7. Execute steps sequentially with IPC reporting
+* 8. Send job.complete and exit
+*/
+async function main() {
+	trace(`main() started, isForkMode=${isForkMode}, pid=${process.pid}`);
+	sendMessage({ type: "ready" });
+	trace("ready message sent");
+	const request = (await receiveRequest()).request;
+	trace(`execute request received: workDir=${request.workDir}, workflow=${request.workflowName}, job=${request.jobName}`);
+	const workDir = request.workDir;
+	const defaultTimeoutMs = request.defaultStepTimeoutMs ?? 1800 * 1e3;
+	const isGlobal = request.isGlobalWorkflow === true;
+	const workflowDir = isGlobal ? join(workDir, "workflow") : workDir;
+	const sourceDir = isGlobal ? join(workDir, "source") : workDir;
+	const masker = createSecretMasker(request);
+	const maskedSend = (msg) => {
+		if (msg.type === "log.line" && masker.hasSecrets()) sendMessage({
+			...msg,
+			line: masker.mask(msg.line)
+		});
+		else sendMessage(msg);
+	};
+	await cloneRepoIfRequested(request, workDir, workflowDir, sourceDir, isGlobal);
+	await applyOverlayIfRequested(request, workflowDir);
+	if (aborted) abortAndExit("aborted after clone");
+	await installDependenciesIfNeeded(workflowDir, request);
+	if (aborted) abortAndExit("aborted after deps");
+	await restoreSourceTarballIfRequested(workflowDir, request);
+	const module = (await loadWorkflowModuleWithCapture(workflowDir, request, isGlobal, maskedSend)).module;
+	const workflow = extractWorkflow(module, request.workflowName);
+	await evaluateConcurrencyGroupIfPresent(workflow, request);
+	const apiTransport = async (method, params) => {
+		const reqId = randomUUID();
+		sendMessage({
+			type: "agent.api.request",
+			requestId: reqId,
+			method,
+			params: params ?? {}
+		});
+		return waitForApiResponse(reqId);
+	};
+	const { normalizedSteps, 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);
+	if (aborted) abortAndExit("aborted after rules");
+	const jobHooks = collectJobHooks(job);
+	const globalRepoInfo = setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir);
+	flushOutputCapture();
+	capturePrepareActive = false;
+	const stepCwd = sourceDir;
+	let currentStepSecrets = null;
+	let currentStepDispose = null;
+	const createStepCtxWithCapture = (stepIndex, stepName) => {
+		captureStepIndex = stepIndex;
+		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);
+		if (globalRepoInfo) {
+			ctx.workflowRepo = globalRepoInfo.workflowRepo;
+			ctx.sourceRepo = globalRepoInfo.sourceRepo;
+		}
+		return ctx;
+	};
+	const jobStartTime = Date.now();
+	const loopResult = await executeStepLoop({
+		steps: normalizedSteps,
+		createStepContext: createStepCtxWithCapture,
+		sendIpc: maskedSend,
+		defaultTimeoutMs,
+		outputsMap,
+		event: request.event ?? {},
+		env: process.env,
+		jobHooks,
+		isAborted: () => aborted,
+		startTime: jobStartTime,
+		getSecretsAccessLog: () => {
+			flushOutputCapture();
+			captureStepIndex = -1;
+			return currentStepSecrets?.getAccessLog() ?? [];
+		},
+		getSecretMountRecords: () => {
+			return currentStepSecrets ? [...currentStepSecrets.getMountRecords()] : [];
+		},
+		disposeStepResources: async () => {
+			const disposeFn = currentStepDispose;
+			currentStepDispose = null;
+			currentStepSecrets = null;
+			if (disposeFn) await disposeFn();
+		}
+	});
+	let finalStatus = loopResult.status === ExecutionStepStatus.enum.success ? ExecutionJobStatus.enum.success : ExecutionJobStatus.enum.failed;
+	let cancelFailureReason;
+	if (aborted) {
+		const cancelResult = await runCancelPathHooks({
+			forceAborted,
+			normalizedSteps,
+			loopResult,
+			jobHooks,
+			jobStartTime,
+			outputsMap,
+			createStepCtxWithCapture,
+			disposeStepResources: async () => {
+				const disposeFn = currentStepDispose;
+				currentStepDispose = null;
+				currentStepSecrets = null;
+				if (disposeFn) await disposeFn();
+			},
+			maskedSend
+		});
+		finalStatus = cancelResult.finalStatus;
+		cancelFailureReason = cancelResult.cancelFailureReason;
+	}
+	const aggregatedOutputs = {};
+	for (const [stepName, outputs] of outputsMap) aggregatedOutputs[stepName] = outputs;
+	sendMessage({
+		type: "job.complete",
+		status: finalStatus,
+		stepResults: loopResult.stepResults,
+		...Object.keys(aggregatedOutputs).length > 0 && { outputs: aggregatedOutputs },
+		...secretOutputs.size > 0 && { secretOutputs: Object.fromEntries(secretOutputs) },
+		...loopResult.failureReason && { error: loopResult.failureReason },
+		...cancelFailureReason && { error: cancelFailureReason },
+		...driftDroppedJobs.length > 0 && { droppedJobs: driftDroppedJobs }
+	});
+	process.exit(finalStatus === ExecutionJobStatus.enum.success ? 0 : 1);
+}
+/**
+* Find a static Job by name in the workflow.
+*/
+function findJob(workflow, jobName) {
+	for (const item of workflow.jobs) if (!isDynamicJobFn(item) && item.name === jobName) return item;
+}
+main().catch((error) => {
+	const message = toErrorMessage(error);
+	const stack = error instanceof Error ? error.stack : void 0;
+	process.stderr.write(`[workflow-runner] Fatal error: ${message}\n`);
+	if (stack) process.stderr.write(`[workflow-runner] Stack: ${stack}\n`);
+	sendMessage({
+		type: "log.line",
+		stepIndex: -1,
+		line: `[workflow-runner] [error] Fatal: ${message}`
+	});
+	sendMessage({
+		type: "job.complete",
+		status: ExecutionJobStatus.enum.failed,
+		stepResults: [],
+		error: message
+	});
+	setTimeout(() => process.exit(1), 100);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=workflow-runner.js.map