@kici-dev/agent 0.1.14 → 0.1.16

package/dist/workflow-runner.js

@@ -1,1060 +1,1735 @@
-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, { access, mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
-import os, { tmpdir } from "node:os";
-import path, { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import fsPromises, { access, cp, mkdir, mkdtemp, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
+import os, { homedir, tmpdir } from "node:os";
+import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { $ } from "zx";
 import { createLogger, deriveSharedSecret, initZx, normalizeLineEndings, sha256, sha256File, toErrorMessage } from "@kici-dev/shared";
-import { ExecutionJobStatus, ExecutionStepStatus } from "@kici-dev/engine";
-import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
-import { execFile } from "node:child_process";
+import { CacheOutcome, CacheStepType, ExecutionJobStatus, ExecutionStepStatus, TimeoutReason } from "@kici-dev/engine";
+import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, normalizeCacheSpecs, normalizeRequireApproval, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
+import { c, x } from "tar";
+import https from "node:https";
+import http from "node:http";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { x } from "tar";
+import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { PNPM_IGNORE_BUILD_GATE_ARG, PackageManager, detectPackageManagerFromManifests } from "@kici-dev/shared/package-manager";
-import https from "node:https";
-import http from "node:http";
+var __defProp = Object.defineProperty;
+var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
 import.meta.url;
 //#endregion
-//#region src/execution/sandbox/log-masker.ts
+//#region src/execution/dep-restore.ts
 /**
-* Secret value masking for log lines.
+* Dependency restoration from cached tarballs.
 *
-* Replaces all occurrences of registered secret values with '***' in log output.
-* Used by the workflow runner to prevent secret leaks in IPC log messages.
+* Downloads a pre-built dependency tarball, verifies SHA-256 integrity,
+* and extracts to .kici/node_modules/ in the work directory.
 *
-* Performance: Builds a single combined regex from all secret values, so each
-* log line is scanned in a single pass (not O(secrets * lines)).
+* 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.
 */
-/** Minimum length for a secret value to be maskable (avoids false positives). */
-const MIN_MASK_LENGTH = 3;
 /**
-* Escape regex special characters in a string.
+* Compute SHA-256 hash of a buffer.
 */
-function escapeRegExp(s) {
-	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function computeHash(data) {
+	return sha256(data);
 }
 /**
-* 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)
-* ```
+* Extract a gzip tarball from a buffer into the target directory.
+* Used for file:// URLs where streaming provides no benefit.
 */
-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
+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);
+	});
+}
 /**
-* Secret merging utilities for the workflow runner.
+* Stream download and extract an HTTP/HTTPS tarball.
 *
-* Separated from workflow-runner.ts to allow unit testing without
-* triggering the runner's top-level side effects (process handlers, main()).
+* 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$2) });
+	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");
+}
 /**
-* Merge orchestrator-level secrets with auto-flattened context keys.
+* Extract the dep tarball into a per-attempt scratch dir so retries never race
+* with still-draining I/O from a previous failed attempt.
 *
-* Precedence (last wins):
-* 1. Orchestrator-level secrets (lowest)
-* 2. Context-flattened keys in declaration order (each context's keys overlay previous)
+* 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).
 *
-* 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.
+* 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 `moveScratchIntoRepo` renames the extracted entries into place
+* (atomic on the same filesystem), then best-effort cleans the scratch dir.
 *
-* Duration is calculated as elapsed time since startTime.
+* 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`.
 */
-function buildOutcomeMetadata(opts) {
+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 {
-		status: opts.status,
-		reason: opts.reason,
-		failedStep: opts.failedStep,
-		stepOutputs: opts.stepOutputs,
-		duration: Date.now() - opts.startTime
+		scratchDir,
+		hash: await streamFetchAndExtract(url, scratchDir)
 	};
 }
 /**
-* Normalize a HookInput (bare function, { run, timeout }, or HookConfig) into a HookConfig.
+* 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).
 */
-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}`);
+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$4.warn("Failed to register scratch dir glob in .git/info/exclude", {
+			excludePath,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
 }
 /**
-* Execute a single hook with timeout enforcement and IPC reporting.
+* Rewrite localhost URLs to use the orchestrator host.
 *
-* Sends step.start and step.complete IPC messages with step_type = 'hook:{hookType}'.
-* The hook runs in the same sandbox context as regular steps.
+* 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.
 */
-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);
+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 {
-		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}`
+		const orchestratorParsed = new URL(orchestratorUrl.replace(/^ws/, "http"));
+		const parsed = new URL(url);
+		parsed.hostname = orchestratorParsed.hostname;
+		return parsed.toString();
+	} catch {
+		return url;
+	}
+}
+/**
+* Move a fully-extracted scratch tree into the cloned repo. The dep tarball is
+* packed repo-root-relative, so the scratch holds repo-root entries:
+* `.kici/node_modules` for every manager, plus (for pnpm) the root
+* `node_modules/.pnpm` store and in-repo workspace sibling dirs. `.kici/` itself
+* already exists in the work tree (cloned or source-restored), so its children
+* are moved individually; every other top-level entry is moved wholesale.
+*
+* On a cache-hit execution agent the destinations do not pre-exist (source
+* restore excludes node_modules and never carries sibling dirs), so the renames
+* have nothing to race; the defensive `rm` covers re-runs.
+*/
+async function moveScratchIntoRepo(scratchDir, workDir) {
+	for (const child of await fsPromises.readdir(scratchDir)) if (child === ".kici") {
+		const kiciScratch = join(scratchDir, ".kici");
+		for (const sub of await fsPromises.readdir(kiciScratch)) await moveInto(join(kiciScratch, sub), join(workDir, ".kici", sub));
+	} else await moveInto(join(scratchDir, child), join(workDir, child));
+}
+/** Move `src` to `dest`, creating the parent and clearing any stale dest. */
+async function moveInto(src, dest) {
+	await mkdir(dirname(dest), { recursive: true });
+	await fsPromises.rm(dest, {
+		recursive: true,
+		force: true
+	});
+	await fsPromises.rename(src, dest);
+}
+/** Best-effort cleanup of a settled scratch dir; logs and continues on failure. */
+async function cleanupScratch(scratchDir) {
+	try {
+		await fsPromises.rm(scratchDir, {
+			recursive: true,
+			force: true
 		});
-		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}`
+	} catch (cleanupErr) {
+		logger$4.warn("Scratch dir cleanup failed (orphan left behind)", {
+			scratchDir,
+			error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
 		});
-		return {
-			success: false,
-			error
-		};
 	}
 }
+/**
+* Restore dependencies from a cached tarball into the cloned repo.
+*
+* The tarball is packed repo-root-relative (see `dep-packer.ts`): every manager
+* carries `.kici/node_modules`; pnpm additionally carries the root
+* `node_modules/.pnpm` store and the in-repo workspace siblings `.kici` resolves.
+* Restore extracts into a scratch dir, then moves each entry into place — one
+* code path for all managers.
+*
+* For HTTP/HTTPS URLs: a streaming pipeline (response -> hash -> gunzip -> tar)
+* with a 5-minute timeout and up to 2 retries avoids buffering whole tarballs.
+* For file:// URLs: 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$4.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}`);
+		}
+		const scratchDir = join(kiciDir, `${SCRATCH_DIR_BASENAME_PREFIX}${process.pid}-file-${Date.now()}`);
+		await extractTarball(data, scratchDir);
+		await moveScratchIntoRepo(scratchDir, workDir);
+		await cleanupScratch(scratchDir);
+		const sizeMB = (data.length / (1024 * 1024)).toFixed(2);
+		logger$4.info("Dependencies restored from cache (file)", {
+			sizeMB,
+			targetDir: workDir
+		});
+		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$4.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 moveScratchIntoRepo(scratchDir, workDir);
+			await cleanupScratch(scratchDir);
+			logger$4.info("Dependencies restored from cache (stream)", { targetDir: workDir });
+			return;
+		} catch (err) {
+			lastError = err instanceof Error ? err : new Error(String(err));
+			logger$4.warn("Dep tarball download failed", {
+				attempt,
+				error: lastError.message
+			});
+		}
+	}
+	throw new Error(`Dep tarball download failed after 3 attempts: ${lastError?.message}`);
+}
+var logger$4, DOWNLOAD_TIMEOUT_MS$2, SCRATCH_DIR_BASENAME_PREFIX, SCRATCH_DIR_GIT_EXCLUDE_GLOB;
+var init_dep_restore = __esmMin((() => {
+	logger$4 = createLogger({ prefix: "dep-restore" });
+	DOWNLOAD_TIMEOUT_MS$2 = 300 * 1e3;
+	SCRATCH_DIR_BASENAME_PREFIX = ".dep-restore-scratch-";
+	SCRATCH_DIR_GIT_EXCLUDE_GLOB = `.kici/${SCRATCH_DIR_BASENAME_PREFIX}*`;
+}));
 //#endregion
-//#region src/execution/rule-evaluator.ts
-initZx();
+//#region src/execution/download.ts
 /**
-* Create RuleContext for agent-side rule evaluation.
+* Shared HTTP/HTTPS download utility.
 *
-* @param event - Event payload from the dispatch message
-* @param changedFiles - List of files changed in this event
-* @param env - Merged environment variables
+* Extracted from workflow-loader.ts to avoid duplication across
+* dep-restore.ts and workflow-loader.ts.
 */
-function createRuleContext(event, changedFiles = [], env = {}) {
-	return {
-		event,
-		changedFiles,
-		env,
-		$
-	};
+var download_exports = /* @__PURE__ */ __exportAll({
+	downloadUrl: () => downloadUrl,
+	uploadToPresignedUrl: () => uploadToPresignedUrl
+});
+/**
+* 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$1) }, (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);
+	});
+}
+/**
+* Upload a buffer to a pre-signed S3 URL via HTTP PUT.
+*
+* Used for direct-to-S3 uploads of bundles and dep tarballs. Localhost /
+* 127.0.0.1 URLs are rewritten via `resolveOrchestratorUrl` so the
+* filesystem cache backend's signed URLs work from container agents that
+* can't reach the orchestrator's host loopback directly.
+*
+* @param url - The pre-signed URL to upload to
+* @param data - The buffer to upload
+*/
+function uploadToPresignedUrl(url, data) {
+	return new Promise((resolve, reject) => {
+		const resolved = resolveOrchestratorUrl(url);
+		const parsed = new URL(resolved);
+		const req = (parsed.protocol === "https:" ? https : http).request({
+			hostname: parsed.hostname,
+			port: parsed.port,
+			path: parsed.pathname + parsed.search,
+			method: "PUT",
+			headers: { "Content-Length": data.length }
+		}, (res) => {
+			if (res.statusCode && (res.statusCode < 200 || res.statusCode >= 300)) {
+				reject(/* @__PURE__ */ new Error(`HTTP ${res.statusCode} uploading to pre-signed URL`));
+				res.resume();
+				return;
+			}
+			res.resume();
+			res.on("end", () => resolve());
+			res.on("error", reject);
+		});
+		req.on("error", reject);
+		req.end(data);
+	});
 }
+var DOWNLOAD_TIMEOUT_MS$1;
+var init_download = __esmMin((() => {
+	init_dep_restore();
+	DOWNLOAD_TIMEOUT_MS$1 = 300 * 1e3;
+}));
 //#endregion
-//#region src/execution/sandbox/step-loop.ts
+//#region src/execution/cache/cache-engine.ts
 /**
-* Execute a single step with timeout enforcement.
+* User-facing cache engine (sandbox-side).
 *
-* Timeout pattern using Promise.race + AbortController, with IPC status reporting.
+* Packs `CacheSpec.paths` into a gzip tarball (mirrors dep-packer's tar+sha256
+* approach) and restores a tarball with on-the-fly SHA-256 verification
+* (mirrors dep-restore's streaming pipeline). Drives the orchestrator over an
+* injected request-response transport (IPC -> agent WS -> orchestrator).
+*
+* Path safety: each path is either `~`-prefixed (home-relative) or
+* repo-root-relative; absolute paths and `..` escapes are rejected so a
+* workflow cannot exfiltrate or clobber files outside its tree/home.
+*
+* Multi-root layout: a spec may mix repo-relative and home-relative paths.
+* Each entry is staged under an anchor prefix — `__repo__/<rel>` for
+* repo-root-relative entries, `__home__/<rel>` for `~`-prefixed entries — so a
+* single tarball can carry both roots and extract restores each group to the
+* right destination (repo entries under `workDir`, home entries under the
+* homedir). Extraction lands in a scratch dir first, then moves each group
+* into place so a partial restore never leaves half-written paths in the live
+* tree (mirrors dep-restore).
 */
-async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, outputsMap, getSecretsAccessLog, getSecretMountRecords) {
-	sendFn({
-		type: "step.start",
-		stepIndex,
-		stepName: step.name
+const logger$3 = createLogger({ prefix: "cache-engine" });
+/** Download timeout for a presigned cache GET: 5 minutes. */
+const DOWNLOAD_TIMEOUT_MS = 300 * 1e3;
+/** Anchor prefix for repo-root-relative cache entries inside the tar. */
+const REPO_ANCHOR = "__repo__";
+/** Anchor prefix for home-relative (`~`) cache entries inside the tar. */
+const HOME_ANCHOR = "__home__";
+/**
+* Resolve a cache path. `~`-prefixed -> home root; otherwise repo-root-relative.
+* Rejects absolute paths and `..` escapes so a workflow cannot read or clobber
+* files outside its tree / home.
+*/
+function resolveCachePath(workDir, p, roots) {
+	const home = roots?.home ?? homedir();
+	if (p === "~" || p.startsWith("~/")) {
+		const rel = p === "~" ? "" : p.slice(2);
+		return rel ? join(home, rel) : home;
+	}
+	if (isAbsolute(p)) throw new Error(`cache path must be repo-relative or ~-prefixed: ${p}`);
+	const resolved = resolve(workDir, p);
+	const rel = relative(workDir, resolved);
+	if (rel === ".." || rel.startsWith(`..${sep}`)) throw new Error(`cache path escapes the repo root: ${p}`);
+	return resolved;
+}
+/** Resolve + anchor every spec path; rejects escapes via resolveCachePath. */
+function anchorEntries(workDir, paths, roots) {
+	const home = roots?.home ?? homedir();
+	return paths.map((p) => {
+		const abs = resolveCachePath(workDir, p, roots);
+		const isHome = p === "~" || p.startsWith("~/");
+		return {
+			abs,
+			anchor: isHome ? HOME_ANCHOR : REPO_ANCHOR,
+			rel: relative(isHome ? home : workDir, abs)
+		};
 	});
-	const startTime = Date.now();
-	const abortController = new AbortController();
-	const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
+}
+/**
+* Pack the spec's paths into a gzip tarball + its SHA-256.
+*
+* Each path is copied into a staging dir under its anchor prefix
+* (`__repo__/<rel>` or `__home__/<rel>`), the staging dir is tarred (portable
+* mode strips uid/gid/mtime), and the staging dir is removed. The resulting
+* tarball self-describes which root each entry restores to.
+*/
+async function packCachePaths(workDir, paths, roots) {
+	const entries = anchorEntries(workDir, paths, roots);
+	const staging = await mkdtemp(join(tmpdir(), "kici-cache-pack-"));
 	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`));
+		const topLevel = /* @__PURE__ */ new Set();
+		for (const e of entries) {
+			const dest = join(staging, e.anchor, e.rel);
+			await mkdir(dirname(dest), { recursive: true });
+			await cp(e.abs, dest, {
+				recursive: true,
+				verbatimSymlinks: true
 			});
-		})]);
-		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 }
+			topLevel.add(e.anchor);
+		}
+		const stream = c({
+			gzip: true,
+			portable: true,
+			cwd: staging
+		}, [...topLevel]);
+		const chunks = [];
+		for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+		const tarball = Buffer.concat(chunks);
+		const hash = sha256(tarball);
+		logger$3.info("packed user cache", {
+			sizeBytes: tarball.length,
+			hash: hash.slice(0, 12),
+			paths
 		});
 		return {
-			name: step.name,
-			stepIndex,
-			status: ExecutionStepStatus.enum.success,
-			durationMs,
-			...outputsPayload && { outputs: outputsPayload }
+			tarball,
+			hash
 		};
-	} 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 }
+	} finally {
+		await rm(staging, {
+			recursive: true,
+			force: true
 		});
-		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;
+/** Move the extracted `__repo__` / `__home__` groups from a scratch dir into place. */
+async function moveAnchoredGroups(scratchDir, workDir, home) {
+	for (const anchor of await readdir(scratchDir)) {
+		const anchorDir = join(scratchDir, anchor);
+		const destRoot = anchor === HOME_ANCHOR ? home : anchor === REPO_ANCHOR ? workDir : null;
+		if (!destRoot) continue;
+		for (const child of await readdir(anchorDir)) {
+			const dest = join(destRoot, child);
+			await mkdir(dirname(dest), { recursive: true });
+			await rm(dest, {
+				recursive: true,
+				force: true
+			});
+			await rename(join(anchorDir, child), dest);
+		}
+	}
 }
 /**
-* Evaluate step-level rules. Returns a 'skipped' result + emits IPC when a rule
-* fails; returns null when the step should run normally.
+* Stream-download a presigned URL, verify its SHA-256 on the fly (mirrors
+* dep-restore's response -> hash -> gunzip -> tar pipeline), then move the
+* anchored groups into place. Extracts into a scratch dir so a failed download
+* never half-writes the live tree.
 */
-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`
-	});
+async function downloadAndExtractCache(url, workDir, expectedHash, roots) {
+	const home = roots?.home ?? homedir();
+	const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+	if (!response.ok || !response.body) throw new Error(`cache download HTTP ${response.status}`);
+	const hash = createHash("sha256");
+	const hashTransform = new Transform({ transform(chunk, _enc, cb) {
+		hash.update(chunk);
+		cb(null, chunk);
+	} });
+	await mkdir(workDir, { recursive: true });
+	const scratch = await mkdtemp(join(tmpdir(), "kici-cache-extract-"));
+	try {
+		await pipeline(Readable.fromWeb(response.body), hashTransform, createGunzip(), x({ cwd: scratch }));
+		const digest = hash.digest("hex");
+		if (digest !== expectedHash) throw new Error(`Cache tarball checksum mismatch on download: expected ${expectedHash}, got ${digest}`);
+		await moveAnchoredGroups(scratch, workDir, home);
+	} finally {
+		await rm(scratch, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Build the imperative `ctx.cache` API bound to a workDir + transport. */
+function createCacheApi(workDir, transport, roots) {
 	return {
-		name: step.name,
-		stepIndex,
-		status: ExecutionStepStatus.enum.skipped,
-		durationMs: 0
+		async restore(spec) {
+			const r = await transport.restore(spec.key, spec.restoreKeys);
+			if (!r.hit || !r.downloadUrl || !r.tarHash) return { hit: false };
+			await downloadAndExtractCache(r.downloadUrl, workDir, r.tarHash, roots);
+			logger$3.info("user cache restored", {
+				key: spec.key,
+				matchedKey: r.matchedKey
+			});
+			return {
+				hit: true,
+				matchedKey: r.matchedKey
+			};
+		},
+		async save(spec) {
+			const begin = await transport.beginSave(spec.key);
+			if (begin.skip || !begin.uploadUrl) {
+				logger$3.info("user cache save skipped (key exists)", { key: spec.key });
+				return;
+			}
+			const { tarball, hash } = await packCachePaths(workDir, spec.paths, roots);
+			const { uploadToPresignedUrl } = await Promise.resolve().then(() => (init_download(), download_exports));
+			await uploadToPresignedUrl(begin.uploadUrl, tarball);
+			await transport.completeSave(spec.key, hash, tarball.length);
+			logger$3.info("user cache saved", {
+				key: spec.key,
+				sizeBytes: tarball.length
+			});
+		}
 	};
 }
+//#endregion
+//#region src/execution/cache/cache-phase.ts
 /**
-* 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.
+* Declarative cache phase (sandbox-side).
+*
+* Restores a list of {@link CacheSpec} before the work that depends on them
+* (a job before its steps, or a step before its `run`) and saves them after
+* (on an exact-key miss). Each operation surfaces as a `cache:restore` /
+* `cache:save` pseudo-step — a `step.start` + `step.complete` IPC pair whose
+* `step_type` comes from {@link CacheStepType} — exactly mirroring how hooks
+* render as `hook:*` pseudo-steps. The `step.complete` `data` carries the
+* {@link CacheOutcome} (plus key / matchedKey / bytes) so the agent can feed a
+* `run.event` and the dashboard can render hit/miss/saved inline.
 */
-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.
+* Restore every spec, surfacing each as a `cache:restore` pseudo-step. Returns
+* a map keyed by spec key recording whether the EXACT key hit (so the save
+* phase can skip a redundant save of an entry that already exists).
 */
-async function 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,
+async function restoreCacheSpecs(specs, deps) {
+	const results = /* @__PURE__ */ new Map();
+	for (const spec of specs) {
+		const stepIndex = deps.nextStepIndex();
+		deps.sendIpc({
+			type: "step.start",
 			stepIndex,
-			hookStepIndex: opts.steps.length + stepIndex * 2 + 1,
-			failedStep: result.status === ExecutionStepStatus.enum.failed ? step.name : void 0,
-			opts
+			stepName: `cache restore: ${spec.key}`,
+			step_type: CacheStepType.enum["cache:restore"]
 		});
-		if (result.status === ExecutionStepStatus.enum.failed) return {
-			result,
-			shouldBreak: !step.continueOnError,
-			failedStepName: step.name
-		};
-		return {
-			result,
-			shouldBreak: false
-		};
-	} finally {
-		await opts.disposeStepResources?.();
+		const start = Date.now();
+		try {
+			const r = await deps.cache.restore(spec);
+			results.set(spec.key, {
+				hit: r.hit,
+				matchedKey: r.matchedKey
+			});
+			deps.sendIpc({
+				type: "step.complete",
+				stepIndex,
+				status: "success",
+				durationMs: Date.now() - start,
+				step_type: CacheStepType.enum["cache:restore"],
+				data: {
+					cacheOutcome: r.hit ? CacheOutcome.enum.hit : CacheOutcome.enum.miss,
+					key: spec.key,
+					...r.matchedKey !== void 0 && { matchedKey: r.matchedKey }
+				}
+			});
+		} catch (e) {
+			results.set(spec.key, { hit: false });
+			deps.sendIpc({
+				type: "step.complete",
+				stepIndex,
+				status: "failed",
+				durationMs: Date.now() - start,
+				error: { message: toErrorMessage(e) },
+				step_type: CacheStepType.enum["cache:restore"],
+				data: {
+					cacheOutcome: CacheOutcome.enum.error,
+					key: spec.key
+				}
+			});
+		}
 	}
+	return results;
 }
 /**
-* 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.
+* Save every spec whose EXACT key did not already hit on restore (immutable +
+* no redundant save), surfacing each as a `cache:save` pseudo-step. A spec
+* whose restore matched a different key via a `restoreKeys` prefix is still
+* saved under its exact key.
 */
-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`
+async function saveCacheSpecs(specs, restoreResults, deps) {
+	for (const spec of specs) {
+		if (restoreResults.get(spec.key)?.matchedKey === spec.key) continue;
+		const stepIndex = deps.nextStepIndex();
+		deps.sendIpc({
+			type: "step.start",
+			stepIndex,
+			stepName: `cache save: ${spec.key}`,
+			step_type: CacheStepType.enum["cache:save"]
 		});
-		return state;
+		const start = Date.now();
+		try {
+			await deps.cache.save(spec);
+			deps.sendIpc({
+				type: "step.complete",
+				stepIndex,
+				status: "success",
+				durationMs: Date.now() - start,
+				step_type: CacheStepType.enum["cache:save"],
+				data: {
+					cacheOutcome: CacheOutcome.enum.saved,
+					key: spec.key
+				}
+			});
+		} catch (e) {
+			deps.sendIpc({
+				type: "step.complete",
+				stepIndex,
+				status: "failed",
+				durationMs: Date.now() - start,
+				error: { message: toErrorMessage(e) },
+				step_type: CacheStepType.enum["cache:save"],
+				data: {
+					cacheOutcome: CacheOutcome.enum.error,
+					key: spec.key
+				}
+			});
+		}
 	}
-	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
-	};
 }
+//#endregion
+//#region src/execution/sandbox/log-masker.ts
 /**
-* 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.
+* 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)).
 */
-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;
+/** 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, "\\$&");
 }
 /**
-* Execute the step loop with hook integration and step-level rule evaluation.
+* Masks secret values in log lines.
 *
-* Hook execution order:
-* - beforeStep -> step -> afterStep (per step)
-* - onSuccess or onFailure (after all steps)
-* - cleanup (always, after onSuccess/onFailure)
+* 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/env-delta.ts
+/**
+* Apply an environment delta to `target` (defaults to process.env), honoring the
+* operator-secret guard.
 *
-* Hooks are observers: beforeStep/afterStep failures do NOT affect step execution.
-* Only completion hooks (onSuccess/onFailure/cleanup) can change job status to failed.
+* - env keys present in `operatorSecretKeys` are rejected (never override an
+*   operator secret); `onReject` fires once per rejected key.
+* - pathPrepends are applied so the FIRST array entry ends up FIRST on PATH.
 */
-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;
+function applyEnvDelta(delta, options) {
+	const target = options.target ?? process.env;
+	const appliedKeys = [];
+	const rejectedKeys = [];
+	for (const [key, value] of Object.entries(delta.env)) {
+		if (options.operatorSecretKeys.has(key)) {
+			rejectedKeys.push(key);
+			options.onReject?.(key);
+			continue;
 		}
-		if (outcome.shouldBreak) break;
+		target[key] = value;
+		appliedKeys.push(key);
+	}
+	const appliedPaths = [];
+	if (delta.pathPrepends.length > 0) {
+		for (const dir of [...delta.pathPrepends].reverse()) target.PATH = target.PATH ? `${dir}:${target.PATH}` : dir;
+		appliedPaths.push(...delta.pathPrepends);
 	}
-	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
+		appliedKeys,
+		rejectedKeys,
+		appliedPaths
 	};
 }
 //#endregion
-//#region src/checkout/ssh-auth.ts
+//#region src/execution/sandbox/env-file.ts
 /**
-* Materialize an SSH private key (and optional pinned known_hosts) into a
-* tempdir and build the `GIT_SSH_COMMAND` that `git clone` needs.
+* KICI_ENV / KICI_PATH temp-file contract.
 *
-* Permissions:
-*   - private key mode 0o600 (required by OpenSSH — refuses to use world-
-*     readable keys).
-*   - known_hosts mode 0o600.
-*   - tempdir mode 0o700.
+* Before each step the agent points the KICI_ENV and KICI_PATH env vars at fresh
+* temp files. A step's shell commands append `KEY=value` lines to $KICI_ENV and
+* one directory per line to $KICI_PATH. After the step the agent parses both
+* files into an EnvDelta and feeds it through applyEnvDelta() -- the same path
+* the JS API (ctx.setEnv / ctx.addPath) uses -- then truncates the files for the
+* next step.
 *
-* 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`.
+* Format v1: single-line `KEY=value` for env (no embedded newlines); one
+* directory per line for path. Blank lines and lines without `=` are ignored.
 */
-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");
+/**
+* Parse `KEY=value` lines into a record. Blank lines, lines without `=`, and
+* lines with an empty key are ignored. The split is on the first `=` only, so a
+* value may contain `=`. The key is trimmed; the value is taken verbatim after
+* the first `=`. Last assignment to a key wins.
+*/
+function parseEnvFileContent(content) {
+	const out = {};
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.trim();
+		if (line.length === 0) continue;
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+		const key = line.slice(0, eq).trim();
+		if (key.length === 0) continue;
+		out[key] = line.slice(eq + 1);
+	}
+	return out;
+}
+/** Parse one trimmed directory per non-blank line, preserving order. */
+function parsePathFileContent(content) {
+	const out = [];
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.trim();
+		if (line.length === 0) continue;
+		out.push(line);
+	}
+	return out;
+}
+/** Create fresh, empty env + path files inside a private temp dir under `baseDir`. */
+async function createEnvFiles(baseDir) {
+	const dir = await mkdtemp(join(baseDir, "kici-env-"));
+	const envFile = join(dir, "env");
+	const pathFile = join(dir, "path");
+	await writeFile(envFile, "");
+	await writeFile(pathFile, "");
 	return {
-		gitSshCommand: parts.join(" "),
-		tempDir,
-		async cleanup() {
-			await rm(tempDir, {
-				recursive: true,
-				force: true
-			});
-		}
+		envFile,
+		pathFile
+	};
+}
+/** Read + parse both files into an EnvDelta. Missing/empty files yield an empty delta. */
+async function readEnvDelta(files) {
+	const [envContent, pathContent] = await Promise.all([readFile(files.envFile, "utf8").catch(() => ""), readFile(files.pathFile, "utf8").catch(() => "")]);
+	return {
+		env: parseEnvFileContent(envContent),
+		pathPrepends: parsePathFileContent(pathContent)
 	};
 }
+/** Truncate both files to empty so the next step starts clean. */
+async function truncateEnvFiles(files) {
+	await Promise.all([writeFile(files.envFile, ""), writeFile(files.pathFile, "")]);
+}
+//#endregion
+//#region src/execution/sandbox/secret-merge.ts
 /**
-* 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.
+* 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()).
 */
-function escapeShellArg(value) {
-	return `'${value.replace(/'/g, "'\\''")}'`;
+/**
+* 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/checkout/git-clone.ts
+//#region src/execution/hook-executor.ts
+/** Default hook timeout: 5 minutes */
+const DEFAULT_HOOK_TIMEOUT_MS = 300 * 1e3;
 /**
-* 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.
+* Build outcome metadata from execution state.
+*
+* Duration is calculated as elapsed time since startTime.
 */
-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 buildOutcomeMetadata(opts) {
+	return {
+		status: opts.status,
+		reason: opts.reason,
+		failedStep: opts.failedStep,
+		stepOutputs: opts.stepOutputs,
+		duration: Date.now() - opts.startTime
+	};
 }
-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]");
+/**
+* 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}`);
 }
 /**
-* 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.
+* Execute a single hook with timeout enforcement and IPC reporting.
 *
-* @throws Error if clone fails or SHA does not match
+* 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 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;
+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 {
-		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
+		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`));
 			});
-			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();
+		})]);
+		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/dep-restore.ts
+//#region src/execution/rule-evaluator.ts
+initZx();
 /**
-* 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.
+* Create RuleContext for agent-side rule evaluation.
 *
-* 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).
+* @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.
 *
-* Streaming downloads have a 5-minute timeout and up to 2 retries.
+* Timeout pattern using Promise.race + AbortController, with IPC status reporting.
+*/
+async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, outputsMap, getSecretsAccessLog, getSecretMountRecords, jobDeadlineSignal) {
+	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`));
+				});
+			}),
+			new Promise((_, reject) => {
+				if (!jobDeadlineSignal) return;
+				if (jobDeadlineSignal.aborted) {
+					reject(/* @__PURE__ */ new Error(`Step '${step.name}' aborted: job timeout exceeded`));
+					return;
+				}
+				jobDeadlineSignal.addEventListener("abort", () => {
+					reject(/* @__PURE__ */ new Error(`Step '${step.name}' aborted: job timeout exceeded`));
+				});
+			})
+		]);
+		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.
 */
-const logger$3 = createLogger({ prefix: "dep-restore" });
-/** Download timeout: 5 minutes. */
-const DOWNLOAD_TIMEOUT_MS$1 = 300 * 1e3;
+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;
+}
 /**
-* Compute SHA-256 hash of a buffer.
+* Evaluate step-level rules. Returns a 'skipped' result + emits IPC when a rule
+* fails; returns null when the step should run normally.
 */
-function computeHash(data) {
-	return sha256(data);
+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
+	};
 }
 /**
-* Extract a gzip tarball from a buffer into the target directory.
-* Used for file:// URLs where streaming provides no benefit.
+* Manual approval gate for a step. When the step declares `requireApproval`
+* and the harness wired `awaitStepApproval`, block until the orchestrator
+* resolves the hold. Returns a failed `StepIterationOutcome` (breaking the
+* loop) on reject/expired; returns null when approved or when no gate applies.
 */
-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);
+async function maybeGateStepApproval(step, stepIndex, opts) {
+	if (step.requireApproval === void 0 || !opts.awaitStepApproval) return null;
+	const normalized = normalizeRequireApproval(step.requireApproval);
+	opts.sendIpc({
+		type: "log.line",
+		stepIndex,
+		line: `[kici] Step '${step.name}' awaiting approval...`
+	});
+	const resolution = await opts.awaitStepApproval({
+		stepIndex,
+		stepName: step.name,
+		clauses: normalized.clauses,
+		reason: normalized.reason ?? `Approval required for step '${step.name}'`,
+		timeoutSeconds: normalized.timeoutSeconds
+	});
+	if (resolution.outcome === "approved") {
+		opts.sendIpc({
+			type: "log.line",
+			stepIndex,
+			line: `[kici] Step '${step.name}' approved.`
+		});
+		return null;
+	}
+	const why = resolution.outcome === "expired" ? "approval expired" : `approval rejected${resolution.reason ? `: ${resolution.reason}` : ""}`;
+	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}' ${why}.`
+	});
+	await opts.disposeStepResources?.();
+	return {
+		result: {
+			name: step.name,
+			stepIndex,
+			status: ExecutionStepStatus.enum.failed,
+			durationMs: 0,
+			error: { message: `Step '${step.name}' ${why}` }
+		},
+		shouldBreak: true,
+		failedStepName: step.name
+	};
+}
+/**
+* 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)`
 	});
 }
 /**
-* Stream download and extract an HTTP/HTTPS tarball.
+* 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.
 *
-* Computes SHA-256 hash on the fly via a Transform stream.
-* Returns the computed hash of the compressed tarball data.
+* 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 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");
+async function runStepIteration(step, stepIndex, opts) {
+	const skippedResult = await evaluateStepRulesAndMaybeSkip(step, stepIndex, opts);
+	if (skippedResult) {
+		await opts.disposeStepResources?.();
+		return {
+			result: skippedResult,
+			shouldBreak: false
+		};
+	}
+	const gate = await maybeGateStepApproval(step, stepIndex, opts);
+	if (gate) return gate;
+	if (opts.jobHooks?.beforeStep) await runObserverHook({
+		hook: opts.jobHooks.beforeStep,
+		hookType: "beforeStep",
+		step,
+		stepIndex,
+		hookStepIndex: opts.steps.length + stepIndex * 2,
+		opts
+	});
+	const stepCacheSpecs = opts.cachePhaseDeps ? normalizeCacheSpecs(step.cache) : [];
+	const stepCacheRestore = stepCacheSpecs.length > 0 && opts.cachePhaseDeps ? await restoreCacheSpecs(stepCacheSpecs, opts.cachePhaseDeps) : /* @__PURE__ */ new Map();
+	try {
+		await opts.beforeStepEnvFiles?.();
+		const ctx = opts.createStepContext(stepIndex, step.name);
+		const timeoutMs = step.timeout ?? opts.defaultTimeoutMs;
+		let result;
+		try {
+			result = await executeStepInLoop(step, stepIndex, ctx, timeoutMs, opts.sendIpc, opts.outputsMap, opts.getSecretsAccessLog, opts.getSecretMountRecords, opts.jobDeadlineSignal);
+		} finally {
+			await opts.afterStepApplyEnvFiles?.();
+		}
+		if (stepCacheSpecs.length > 0 && opts.cachePhaseDeps && result.status === ExecutionStepStatus.enum.success) await saveCacheSpecs(stepCacheSpecs, stepCacheRestore, opts.cachePhaseDeps);
+		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?.();
+	}
 }
 /**
-* 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 `moveScratchIntoRepo` renames the extracted entries into place
-* (atomic on the same filesystem), then best-effort cleans 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`.
+* 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 extractIntoScratch(url, kiciDir, attempt) {
-	const scratchDir = join(kiciDir, `${SCRATCH_DIR_BASENAME_PREFIX}${process.pid}-${attempt}-${Date.now()}`);
-	await mkdir(scratchDir, { recursive: true });
+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 {
-		scratchDir,
-		hash: await streamFetchAndExtract(url, scratchDir)
+		failed: state.failed || promoteToFailed,
+		failedStepName: state.failedStepName,
+		failureReason: state.failureReason ? `${state.failureReason}; ${reasonFragment}` : reasonFragment
 	};
 }
 /**
-* 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.
+* 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.
 *
-* Idempotent: callers may invoke this multiple times (dual-clone path, retry
-* after partial setup). We skip the append if the glob is already present.
+* Hook execution order:
+* - beforeStep -> step -> afterStep (per step)
+* - onSuccess or onFailure (after all steps)
+* - cleanup (always, after onSuccess/onFailure)
 *
-* @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).
+* 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 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)
-		});
+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/execution/env-init/init-phase.ts
+/** Default init timeout when a spec sets none: 10 minutes. */
+const DEFAULT_INIT_TIMEOUT_MS = 600 * 1e3;
 /**
-* 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.
+* Marker thrown when an init command exceeds its wall-clock budget. Carries the
+* distinct P3 timeout reason so the phase result + job.complete report a timeout
+* rather than a generic failure.
 */
-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;
+var InitTimeoutError = class extends Error {
+	reason = TimeoutReason.enum.job_timeout;
+	constructor(timeoutMs) {
+		super(`init command exceeded its timeout of ${timeoutMs}ms`);
+		this.name = "InitTimeoutError";
+	}
+};
+/** Run all init specs in order; stop + fail at the first non-zero / timeout. */
+async function runInitPhase(opts) {
+	if (!opts.specs || opts.specs.length === 0) return { ok: true };
+	for (let i = 0; i < opts.specs.length; i++) {
+		const spec = opts.specs[i];
+		const stepIndex = opts.stepIndexBase + i;
+		const stepType = `init:${i}`;
+		const outcome = await runOneInit(spec, i, stepIndex, stepType, opts);
+		if (!outcome.ok) return {
+			ok: false,
+			failedInitIndex: i,
+			error: outcome.error,
+			...outcome.timedOut && {
+				timedOut: true,
+				reason: outcome.reason
+			}
+		};
 	}
+	return { ok: true };
 }
 /**
-* Move a fully-extracted scratch tree into the cloned repo. The dep tarball is
-* packed repo-root-relative, so the scratch holds repo-root entries:
-* `.kici/node_modules` for every manager, plus (for pnpm) the root
-* `node_modules/.pnpm` store and in-repo workspace sibling dirs. `.kici/` itself
-* already exists in the work tree (cloned or source-restored), so its children
-* are moved individually; every other top-level entry is moved wholesale.
-*
-* On a cache-hit execution agent the destinations do not pre-exist (source
-* restore excludes node_modules and never carries sibling dirs), so the renames
-* have nothing to race; the defensive `rm` covers re-runs.
+* Run a promise against a wall-clock budget. Aborts via an AbortController on
+* breach (mirroring the step loop) and rejects with an {@link InitTimeoutError}
+* carrying the distinct P3 timeout reason. Resolves with the command's value
+* when it finishes first.
 */
-async function moveScratchIntoRepo(scratchDir, workDir) {
-	for (const child of await fsPromises.readdir(scratchDir)) if (child === ".kici") {
-		const kiciScratch = join(scratchDir, ".kici");
-		for (const sub of await fsPromises.readdir(kiciScratch)) await moveInto(join(kiciScratch, sub), join(workDir, ".kici", sub));
-	} else await moveInto(join(scratchDir, child), join(workDir, child));
+function withInitTimeout(run, timeoutMs) {
+	const ac = new AbortController();
+	const timer = setTimeout(() => ac.abort(), timeoutMs);
+	return Promise.race([run, new Promise((_, reject) => {
+		ac.signal.addEventListener("abort", () => reject(new InitTimeoutError(timeoutMs)));
+	})]).finally(() => clearTimeout(timer));
 }
-/** Move `src` to `dest`, creating the parent and clearing any stale dest. */
-async function moveInto(src, dest) {
-	await mkdir(dirname(dest), { recursive: true });
-	await fsPromises.rm(dest, {
-		recursive: true,
-		force: true
+async function runOneInit(spec, index, stepIndex, stepType, opts) {
+	opts.sendIpc({
+		type: "step.start",
+		stepIndex,
+		stepName: stepType,
+		step_type: stepType
 	});
-	await fsPromises.rename(src, dest);
-}
-/** Best-effort cleanup of a settled scratch dir; logs and continues on failure. */
-async function cleanupScratch(scratchDir) {
+	const start = Date.now();
+	const shell = spec.shell ?? "bash";
 	try {
-		await fsPromises.rm(scratchDir, {
-			recursive: true,
-			force: true
+		let cacheHit = false;
+		if (spec.cache && opts.cache) cacheHit = (await opts.cache.restore(spec.cache)).hit;
+		await opts.env?.beginCapture();
+		const $ = opts.shellFor(spec, index);
+		const timeoutMs = spec.timeout ?? DEFAULT_INIT_TIMEOUT_MS;
+		await withInitTimeout($`${shell} -c ${spec.run}`, timeoutMs);
+		if (spec.cache && opts.cache && !cacheHit) await opts.cache.save(spec.cache);
+		await opts.env?.applyDelta();
+		opts.sendIpc({
+			type: "step.complete",
+			stepIndex,
+			status: ExecutionStepStatus.enum.success,
+			durationMs: Date.now() - start,
+			step_type: stepType
 		});
-	} catch (cleanupErr) {
-		logger$3.warn("Scratch dir cleanup failed (orphan left behind)", {
-			scratchDir,
-			error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
+		return { ok: true };
+	} catch (e) {
+		const error = toErrorMessage(e);
+		const timedOut = e instanceof InitTimeoutError;
+		const exitCode = e && typeof e === "object" && "exitCode" in e && typeof e.exitCode === "number" ? e.exitCode : void 0;
+		opts.sendIpc({
+			type: "step.complete",
+			stepIndex,
+			status: ExecutionStepStatus.enum.failed,
+			durationMs: Date.now() - start,
+			error: {
+				message: error,
+				...exitCode !== void 0 && { exitCode }
+			},
+			step_type: stepType
 		});
+		return {
+			ok: false,
+			error,
+			...timedOut && {
+				timedOut: true,
+				reason: e.reason
+			}
+		};
 	}
 }
+//#endregion
+//#region src/execution/sandbox/job-deadline.ts
 /**
-* Restore dependencies from a cached tarball into the cloned repo.
-*
-* The tarball is packed repo-root-relative (see `dep-packer.ts`): every manager
-* carries `.kici/node_modules`; pnpm additionally carries the root
-* `node_modules/.pnpm` store and the in-repo workspace siblings `.kici` resolves.
-* Restore extracts into a scratch dir, then moves each entry into place — one
-* code path for all managers.
+* Arm a job-level wall-clock deadline. When `timeoutMs` is set and elapses
+* before clear() is called, invokes `onTimeout` with the distinct
+* `job_timeout` reason and the configured budget. A no-op when `timeoutMs`
+* is undefined (no job-level cap configured).
+*/
+function armJobDeadline(timeoutMs, onTimeout) {
+	if (timeoutMs === void 0 || timeoutMs <= 0) return { clear: () => {} };
+	const timer = setTimeout(() => {
+		onTimeout(TimeoutReason.enum.job_timeout, timeoutMs);
+	}, timeoutMs);
+	timer.unref?.();
+	return { clear: () => clearTimeout(timer) };
+}
+//#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.
 *
-* For HTTP/HTTPS URLs: a streaming pipeline (response -> hash -> gunzip -> tar)
-* with a 5-minute timeout and up to 2 retries avoids buffering whole tarballs.
-* For file:// URLs: a buffer-based approach (local, no streaming benefit).
+* Permissions:
+*   - private key mode 0o600 (required by OpenSSH — refuses to use world-
+*     readable keys).
+*   - known_hosts mode 0o600.
+*   - tempdir mode 0o700.
 *
-* @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
+* 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 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}`);
+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
+			});
 		}
-		const scratchDir = join(kiciDir, `${SCRATCH_DIR_BASENAME_PREFIX}${process.pid}-file-${Date.now()}`);
-		await extractTarball(data, scratchDir);
-		await moveScratchIntoRepo(scratchDir, workDir);
-		await cleanupScratch(scratchDir);
-		const sizeMB = (data.length / (1024 * 1024)).toFixed(2);
-		logger$3.info("Dependencies restored from cache (file)", {
-			sizeMB,
-			targetDir: workDir
-		});
-		return;
+	};
+}
+/**
+* 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(() => {});
+		};
 	}
-	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
-		});
+	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 {
-			const { scratchDir, hash } = await extractIntoScratch(depsUrl, kiciDir, attempt);
-			if (depsHash && hash !== depsHash) throw new Error(`Dep tarball hash mismatch: expected ${depsHash}, got ${hash}`);
-			await moveScratchIntoRepo(scratchDir, workDir);
-			await cleanupScratch(scratchDir);
-			logger$3.info("Dependencies restored from cache (stream)", { targetDir: workDir });
-			return;
+			execFileSync("git", args, {
+				stdio: "pipe",
+				timeout: 12e4,
+				...env && { env }
+			});
 		} catch (err) {
-			lastError = err instanceof Error ? err : new Error(String(err));
-			logger$3.warn("Dep tarball download failed", {
-				attempt,
-				error: lastError.message
+			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();
 	}
-	throw new Error(`Dep tarball download failed after 3 attempts: ${lastError?.message}`);
 }
 //#endregion
 //#region src/execution/npm-resolver.ts
@@ -1565,8 +2240,8 @@ function logSubprocessStreams(e, tokens) {
 * no Rolldown step at runtime. `@kici-dev/sdk` and host-repo deps resolve via
 * Node's normal ESM lookup against `.kici/node_modules/`.
 */
-const AGENT_SDK_VERSION = "0.1.14";
-const AGENT_SDK_BUNDLE_HASH = "675aafe4de03e677785ef2794d8f34951b14e2bd1e6f0ea825953d6c2abfe128";
+const AGENT_SDK_VERSION = "0.1.16";
+const AGENT_SDK_BUNDLE_HASH = "cd4b8e0d91efe578c96e7c746f89b44a3df8fcaebaec2185399168ef8eb4ebca";
 /**
 * Register the `@kici-dev/core/ts-loader-hook` oxc-transform ESM loader hook so
 * subsequent dynamic `import()` calls for `.ts` / `.tsx` files transform on the
@@ -1727,40 +2402,6 @@ async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event
 	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.
@@ -1783,6 +2424,8 @@ function downloadUrl(url) {
 * runs without a preceding build (cache infrastructure unavailable, or a
 * build job that failed but left dynamic dispatch in flight).
 */
+init_download();
+init_dep_restore();
 const logger$1 = createLogger({ prefix: "source-restore" });
 async function extractSourceTarball(data, targetDir) {
 	await mkdir(targetDir, { recursive: true });
@@ -1824,6 +2467,7 @@ async function restoreSource(workDir, sourceTarUrl) {
 * Wire format: [12-byte IV][16-byte auth tag][ciphertext]
 * Same encryption scheme as packages/compiler/src/remote/encryption.ts.
 */
+init_download();
 const logger = createLogger({ prefix: "overlay-applier" });
 const IV_LENGTH = 12;
 const AUTH_TAG_LENGTH = 16;
@@ -1957,6 +2601,7 @@ async function applyOverlay(config) {
 * This file is compiled alongside the agent by rolldown (existing build), but
 * runs as a SEPARATE process spawned by the sandbox backend.
 */
+init_dep_restore();
 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`);
@@ -2139,6 +2784,21 @@ let aborted = false;
 */
 let forceAborted = false;
 /**
+* Set when the job-level wall-clock deadline (the lock job's `timeout`) is
+* breached. Trips the same abort path cancellation uses, but tags the
+* job.complete with the distinct TimeoutReason.job_timeout reason.
+*/
+let jobTimedOut = false;
+/** The configured job timeout budget in ms, captured when the deadline fires. */
+let jobTimedOutMs;
+/**
+* Aborted when the job-level deadline fires. Threaded into the step loop so the
+* IN-FLIGHT step (e.g. a long-running `sleep`) is interrupted immediately on
+* breach — the between-steps `isAborted()` check alone cannot unwind a single
+* long step that has no per-step `timeout`.
+*/
+const jobDeadlineAbort = new AbortController();
+/**
 * Pending promises for event.emit requests awaiting responses from the agent.
 *
 * Key: requestId (correlates EventEmitRequest -> EventEmitResponse)
@@ -2245,6 +2905,190 @@ function waitForApiResponse(requestId) {
 	});
 }
 /**
+* Pending promises for cache.response messages from the agent.
+* Key: requestId (correlates cache.request -> cache.response).
+*/
+const pendingCacheResponses = /* @__PURE__ */ new Map();
+/** Default timeout for a cache request relay (matches the upload-URL request budget). */
+const CACHE_RESPONSE_TIMEOUT_MS = 3e4;
+/** Wait for a cache.response from the agent with the given requestId. */
+function waitForCacheResponse(requestId) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			pendingCacheResponses.delete(requestId);
+			reject(/* @__PURE__ */ new Error(`Cache request timed out after ${CACHE_RESPONSE_TIMEOUT_MS}ms`));
+		}, CACHE_RESPONSE_TIMEOUT_MS);
+		pendingCacheResponses.set(requestId, {
+			resolve: (response) => {
+				clearTimeout(timer);
+				pendingCacheResponses.delete(requestId);
+				resolve(response);
+			},
+			reject: (err) => {
+				clearTimeout(timer);
+				pendingCacheResponses.delete(requestId);
+				reject(err);
+			},
+			timer
+		});
+	});
+}
+/**
+* Pending promises for approval.resolved messages from the agent.
+* Key: requestId (correlates approval.request -> approval.resolved).
+*/
+const pendingApprovalResolutions = /* @__PURE__ */ new Map();
+/**
+* Hard ceiling on how long the runner blocks a step waiting for an approval
+* resolution. The orchestrator enforces the real (org-/SDK-configured) expiry
+* and sends `expired` when it lapses; this is a safety net well above any sane
+* approval window so the runner cannot hang forever if the resolution is lost.
+*/
+const APPROVAL_RESOLUTION_TIMEOUT_MS = 10080 * 60 * 1e3;
+/** Wait for an approval.resolved from the agent with the given requestId. */
+function waitForApprovalResolution(requestId) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			pendingApprovalResolutions.delete(requestId);
+			resolve({
+				type: "approval.resolved",
+				requestId,
+				outcome: "expired"
+			});
+		}, APPROVAL_RESOLUTION_TIMEOUT_MS);
+		pendingApprovalResolutions.set(requestId, {
+			resolve: (response) => {
+				clearTimeout(timer);
+				pendingApprovalResolutions.delete(requestId);
+				resolve(response);
+			},
+			timer
+		});
+	});
+}
+/**
+* Build the `awaitStepApproval` callback the step loop uses to block on a
+* `requireApproval` step. Sends an `approval.request` IPC (relayed by the agent
+* over the WS as a `step.approval-request`) and awaits the matching
+* `approval.resolved`. A relay error is treated as a fail-closed reject.
+*/
+function buildAwaitStepApproval() {
+	return async (req) => {
+		const requestId = randomUUID();
+		sendMessage({
+			type: "approval.request",
+			requestId,
+			stepIndex: req.stepIndex,
+			stepName: req.stepName,
+			clauses: req.clauses,
+			reason: req.reason,
+			...req.timeoutSeconds !== void 0 && { timeoutSeconds: req.timeoutSeconds }
+		});
+		const resolution = await waitForApprovalResolution(requestId);
+		if (resolution.error) return {
+			outcome: "rejected",
+			reason: resolution.error
+		};
+		return {
+			outcome: resolution.outcome ?? "rejected",
+			...resolution.reason !== void 0 && { reason: resolution.reason }
+		};
+	};
+}
+/**
+* Build the {@link CacheTransport} the sandbox-side cache engine uses to reach
+* the orchestrator. Each method sends a `cache.request` IPC (relayed by the
+* agent over the WS as a `cache.user.*` message) and awaits the matching
+* `cache.response`. Mirrors the `event.emit` / `agent.api.request` relays.
+*/
+function buildCacheTransport() {
+	return {
+		async restore(key, restoreKeys) {
+			const requestId = randomUUID();
+			sendMessage({
+				type: "cache.request",
+				requestId,
+				op: "restore",
+				key,
+				...restoreKeys && { restoreKeys }
+			});
+			const response = await waitForCacheResponse(requestId);
+			if (response.error) throw new Error(`Cache restore failed: ${response.error}`);
+			return {
+				hit: response.hit ?? false,
+				...response.matchedKey && { matchedKey: response.matchedKey },
+				...response.downloadUrl && { downloadUrl: response.downloadUrl },
+				...response.tarHash && { tarHash: response.tarHash }
+			};
+		},
+		async beginSave(key) {
+			const requestId = randomUUID();
+			sendMessage({
+				type: "cache.request",
+				requestId,
+				op: "beginSave",
+				key
+			});
+			const response = await waitForCacheResponse(requestId);
+			if (response.error) throw new Error(`Cache save failed: ${response.error}`);
+			return {
+				skip: response.skip ?? true,
+				...response.uploadUrl && { uploadUrl: response.uploadUrl }
+			};
+		},
+		async completeSave(key, tarHash, sizeBytes) {
+			const requestId = randomUUID();
+			sendMessage({
+				type: "cache.request",
+				requestId,
+				op: "completeSave",
+				key,
+				tarHash,
+				sizeBytes
+			});
+			const response = await waitForCacheResponse(requestId);
+			if (response.error) throw new Error(`Cache save-complete failed: ${response.error}`);
+		}
+	};
+}
+/**
+* Build the declarative-cache phase dependencies and run the job-level cache
+* restore (Phase 9b).
+*
+* The deps carry one job-scoped cache API (over the same IPC→WS transport
+* `ctx.cache` uses) plus a monotonic pseudo-step index allocator that starts
+* well above every real-step and hook index (hooks use up to `stepCount * 3`).
+* Cache restores/saves surface as `cache:restore` / `cache:save` pseudo-steps
+* allocated from this cursor. The returned `jobCacheRestore` map lets the
+* post-loop save phase skip exact-key hits.
+*/
+async function setupJobCache(stepCwd, stepCount, jobCache, sendIpc) {
+	let cacheStepCursor = stepCount * 3 + 100;
+	const cachePhaseDeps = {
+		cache: createCacheApi(stepCwd, buildCacheTransport()),
+		sendIpc,
+		nextStepIndex: () => cacheStepCursor++
+	};
+	const jobCacheSpecs = normalizeCacheSpecs(jobCache);
+	return {
+		cachePhaseDeps,
+		jobCacheSpecs,
+		jobCacheRestore: jobCacheSpecs.length > 0 ? await restoreCacheSpecs(jobCacheSpecs, cachePhaseDeps) : /* @__PURE__ */ new Map()
+	};
+}
+/**
+* Job-level cache save (Phase 9c). Runs after the step loop, only when every
+* step succeeded and the job was not aborted. Each spec whose exact key did NOT
+* already hit on restore is saved (immutable: a re-save of an existing exact
+* key is skipped by the save phase itself). A no-op when the job declared no
+* cache or did not fully succeed (a failed/aborted job's artifacts may be
+* partial).
+*/
+async function maybeSaveJobCache(specs, restoreResults, deps, succeeded) {
+	if (specs.length === 0 || !succeeded) return;
+	await saveCacheSpecs(specs, restoreResults, deps);
+}
+/**
 * Dispatch an agent-to-runner message to the appropriate pending handler.
 * Shared between fork mode (IPC channel) and stdio mode (stdin readline).
 */
@@ -2261,6 +3105,12 @@ function dispatchAgentMessage(msg) {
 		const pending = pendingApiResponses.get(msg.requestId);
 		if (pending) if (msg.error) pending.reject(new Error(msg.error));
 		else pending.resolve(msg.result);
+	} else if (msg.type === "cache.response") {
+		const pending = pendingCacheResponses.get(msg.requestId);
+		if (pending) pending.resolve(msg);
+	} else if (msg.type === "approval.resolved") {
+		const pending = pendingApprovalResolutions.get(msg.requestId);
+		if (pending) pending.resolve(msg);
 	}
 }
 if (isForkMode) process.on("message", (msg) => {
@@ -2390,16 +3240,29 @@ function createSecretMasker(request) {
 	return masker;
 }
 /**
-* Create a StepContext natively inside the workflow runner.
+* Build a fresh zx `$` shell bound to the sandbox working directory and the
+* sanitized environment (process.env was set by the parent via env-sanitizer
+* before spawning this process). This is the single shell-construction code
+* path shared by step execution (`createSandboxStepContext`) and the per-job
+* init phase (`runInitPhase`), so init commands run through the identical shell
+* steps use — same cwd, same env snapshot, same masked log streaming.
 *
-* 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.
+* Intercept zx subprocess output via the log callback: zx does NOT write child
+* stdout/stderr to process.stdout — it pipes to an internal VoidStream and only
+* calls $.log() with { kind: 'stdout'|'stderr' }. With verbose=false the default
+* log function skips stdout entirely, and with quiet=false it writes stderr to
+* process.stderr. We override the log function to capture both kinds directly
+* and send them as masked IPC log.line messages tagged with `stepIndex`.
+*
+* IMPORTANT: The log function must be passed in the zx$() config, not set on the
+* returned function. zx$() returns a plain function (not the proxy $), so setting
+* step$.log would only set it on the function object and NOT propagate to the
+* AsyncLocalStorage store that zx uses for ProcessPromise snapshots.
 */
-function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedSendFn, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, secrets) {
+function buildSandboxShell(cwd, stepIndex, maskedSendFn) {
 	let zxLineBuf = "";
-	const step$ = $({
-		cwd: workDir,
+	return $({
+		cwd,
 		env: { ...process.env },
 		verbose: false,
 		quiet: false,
@@ -2418,20 +3281,36 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 			}
 		})
 	});
+}
+/**
+* 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) {
+	const step$ = buildSandboxShell(workDir, stepIndex, maskedSendFn);
 	const log = createIpcLogger(stepIndex, stepName, maskedSendFn);
+	const rawPayload = rawPayloadFromEvent(request.event);
 	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;
+			applyEnvDelta({
+				env: { [key]: value },
+				pathPrepends: []
+			}, {
+				operatorSecretKeys,
+				onReject: (k) => log.warn(`Cannot override operator secret "${k}" via setEnv — value preserved`)
+			});
 		},
 		addPath: (dir) => {
-			process.env.PATH = dir + ":" + (process.env.PATH ?? "");
+			applyEnvDelta({
+				env: {},
+				pathPrepends: [dir]
+			}, { operatorSecretKeys });
 		},
 		inputs: {},
 		secrets,
@@ -2442,6 +3321,7 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 		},
 		isTestRun: request.isTestRun ?? false,
 		environment: request.environment,
+		cache: createCacheApi(workDir, buildCacheTransport()),
 		emit: async (eventName, payload, options) => {
 			const reqId = randomUUID();
 			sendMessage({
@@ -2474,10 +3354,15 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 			});
 			return waitForApiResponse(reqId);
 		}),
-		...request.event && { rawPayload: request.event },
+		...rawPayload && { rawPayload },
 		...request.provider && { provider: request.provider }
 	};
 }
+/** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
+function rawPayloadFromEvent(event) {
+	if (!event) return void 0;
+	return event.payload ?? void 0;
+}
 /**
 * Check if a file exists at the given path.
 */
@@ -2499,7 +3384,8 @@ function abortAndExit(reason) {
 	sendMessage({
 		type: "job.complete",
 		status: ExecutionJobStatus.enum.failed,
-		stepResults: []
+		stepResults: [],
+		...jobTimedOut && { error: `${TimeoutReason.enum.job_timeout}: job exceeded its timeout of ${jobTimedOutMs ?? 0}ms` }
 	});
 	process.exit(1);
 }
@@ -3094,6 +3980,121 @@ function collectJobHooks(job) {
 	return jobHooks;
 }
 /**
+* Normalize `Job.init` (config | config[] | false | undefined) to an ordered
+* array of init specs. `false` is an explicit opt-out and `undefined` (no
+* config) both resolve to an empty list — the init phase is then a no-op.
+*/
+function resolveInitSpecs(job) {
+	if (!job || job.init === void 0 || job.init === false) return [];
+	return Array.isArray(job.init) ? [...job.init] : [job.init];
+}
+/**
+* Base stepIndex for the `init:<n>` pseudo-steps. The step loop reserves the
+* range starting at `steps.length` for hook pseudo-steps (`beforeStep` =
+* `steps.length + i*2`, `afterStep` = `steps.length + i*2 + 1`, and job-level
+* onSuccess/onFailure/cleanup from `steps.length` upward — see step-loop.ts),
+* so init indices must sit ABOVE every possible hook index to avoid collision.
+* A large fixed offset reserves a dedicated range no realistic step/hook count
+* can reach; init:<n> then occupies `INIT_STEP_INDEX_BASE + n`.
+*/
+const INIT_STEP_INDEX_BASE = 1e6;
+/**
+* Read the KICI_ENV/KICI_PATH delta written by a command, apply it through
+* `applyEnvDelta` (operator-secret override guard + masked reject log), then
+* truncate the files for the next command. Shared by the per-job init phase and
+* the per-step after-hook so both honor the identical operator-secret guard.
+*/
+async function applyEnvFilesDelta(envFiles, operatorSecretKeys, maskedSend) {
+	applyEnvDelta(await readEnvDelta(envFiles), {
+		operatorSecretKeys,
+		onReject: (key) => maskedSend({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[kici] Cannot override operator secret "${key}" via $KICI_ENV — value preserved`
+		})
+	});
+	await truncateEnvFiles(envFiles);
+}
+/**
+* Build the step loop's KICI_ENV/KICI_PATH callbacks over the shared `envFiles`.
+* `beforeStepEnvFiles` points the runner's process.env at the files (each step's
+* zx $ snapshots process.env at context creation, which happens AFTER this
+* before-hook, so the shell sees them; the pre-fork env allowlist does not
+* re-filter runtime-set vars). `afterStepApplyEnvFiles` applies + truncates the
+* delta, mirroring the init phase's env port.
+*/
+function buildStepEnvFileHooks(envFiles, operatorSecretKeys, maskedSend) {
+	return {
+		beforeStepEnvFiles: async () => {
+			process.env.KICI_ENV = envFiles.envFile;
+			process.env.KICI_PATH = envFiles.pathFile;
+		},
+		afterStepApplyEnvFiles: async () => {
+			try {
+				await applyEnvFilesDelta(envFiles, operatorSecretKeys, maskedSend);
+			} catch (err) {
+				maskedSend({
+					type: "log.line",
+					stepIndex: -1,
+					line: `[kici] Failed to apply $KICI_ENV/$KICI_PATH delta: ${toErrorMessage(err)}`
+				});
+			}
+		}
+	};
+}
+/**
+* Run the per-job init phase with concrete ports, then fail the job (no steps)
+* if any init spec failed or timed out.
+*
+* Concrete ports supplied to `runInitPhase`:
+* - shell: a fresh `buildSandboxShell` per init (same zx config steps use), cwd
+*   = the clone root. Each init snapshots `process.env` (which `beginCapture`
+*   has pointed at the shared KICI_ENV/KICI_PATH files), so the command can hand
+*   env + PATH off to later inits and to every step.
+* - cache: the transport-backed `CacheApi` (`createCacheApi`) — the same engine
+*   `ctx.cache` and the declarative cache phase use. Restore before / save on
+*   key miss after.
+* - env: the P1 KICI_ENV/KICI_PATH lifecycle over the shared `envFiles`,
+*   mirroring the step loop's `beforeStepEnvFiles` / `afterStepApplyEnvFiles`
+*   (same `operatorSecretKeys` guard + masked reject log).
+*
+* On `result.ok === false`: emit `job.complete{failed}` with `stepResults: []`
+* (no step ran), an actionable error (carrying the distinct P3 timeout reason
+* when `timedOut`), and `process.exit(1)` — the step loop never executes.
+*/
+async function runInitPhaseOrFailJob(args) {
+	const { job, stepCwd, envFiles, operatorSecretKeys, maskedSend } = args;
+	const initSpecs = resolveInitSpecs(job);
+	if (initSpecs.length === 0) return;
+	const initResult = await runInitPhase({
+		specs: initSpecs,
+		shellFor: (_spec, i) => buildSandboxShell(stepCwd, INIT_STEP_INDEX_BASE + i, maskedSend),
+		sendIpc: maskedSend,
+		stepIndexBase: INIT_STEP_INDEX_BASE,
+		cache: createCacheApi(stepCwd, buildCacheTransport()),
+		env: {
+			beginCapture: async () => {
+				process.env.KICI_ENV = envFiles.envFile;
+				process.env.KICI_PATH = envFiles.pathFile;
+				await truncateEnvFiles(envFiles);
+			},
+			applyDelta: async () => {
+				await applyEnvFilesDelta(envFiles, operatorSecretKeys, maskedSend);
+			}
+		}
+	});
+	if (!initResult.ok) {
+		const errorBody = initResult.error ?? "";
+		sendMessage({
+			type: "job.complete",
+			status: ExecutionJobStatus.enum.failed,
+			stepResults: [],
+			error: initResult.reason ? `init[${initResult.failedInitIndex}] ${initResult.reason}: ${errorBody}`.trim() : `init[${initResult.failedInitIndex}] failed: ${errorBody}`.trim()
+		});
+		process.exit(1);
+	}
+}
+/**
 * Run the complete job execution lifecycle.
 *
 * 1. Receive execution request
@@ -3124,6 +4125,18 @@ async function main() {
 		});
 		else sendMessage(msg);
 	};
+	const jobDeadline = armJobDeadline(request.jobTimeoutMs, (reason, timeoutMs) => {
+		jobTimedOut = true;
+		jobTimedOutMs = timeoutMs;
+		aborted = true;
+		forceAborted = true;
+		maskedSend({
+			type: "log.line",
+			stepIndex: -1,
+			line: `[kici] Job exceeded its timeout of ${timeoutMs}ms (${reason}); aborting.`
+		});
+		jobDeadlineAbort.abort();
+	});
 	await cloneRepoIfRequested(request, workDir, workflowDir, sourceDir, isGlobal);
 	await applyOverlayIfRequested(request, workflowDir);
 	if (aborted) abortAndExit("aborted after clone");
@@ -3153,6 +4166,15 @@ async function main() {
 	flushOutputCapture();
 	capturePrepareActive = false;
 	const stepCwd = sourceDir;
+	const envFiles = await createEnvFiles(tmpdir());
+	await runInitPhaseOrFailJob({
+		job,
+		stepCwd,
+		envFiles,
+		operatorSecretKeys,
+		maskedSend
+	});
+	const { cachePhaseDeps, jobCacheSpecs, jobCacheRestore } = await setupJobCache(stepCwd, normalizedSteps.length, job?.cache, maskedSend);
 	let currentStepSecrets = null;
 	let currentStepDispose = null;
 	const createStepCtxWithCapture = (stepIndex, stepName) => {
@@ -3167,6 +4189,7 @@ async function main() {
 		}
 		return ctx;
 	};
+	const stepEnvHooks = buildStepEnvFileHooks(envFiles, operatorSecretKeys, maskedSend);
 	const jobStartTime = Date.now();
 	const loopResult = await executeStepLoop({
 		steps: normalizedSteps,
@@ -3177,7 +4200,9 @@ async function main() {
 		event: request.event ?? {},
 		env: process.env,
 		jobHooks,
+		cachePhaseDeps,
 		isAborted: () => aborted,
+		jobDeadlineSignal: jobDeadlineAbort.signal,
 		startTime: jobStartTime,
 		getSecretsAccessLog: () => {
 			flushOutputCapture();
@@ -3192,8 +4217,13 @@ async function main() {
 			currentStepDispose = null;
 			currentStepSecrets = null;
 			if (disposeFn) await disposeFn();
-		}
+		},
+		beforeStepEnvFiles: stepEnvHooks.beforeStepEnvFiles,
+		afterStepApplyEnvFiles: stepEnvHooks.afterStepApplyEnvFiles,
+		awaitStepApproval: buildAwaitStepApproval()
 	});
+	jobDeadline.clear();
+	await maybeSaveJobCache(jobCacheSpecs, jobCacheRestore, cachePhaseDeps, !aborted && loopResult.status === ExecutionStepStatus.enum.success);
 	let finalStatus = loopResult.status === ExecutionStepStatus.enum.success ? ExecutionJobStatus.enum.success : ExecutionJobStatus.enum.failed;
 	let cancelFailureReason;
 	if (aborted) {
@@ -3216,19 +4246,40 @@ async function main() {
 		finalStatus = cancelResult.finalStatus;
 		cancelFailureReason = cancelResult.cancelFailureReason;
 	}
+	if (jobTimedOut) finalStatus = ExecutionJobStatus.enum.failed;
+	emitJobComplete({
+		finalStatus,
+		loopResult,
+		outputsMap,
+		secretOutputs,
+		jobTimedOut,
+		jobTimeoutMs: request.jobTimeoutMs,
+		cancelFailureReason,
+		driftDroppedJobs
+	});
+	process.exit(finalStatus === ExecutionJobStatus.enum.success ? 0 : 1);
+}
+/**
+* Phase 11 — emit the terminal `job.complete` IPC. Aggregates per-step outputs
+* by step name, includes encrypted secret outputs, and selects the error
+* message: a `job_timeout` reason when the job-level deadline tripped, else the
+* step-loop's failure reason (or the cancel-path's compound reason).
+*/
+function emitJobComplete(args) {
 	const aggregatedOutputs = {};
-	for (const [stepName, outputs] of outputsMap) aggregatedOutputs[stepName] = outputs;
+	for (const [stepName, outputs] of args.outputsMap) aggregatedOutputs[stepName] = outputs;
 	sendMessage({
 		type: "job.complete",
-		status: finalStatus,
-		stepResults: loopResult.stepResults,
+		status: args.finalStatus,
+		stepResults: args.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 }
+		...args.secretOutputs.size > 0 && { secretOutputs: Object.fromEntries(args.secretOutputs) },
+		...args.jobTimedOut ? { error: `${TimeoutReason.enum.job_timeout}: job exceeded its timeout of ${args.jobTimeoutMs}ms` } : {
+			...args.loopResult.failureReason && { error: args.loopResult.failureReason },
+			...args.cancelFailureReason && { error: args.cancelFailureReason }
+		},
+		...args.driftDroppedJobs.length > 0 && { droppedJobs: args.driftDroppedJobs }
 	});
-	process.exit(finalStatus === ExecutionJobStatus.enum.success ? 0 : 1);
 }
 /**
 * Find a static Job by name in the workflow.
@@ -3255,6 +4306,6 @@ main().catch((error) => {
 	setTimeout(() => process.exit(1), 100);
 });
 //#endregion
-export {};
+export { rawPayloadFromEvent, resolveInitSpecs };
 
 //# sourceMappingURL=workflow-runner.js.map