@kici-dev/agent 0.1.14 → 0.1.15

package/dist/server.js

@@ -8,16 +8,17 @@ import { PassThrough, Readable, Transform, Writable } from "node:stream";
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import winston from "winston";
-import { RingBuffer, createHealthRoutes, createLogger, createMeter, createMetricsRoutes, deriveSharedSecret, getPrometheusExporter, getReconnectDelay, getRequestContext, guardStartup, initTelemetry, normalizeLineEndings, requestContext, setServiceName, setupGracefulShutdown, sha256, sha256File, toErrorMessage, validateRequiredTools } from "@kici-dev/shared";
+import { RingBuffer, createHealthRoutes, createLogger, createMeter, createMetricsRoutes, deriveSharedSecret, getPrometheusExporter, getReconnectDelay, getRequestContext, guardStartup, initTelemetry, logger, normalizeLineEndings, requestContext, setServiceName, setupGracefulShutdown, sha256, sha256File, toErrorMessage, validateRequiredTools } from "@kici-dev/shared";
 import { z } from "zod";
 import { LOGGER_ENV_VARS, defineEnv, validateUnknownKiciVars } from "@kici-dev/shared/env";
-import { ALLOWED_SYSTEM_VARS, ExecutionJobStatus, ExecutionStepStatus, KNOWN_ROLES, PROTOCOL_VERSION, SANDBOX_DEFAULT_VARS, WS_CLOSE_AGENT_AUTH_FAILED, WS_MAX_PAYLOAD_BYTES, deriveOsArchLabels, heartbeatSchema, hostLabel, mergeAutoLabels, orchestratorToAgentMessageSchema, resolveRoleLabels, validateNoReservedLabels } from "@kici-dev/engine";
+import { ALLOWED_SYSTEM_VARS, CacheRunEventType, CacheStepType, ExecutionJobStatus, ExecutionStepStatus, InitFailureCategory, KNOWN_ROLES, PROTOCOL_VERSION, SANDBOX_DEFAULT_VARS, WS_CLOSE_AGENT_AUTH_FAILED, WS_MAX_PAYLOAD_BYTES, deriveOsArchLabels, heartbeatSchema, hostLabel, mergeAutoLabels, orchestratorToAgentMessageSchema, resolveRoleLabels, validateNoReservedLabels } from "@kici-dev/engine";
 import { execFile, execFileSync, execSync, fork, spawn } from "node:child_process";
 import WebSocket from "ws";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { format, promisify } from "node:util";
 import { existsSync } from "node:fs";
 import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { gcStaleTmpDirs } from "@kici-dev/core/tmp-gc";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import fs, { access, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, unlink, writeFile } from "node:fs/promises";
 import Docker from "dockerode";
@@ -207,7 +208,7 @@ var LogBuffer = class extends RingBuffer {
 };
 //#endregion
 //#region src/ws/orchestrator-client.ts
-const logger$10 = createLogger({ prefix: "orchestrator-client" });
+const logger$11 = createLogger({ prefix: "orchestrator-client" });
 /**
 * WebSocket client that connects the agent to the customer orchestrator.
 *
@@ -240,6 +241,8 @@ var OrchestratorClient = class OrchestratorClient {
 	pendingEventEmitRequests = /* @__PURE__ */ new Map();
 	/** Pending agent.api.request calls awaiting orchestrator response. */
 	pendingApiRequests = /* @__PURE__ */ new Map();
+	/** Pending user-cache restore/save requests awaiting orchestrator response. */
+	pendingUserCacheRequests = /* @__PURE__ */ new Map();
 	/** Pending concurrency report requests awaiting orchestrator ack. */
 	pendingConcurrencyRequests = /* @__PURE__ */ new Map();
 	url;
@@ -311,7 +314,7 @@ var OrchestratorClient = class OrchestratorClient {
 	*/
 	connect() {
 		if (this._state !== "disconnected") {
-			logger$10.warn("connect() called while not disconnected", { state: this._state });
+			logger$11.warn("connect() called while not disconnected", { state: this._state });
 			return;
 		}
 		this.intentionalDisconnect = false;
@@ -481,6 +484,69 @@ var OrchestratorClient = class OrchestratorClient {
 		});
 	}
 	/**
+	* Relay a user-facing cache request from the sandbox to the orchestrator.
+	*
+	* Translates the sandbox `cache.request` IPC into the matching `cache.user.*`
+	* WS message and resolves with the orchestrator's response mapped onto the
+	* IPC response shape:
+	*
+	* - `restore` -> `cache.user.restore.request`, awaits `cache.user.restore.response`.
+	* - `beginSave` -> `cache.user.save.request`, awaits `cache.user.save.response`.
+	* - `completeSave` -> `cache.user.save.complete` (fire-and-forget; the
+	*   orchestrator commits temp -> final without replying), resolves immediately.
+	*
+	* Times out after 30 seconds for the round-trip ops.
+	*/
+	async requestUserCache(jobId, request) {
+		if (request.op === "completeSave") {
+			this.sendDirect({
+				type: "cache.user.save.complete",
+				messageId: randomUUID(),
+				jobId,
+				key: request.key,
+				tarHash: request.tarHash,
+				sizeBytes: request.sizeBytes
+			});
+			return {
+				type: "cache.response",
+				requestId: request.requestId
+			};
+		}
+		const messageId = randomUUID();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pendingUserCacheRequests.delete(messageId);
+				reject(/* @__PURE__ */ new Error("User-cache request timed out (30s)"));
+			}, 3e4);
+			this.pendingUserCacheRequests.set(messageId, {
+				resolve: (response) => {
+					clearTimeout(timer);
+					resolve({
+						...response,
+						requestId: request.requestId
+					});
+				},
+				reject: (err) => {
+					clearTimeout(timer);
+					reject(err);
+				}
+			});
+			if (request.op === "restore") this.sendDirect({
+				type: "cache.user.restore.request",
+				messageId,
+				jobId,
+				key: request.key,
+				...request.restoreKeys && { restoreKeys: request.restoreKeys }
+			});
+			else this.sendDirect({
+				type: "cache.user.save.request",
+				messageId,
+				jobId,
+				key: request.key
+			});
+		});
+	}
+	/**
 	* Send a job.context message to the orchestrator.
 	*
 	* Conveys execution environment details (runtime, sandbox type, env vars)
@@ -562,7 +628,7 @@ var OrchestratorClient = class OrchestratorClient {
 				}
 			});
 		} catch (err) {
-			logger$10.error("Failed to create WebSocket", { error: toErrorMessage(err) });
+			logger$11.error("Failed to create WebSocket", { error: toErrorMessage(err) });
 			this._state = "disconnected";
 			this.scheduleReconnect();
 			return;
@@ -570,7 +636,7 @@ var OrchestratorClient = class OrchestratorClient {
 		this.ws.on("open", () => {
 			if (this.token) {
 				this._state = "authenticating";
-				logger$10.info("Connected to orchestrator, sending auth.request", {
+				logger$11.info("Connected to orchestrator, sending auth.request", {
 					url: this.url,
 					agentId: this.agentId
 				});
@@ -581,7 +647,7 @@ var OrchestratorClient = class OrchestratorClient {
 				}));
 			} else {
 				this._state = "registering";
-				logger$10.info("Connected to orchestrator, sending agent.register (no token)", {
+				logger$11.info("Connected to orchestrator, sending agent.register (no token)", {
 					url: this.url,
 					agentId: this.agentId
 				});
@@ -592,12 +658,12 @@ var OrchestratorClient = class OrchestratorClient {
 			this.handleMessage(data);
 		});
 		this.ws.on("close", (code, reason) => {
-			logger$10.info("Orchestrator connection closed", {
+			logger$11.info("Orchestrator connection closed", {
 				code,
 				reason: reason.toString()
 			});
 			if (code === WS_CLOSE_AGENT_AUTH_FAILED) {
-				logger$10.error("Orchestrator closed with auth-failed code -- token is invalid or revoked. NOT retrying.", {
+				logger$11.error("Orchestrator closed with auth-failed code -- token is invalid or revoked. NOT retrying.", {
 					code,
 					reason: reason.toString()
 				});
@@ -614,12 +680,14 @@ var OrchestratorClient = class OrchestratorClient {
 			this.pendingEventEmitRequests.clear();
 			for (const [_id, pending] of this.pendingApiRequests) pending.reject(/* @__PURE__ */ new Error("WebSocket disconnected"));
 			this.pendingApiRequests.clear();
+			for (const [_id, pending] of this.pendingUserCacheRequests) pending.reject(/* @__PURE__ */ new Error("WebSocket disconnected"));
+			this.pendingUserCacheRequests.clear();
 			for (const [_id, pending] of this.pendingConcurrencyRequests) pending.reject(/* @__PURE__ */ new Error("WebSocket disconnected"));
 			this.pendingConcurrencyRequests.clear();
 			if (!this.intentionalDisconnect) this.scheduleReconnect();
 		});
 		this.ws.on("error", (err) => {
-			logger$10.error(`Orchestrator WebSocket error: ${err.message}`);
+			logger$11.error(`Orchestrator WebSocket error: ${err.message}`);
 			if (this.ws && this.ws.readyState === WebSocket.OPEN) this.ws.close();
 		});
 	}
@@ -628,7 +696,7 @@ var OrchestratorClient = class OrchestratorClient {
 		try {
 			raw = JSON.parse(data.toString());
 		} catch {
-			logger$10.warn("Malformed JSON received from orchestrator");
+			logger$11.warn("Malformed JSON received from orchestrator");
 			return;
 		}
 		const rawMsg = raw;
@@ -662,19 +730,37 @@ var OrchestratorClient = class OrchestratorClient {
 			}
 			return;
 		}
+		if (rawMsg.type === "cache.user.restore.response" || rawMsg.type === "cache.user.save.response") {
+			const cacheMsg = raw;
+			const pending = this.pendingUserCacheRequests.get(cacheMsg.requestId);
+			if (pending) {
+				this.pendingUserCacheRequests.delete(cacheMsg.requestId);
+				pending.resolve({
+					type: "cache.response",
+					requestId: cacheMsg.requestId,
+					...cacheMsg.hit !== void 0 && { hit: cacheMsg.hit },
+					...cacheMsg.matchedKey && { matchedKey: cacheMsg.matchedKey },
+					...cacheMsg.downloadUrl && { downloadUrl: cacheMsg.downloadUrl },
+					...cacheMsg.tarHash && { tarHash: cacheMsg.tarHash },
+					...cacheMsg.skip !== void 0 && { skip: cacheMsg.skip },
+					...cacheMsg.uploadUrl && { uploadUrl: cacheMsg.uploadUrl }
+				});
+			}
+			return;
+		}
 		const parsed = orchestratorToAgentMessageSchema.safeParse(raw);
 		if (parsed.success) {
 			const msg = parsed.data;
 			switch (msg.type) {
 				case "auth.success":
 					if (this._state === "authenticating") {
-						logger$10.info("Authentication successful, sending agent.register", { connectionId: msg.connectionId });
+						logger$11.info("Authentication successful, sending agent.register", { connectionId: msg.connectionId });
 						this._state = "registering";
 						this.sendAgentRegister();
 					}
 					break;
 				case "auth.failure":
-					logger$10.error("Authentication FAILED -- token is invalid or expired. NOT retrying.", { reason: msg.reason });
+					logger$11.error("Authentication FAILED -- token is invalid or expired. NOT retrying.", { reason: msg.reason });
 					this.authFailed = true;
 					this.intentionalDisconnect = true;
 					if (this.ws) {
@@ -684,7 +770,7 @@ var OrchestratorClient = class OrchestratorClient {
 					this._state = "disconnected";
 					break;
 				case "register.ack":
-					logger$10.info("Registration acknowledged by orchestrator", {
+					logger$11.info("Registration acknowledged by orchestrator", {
 						agentId: msg.agentId,
 						labels: msg.labels,
 						scalerManaged: msg.scalerManaged,
@@ -699,14 +785,14 @@ var OrchestratorClient = class OrchestratorClient {
 					this.sendConfigAck(msg.agentId);
 					break;
 				case "job.dispatch":
-					logger$10.info("Job dispatch received", {
+					logger$11.info("Job dispatch received", {
 						runId: msg.runId,
 						jobId: msg.jobId
 					});
 					this.onJobDispatch(msg);
 					break;
 				case "job.cancel":
-					logger$10.info("Job cancel received", {
+					logger$11.info("Job cancel received", {
 						runId: msg.runId,
 						jobId: msg.jobId,
 						reason: msg.reason
@@ -714,7 +800,7 @@ var OrchestratorClient = class OrchestratorClient {
 					this.onJobCancel(msg);
 					break;
 				case "job.concurrency.ack": {
-					logger$10.info("Concurrency ack received", {
+					logger$11.info("Concurrency ack received", {
 						requestId: msg.requestId,
 						action: msg.action
 					});
@@ -732,7 +818,7 @@ var OrchestratorClient = class OrchestratorClient {
 			return;
 		}
 		if (heartbeatSchema.safeParse(raw).success) return;
-		logger$10.warn("Invalid message from orchestrator", { errors: parsed.error.issues });
+		logger$11.warn("Invalid message from orchestrator", { errors: parsed.error.issues });
 	}
 	flushBuffer() {
 		const events = this.eventBuffer.flush();
@@ -746,11 +832,11 @@ var OrchestratorClient = class OrchestratorClient {
 		}
 		this.disconnectedAt = null;
 		if (events.length > 0) {
-			logger$10.info("Flushing event buffer", { count: events.length });
+			logger$11.info("Flushing event buffer", { count: events.length });
 			for (const msg of events) this.sendDirect(msg);
 		}
 		if (logLines.length > 0) {
-			logger$10.info("Flushing log buffer", { count: logLines.length });
+			logger$11.info("Flushing log buffer", { count: logLines.length });
 			for (let i = 0; i < logLines.length; i += OrchestratorClient.LOG_BATCH_SIZE) {
 				const batch = logLines.slice(i, i + OrchestratorClient.LOG_BATCH_SIZE);
 				this.sendAgentLogMessage(batch);
@@ -803,14 +889,14 @@ var OrchestratorClient = class OrchestratorClient {
 	*/
 	blockMmdsAccess() {
 		if (process.getuid?.() !== 0) {
-			logger$10.info("MMDS iptables block skipped (non-root) — network isolation handled by orchestrator");
+			logger$11.info("MMDS iptables block skipped (non-root) — network isolation handled by orchestrator");
 			return;
 		}
 		try {
 			execSync("iptables -A OUTPUT -d 169.254.169.254 -j DROP", { timeout: 5e3 });
-			logger$10.info("MMDS access blocked via iptables");
+			logger$11.info("MMDS access blocked via iptables");
 		} catch (err) {
-			logger$10.warn("Failed to block MMDS access via iptables", { error: toErrorMessage(err) });
+			logger$11.warn("Failed to block MMDS access via iptables", { error: toErrorMessage(err) });
 		}
 	}
 	/**
@@ -824,7 +910,7 @@ var OrchestratorClient = class OrchestratorClient {
 				messageId: `config-ack-${agentId}-${Date.now()}`,
 				agentId
 			}));
-			logger$10.info("Config ACK sent to orchestrator", { agentId });
+			logger$11.info("Config ACK sent to orchestrator", { agentId });
 		}
 	}
 	startHeartbeat() {
@@ -885,12 +971,12 @@ var OrchestratorClient = class OrchestratorClient {
 	scheduleReconnect() {
 		this.cancelReconnect();
 		if (this.authFailed) {
-			logger$10.error("Not reconnecting: authentication permanently failed");
+			logger$11.error("Not reconnecting: authentication permanently failed");
 			return;
 		}
 		const delay = this.getReconnectDelay();
 		this.reconnectAttempts++;
-		logger$10.info("Scheduling reconnect", {
+		logger$11.info("Scheduling reconnect", {
 			attempt: this.reconnectAttempts,
 			delayMs: Math.round(delay)
 		});
@@ -975,14 +1061,14 @@ var init_console_capture = __esmMin((() => {
 init_console_capture();
 function safe(name, fallback = "unknown") {
 	switch (name) {
-		case "version": return "0.1.14";
-		case "buildCommit": return "0fc7a43c9";
-		case "sdkVersion": return "0.1.14";
-		case "sdkBundleHash": return "675aafe4de03e677785ef2794d8f34951b14e2bd1e6f0ea825953d6c2abfe128";
-		case "sharedVersion": return "0.1.14";
-		case "sharedBundleHash": return "5a44862f00d382dbac676c0bdbf9e3fb3016d1c4667b60ea4ae6cbf8ac8deaf4";
-		case "engineVersion": return "0.1.14";
-		case "engineBundleHash": return "8eef210908744b12e19a2b915520298c5dde5abd4a064fa75e87123e237bf932";
+		case "version": return "0.1.15";
+		case "buildCommit": return "831f6a763";
+		case "sdkVersion": return "0.1.15";
+		case "sdkBundleHash": return "cee24b67bbb4a1d2a770e4063dd37a9af33409faeb5ce32f936703b4431316dd";
+		case "sharedVersion": return "0.1.15";
+		case "sharedBundleHash": return "e82a8b68a7d72698674352158c5de4c0d10824c61bfa7166cc8f846044b8b5e4";
+		case "engineVersion": return "0.1.15";
+		case "engineBundleHash": return "032d6b28b3d32bcbea80ba80a52934b017ee2c86a97fcaf8fe8db0d86d72a7f7";
 		default: return fallback;
 	}
 }
@@ -1203,6 +1289,42 @@ function verifyNpmAvailable() {
 }
 var init_npm_resolver = __esmMin((() => {}));
 //#endregion
+//#region src/execution/tmp-gc.ts
+init_npm_resolver();
+/**
+* Startup garbage collection for this agent's own temp-directory families.
+*
+* Job workdirs (`kici-<6 random chars>`, see job-runner.ts) and isolated
+* pnpm stores (`kici-pnpm-store-*`, see dep-installer.ts) clean themselves
+* up in `finally` blocks — but a hard process death (SIGKILL, OOM kill)
+* skips those, and on a long-lived bare-metal agent the leftovers then
+* accumulate forever. Collecting anything older than a day at startup is
+* safe on shared hosts: no job lives remotely that long (job timeouts are
+* minutes), so a concurrent agent's in-flight dirs are never eligible.
+*/
+const AGENT_TMP_GC_MAX_AGE_MS = 1440 * 60 * 1e3;
+/** mkdtemp's 6-char suffix on the bare `kici-` prefix — job workdirs only. */
+const AGENT_WORKDIR_PATTERN = /^kici-[A-Za-z0-9]{6}$/;
+const PNPM_STORE_PATTERN = /^kici-pnpm-store-/;
+/**
+* Collect this agent's stale temp dirs. `base` is overridable for tests;
+* production callers use the default temp root. Never throws.
+*/
+async function gcStaleAgentTmpDirs(base = tmpdir()) {
+	const log = (m) => logger.info(m);
+	return [...await gcStaleTmpDirs({
+		base,
+		pattern: AGENT_WORKDIR_PATTERN,
+		maxAgeMs: AGENT_TMP_GC_MAX_AGE_MS,
+		log
+	}), ...await gcStaleTmpDirs({
+		base,
+		pattern: PNPM_STORE_PATTERN,
+		maxAgeMs: AGENT_TMP_GC_MAX_AGE_MS,
+		log
+	})];
+}
+//#endregion
 //#region src/metrics/prometheus.ts
 var prometheus_exports = /* @__PURE__ */ __exportAll({
 	cloneDurationSeconds: () => cloneDurationSeconds,
@@ -1630,8 +1752,8 @@ async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event
 }
 var AGENT_SDK_VERSION, AGENT_SDK_BUNDLE_HASH, hookRegistered;
 var init_workflow_loader = __esmMin((() => {
-	AGENT_SDK_VERSION = "0.1.14";
-	AGENT_SDK_BUNDLE_HASH = "675aafe4de03e677785ef2794d8f34951b14e2bd1e6f0ea825953d6c2abfe128";
+	AGENT_SDK_VERSION = "0.1.15";
+	AGENT_SDK_BUNDLE_HASH = "cee24b67bbb4a1d2a770e4063dd37a9af33409faeb5ce32f936703b4431316dd";
 	hookRegistered = false;
 }));
 //#endregion
@@ -1652,7 +1774,7 @@ var init_workflow_loader = __esmMin((() => {
 async function packKiciSource(workDir) {
 	const kiciDir = join(workDir, ".kici");
 	if (!existsSync(kiciDir)) throw new Error(`.kici/ not found at ${kiciDir}`);
-	logger$9.info("Packing .kici/ source tarball", { dir: workDir });
+	logger$10.info("Packing .kici/ source tarball", { dir: workDir });
 	const startTime = Date.now();
 	const stream = c({
 		gzip: true,
@@ -1666,7 +1788,7 @@ async function packKiciSource(workDir) {
 	const hash = sha256(tarball);
 	const sizeKB = (tarball.length / 1024).toFixed(2);
 	const durationMs = Date.now() - startTime;
-	logger$9.info(".kici/ source packed", {
+	logger$10.info(".kici/ source packed", {
 		sizeKB,
 		hash: hash.slice(0, 12),
 		durationMs
@@ -1676,9 +1798,9 @@ async function packKiciSource(workDir) {
 		hash
 	};
 }
-var logger$9;
+var logger$10;
 var init_source_packer = __esmMin((() => {
-	logger$9 = createLogger({ prefix: "source-packer" });
+	logger$10 = createLogger({ prefix: "source-packer" });
 }));
 //#endregion
 //#region src/execution/dep-restore.ts
@@ -1819,7 +1941,7 @@ async function cleanupScratch(scratchDir) {
 			force: true
 		});
 	} catch (cleanupErr) {
-		logger$8.warn("Scratch dir cleanup failed (orphan left behind)", {
+		logger$9.warn("Scratch dir cleanup failed (orphan left behind)", {
 			scratchDir,
 			error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
 		});
@@ -1844,7 +1966,7 @@ async function cleanupScratch(scratchDir) {
 */
 async function restoreDeps(workDir, depsUrl, depsHash) {
 	depsUrl = resolveOrchestratorUrl(depsUrl);
-	logger$8.info("Downloading dependency tarball", { url: depsUrl });
+	logger$9.info("Downloading dependency tarball", { url: depsUrl });
 	const kiciDir = join(workDir, ".kici");
 	if (depsUrl.startsWith("file://")) {
 		const localPath = fileURLToPath(depsUrl);
@@ -1858,7 +1980,7 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 		await moveScratchIntoRepo(scratchDir, workDir);
 		await cleanupScratch(scratchDir);
 		const sizeMB = (data.length / (1024 * 1024)).toFixed(2);
-		logger$8.info("Dependencies restored from cache (file)", {
+		logger$9.info("Dependencies restored from cache (file)", {
 			sizeMB,
 			targetDir: workDir
 		});
@@ -1867,7 +1989,7 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 	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$8.warn("Retrying dep tarball download", {
+		if (attempt > 0) logger$9.warn("Retrying dep tarball download", {
 			attempt,
 			url: depsUrl
 		});
@@ -1876,11 +1998,11 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 			if (depsHash && hash !== depsHash) throw new Error(`Dep tarball hash mismatch: expected ${depsHash}, got ${hash}`);
 			await moveScratchIntoRepo(scratchDir, workDir);
 			await cleanupScratch(scratchDir);
-			logger$8.info("Dependencies restored from cache (stream)", { targetDir: workDir });
+			logger$9.info("Dependencies restored from cache (stream)", { targetDir: workDir });
 			return;
 		} catch (err) {
 			lastError = err instanceof Error ? err : new Error(String(err));
-			logger$8.warn("Dep tarball download failed", {
+			logger$9.warn("Dep tarball download failed", {
 				attempt,
 				error: lastError.message
 			});
@@ -1888,9 +2010,9 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 	}
 	throw new Error(`Dep tarball download failed after 3 attempts: ${lastError?.message}`);
 }
-var logger$8, DOWNLOAD_TIMEOUT_MS$1, SCRATCH_DIR_BASENAME_PREFIX;
+var logger$9, DOWNLOAD_TIMEOUT_MS$1, SCRATCH_DIR_BASENAME_PREFIX;
 var init_dep_restore = __esmMin((() => {
-	logger$8 = createLogger({ prefix: "dep-restore" });
+	logger$9 = createLogger({ prefix: "dep-restore" });
 	DOWNLOAD_TIMEOUT_MS$1 = 300 * 1e3;
 	SCRATCH_DIR_BASENAME_PREFIX = ".dep-restore-scratch-";
 	`${SCRATCH_DIR_BASENAME_PREFIX}`;
@@ -2002,7 +2124,7 @@ async function extractSourceTarball(data, targetDir) {
 }
 async function restoreSource(workDir, sourceTarUrl) {
 	sourceTarUrl = resolveOrchestratorUrl(sourceTarUrl);
-	logger$7.info("Restoring .kici/ source from tarball", { sourceTarUrl });
+	logger$8.info("Restoring .kici/ source from tarball", { sourceTarUrl });
 	const startTime = Date.now();
 	let data;
 	if (sourceTarUrl.startsWith("file://")) {
@@ -2012,16 +2134,16 @@ async function restoreSource(workDir, sourceTarUrl) {
 	else throw new Error(`Unsupported source tarball URL scheme: ${sourceTarUrl}`);
 	await extractSourceTarball(data, workDir);
 	const durationMs = Date.now() - startTime;
-	logger$7.info(".kici/ source restored", {
+	logger$8.info(".kici/ source restored", {
 		sizeKB: (data.length / 1024).toFixed(2),
 		durationMs
 	});
 }
-var logger$7;
+var logger$8;
 var init_source_restore = __esmMin((() => {
 	init_download();
 	init_dep_restore();
-	logger$7 = createLogger({ prefix: "source-restore" });
+	logger$8 = createLogger({ prefix: "source-restore" });
 }));
 //#endregion
 //#region src/execution/timeout-util.ts
@@ -2069,7 +2191,7 @@ function findJobByName(workflow, jobName) {
 *
 * @param workflow - The extracted Workflow object
 * @param jobName - Name of the job whose dynamic fields to evaluate
-* @param event - Normalized webhook event data, passed as argument to dynamic functions
+* @param event - Normalized event envelope — same shape every dynamic-function call site receives.
 * @param flags - Which fields are dynamic and need evaluation
 * @param timeoutMs - Timeout per dynamic function call (default 60_000ms)
 */
@@ -2258,7 +2380,12 @@ async function serializeMatrix(matrix, jobName, runsOn, ctx) {
 		log: ctx.log,
 		env: ctx.env
 	};
-	const values = await withTimeout(() => matrix(matrixCtx), DYNAMIC_FIELD_TIMEOUT_MS, `dynamic matrix for generated job '${jobName}'`);
+	let values;
+	try {
+		values = await withTimeout(() => matrix(matrixCtx), DYNAMIC_FIELD_TIMEOUT_MS, `dynamic matrix for generated job '${jobName}'`);
+	} catch (err) {
+		throw new MatrixExpansionError(jobName, `Matrix expansion failed for job '${jobName}': ${err.message}`);
+	}
 	if (Array.isArray(values)) return {
 		_type: "static",
 		values
@@ -2267,11 +2394,19 @@ async function serializeMatrix(matrix, jobName, runsOn, ctx) {
 		_type: "static",
 		values
 	};
-	throw new Error(`Job '${jobName}': dynamic matrix function returned an unsupported value (expected array or object, got ${typeof values})`);
+	throw new MatrixExpansionError(jobName, `Job '${jobName}': dynamic matrix function returned an unsupported value (expected array or object, got ${typeof values})`);
 }
-var DYNAMIC_FIELD_TIMEOUT_MS;
+var MatrixExpansionError, DYNAMIC_FIELD_TIMEOUT_MS;
 var init_dynamic_job_serializer = __esmMin((() => {
 	init_timeout_util();
+	MatrixExpansionError = class MatrixExpansionError extends Error {
+		name = "MatrixExpansionError";
+		constructor(jobName, message) {
+			super(message);
+			this.jobName = jobName;
+			Object.setPrototypeOf(this, MatrixExpansionError.prototype);
+		}
+	};
 	DYNAMIC_FIELD_TIMEOUT_MS = 6e4;
 })), DEFAULT_MAX_LOG_SIZE_BYTES, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_FLUSH_LINE_THRESHOLD, PAUSE_SAFETY_TIMEOUT_MS, LogStreamer;
 var init_log_streamer = __esmMin((() => {
@@ -2540,7 +2675,7 @@ async function applyOverlay(config) {
 	const { tarballUrl, cliPublicKey, orchestratorPrivateKey, repoDir } = config;
 	const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "kici-overlay-"));
 	try {
-		logger$6.info("Downloading overlay tarball", { url: tarballUrl.replace(/\?.*$/, "?[redacted]") });
+		logger$7.info("Downloading overlay tarball", { url: tarballUrl.replace(/\?.*$/, "?[redacted]") });
 		let encryptedData;
 		try {
 			encryptedData = await downloadUrl(tarballUrl);
@@ -2550,7 +2685,7 @@ async function applyOverlay(config) {
 		const cliPubKeyBuf = Buffer.from(cliPublicKey, "base64");
 		const aesKey = deriveSharedSecret(Buffer.from(orchestratorPrivateKey, "base64"), cliPubKeyBuf);
 		const decryptedData = decryptBuffer(encryptedData, aesKey);
-		logger$6.info("Extracting overlay tarball", { size: decryptedData.length });
+		logger$7.info("Extracting overlay tarball", { size: decryptedData.length });
 		const extractDir = path.join(tmpDir, "extracted");
 		await fs.mkdir(extractDir, { recursive: true });
 		try {
@@ -2599,10 +2734,10 @@ async function applyOverlay(config) {
 				await fs.unlink(targetPath);
 				filesDeleted++;
 			} catch {
-				logger$6.debug("Deletion target not found, skipping", { file });
+				logger$7.debug("Deletion target not found, skipping", { file });
 			}
 		}
-		logger$6.info("Overlay applied successfully", {
+		logger$7.info("Overlay applied successfully", {
 			filesApplied,
 			filesDeleted
 		});
@@ -2618,10 +2753,10 @@ async function applyOverlay(config) {
 		}).catch(() => {});
 	}
 }
-var logger$6, IV_LENGTH$1, AUTH_TAG_LENGTH;
+var logger$7, IV_LENGTH$1, AUTH_TAG_LENGTH;
 var init_overlay_applier = __esmMin((() => {
 	init_download();
-	logger$6 = createLogger({ prefix: "overlay-applier" });
+	logger$7 = createLogger({ prefix: "overlay-applier" });
 	IV_LENGTH$1 = 12;
 	AUTH_TAG_LENGTH = 16;
 }));
@@ -2935,7 +3070,7 @@ async function detectKiciPackageManager(repoRoot, kiciDir) {
 async function installDeps(kiciDir, opts = {}) {
 	const repoRoot = opts.repoRoot ?? dirname(kiciDir);
 	const packageManager = await detectKiciPackageManager(repoRoot, kiciDir);
-	logger$5.info("Installing deps inline", {
+	logger$6.info("Installing deps inline", {
 		packageManager,
 		dir: kiciDir
 	});
@@ -2976,7 +3111,7 @@ async function installDeps(kiciDir, opts = {}) {
 	if (packageManager === PackageManager.Pnpm && await kiciHasLocalProtocolDeps(kiciDir)) await buildWorkspaceClosure(repoRoot);
 	const durationMs = Date.now() - startTime;
 	process.stderr.write(`[dep-installer:trace] install complete: ${durationMs}ms\n`);
-	logger$5.info("Deps installed inline", {
+	logger$6.info("Deps installed inline", {
 		packageManager,
 		durationMs
 	});
@@ -3114,12 +3249,11 @@ function logSubprocessStreams(e, tokens) {
 	if (e && typeof e === "object" && "stdout" in e) process.stderr.write(`[dep-installer:trace] stdout: ${redactNpmOutput(String(e.stdout), tokens).slice(0, 500)}\n`);
 	if (e && typeof e === "object" && "stderr" in e) process.stderr.write(`[dep-installer:trace] stderr: ${redactNpmOutput(String(e.stderr), tokens).slice(0, 500)}\n`);
 }
-var logger$5, execFileAsync, INSTALL_TIMEOUT_MS, INSTALL_MAX_BUFFER;
+var logger$6, execFileAsync, INSTALL_TIMEOUT_MS, INSTALL_MAX_BUFFER;
 var init_dep_installer = __esmMin((() => {
-	init_npm_resolver();
 	init_npm_registry_config();
 	init_validate_kici_deps();
-	logger$5 = createLogger({ prefix: "dep-installer" });
+	logger$6 = createLogger({ prefix: "dep-installer" });
 	execFileAsync = promisify(execFile);
 	INSTALL_TIMEOUT_MS = 6e5;
 	INSTALL_MAX_BUFFER = 128 * 1024 * 1024;
@@ -3158,7 +3292,7 @@ async function packNodeModules(kiciDir) {
 	const workDir = dirname(kiciDir);
 	const packageManager = await detectPackageManagerFromManifests(workDir) ?? await detectPackageManagerFromManifests(kiciDir) ?? PackageManager.Npm;
 	const entries = await closureEntries(workDir, kiciDir, packageManager);
-	logger$4.info("Packing dependency closure into tarball", {
+	logger$5.info("Packing dependency closure into tarball", {
 		dir: workDir,
 		packageManager,
 		entries
@@ -3174,7 +3308,7 @@ async function packNodeModules(kiciDir) {
 	const tarball = Buffer.concat(chunks);
 	const hash = sha256(tarball);
 	const sizeMB = (tarball.length / (1024 * 1024)).toFixed(2);
-	logger$4.info("Dependency closure packed", {
+	logger$5.info("Dependency closure packed", {
 		sizeMB,
 		hash: hash.slice(0, 12),
 		durationMs: Date.now() - startTime
@@ -3262,9 +3396,9 @@ function isInside(root, target) {
 function isAbsoluteRel(rel) {
 	return rel.length > 1 && rel[1] === ":";
 }
-var logger$4;
+var logger$5;
 var init_dep_packer = __esmMin((() => {
-	logger$4 = createLogger({ prefix: "dep-packer" });
+	logger$5 = createLogger({ prefix: "dep-packer" });
 }));
 //#endregion
 //#region src/execution/sandbox/env-sanitizer.ts
@@ -3427,6 +3561,7 @@ function buildRequest(dispatch, workDir) {
 		contentHash: jobConfig.contentHash,
 		resolvedHashFiles: jobConfig.resolvedHashFiles,
 		maxLogSizeBytes: dispatch.maxLogSizeBytes,
+		jobTimeoutMs: jobConfig.timeout,
 		container: jobConfig.container,
 		event: jobConfig.event,
 		provider: jobConfig.provider,
@@ -3668,6 +3803,24 @@ function relayAgentApiRequest(msg, ctx) {
 		error: toErrorMessage(err)
 	}));
 }
+/** Relay `cache.request` and pipe the orchestrator response (or an error
+*  response, or a "not configured" response when the agent didn't provide
+*  the callback) back into the sandbox runner. */
+function relayCacheRequest$1(msg, ctx) {
+	if (!ctx.execOptions.onCacheRequest) {
+		safeSendToChild(ctx.child, {
+			type: "cache.response",
+			requestId: msg.requestId,
+			error: "Cache not available in this agent configuration"
+		});
+		return;
+	}
+	ctx.execOptions.onCacheRequest(msg).then((response) => safeSendToChild(ctx.child, response), (err) => safeSendToChild(ctx.child, {
+		type: "cache.response",
+		requestId: msg.requestId,
+		error: toErrorMessage(err)
+	}));
+}
 /** Resolve the result promise for `job.complete` IPC messages. Encrypts
 *  secret outputs (when a runPublicKey is available) and overrides status to
 *  `cancelled` if a cancel was already in flight. */
@@ -3714,7 +3867,9 @@ function relayChildIpcMessage(msg, dispatch, ctx) {
 			ctx.execOptions.onStepStatus(msg.stepIndex, ctx.stepNames.get(msg.stepIndex) ?? "", msg.status, {
 				durationMs: msg.durationMs,
 				...msg.error && { error: msg.error },
-				...msg.secretsAccessed && { secretsAccessed: msg.secretsAccessed }
+				...msg.secretsAccessed && { secretsAccessed: msg.secretsAccessed },
+				...msg.step_type && { step_type: msg.step_type },
+				...msg.data && msg.data
 			});
 			return;
 		case "step.secret_mount":
@@ -3735,6 +3890,9 @@ function relayChildIpcMessage(msg, dispatch, ctx) {
 		case "agent.api.request":
 			relayAgentApiRequest(msg, ctx);
 			return;
+		case "cache.request":
+			relayCacheRequest$1(msg, ctx);
+			return;
 		case "job.complete":
 			handleJobComplete(msg, dispatch, ctx);
 			return;
@@ -3905,10 +4063,10 @@ var init_fork_runner = __esmMin((() => {
 * network access. This mode provides credential isolation only and should
 * be used in trusted environments.
 */
-var logger$3, BareMetalSandbox;
+var logger$4, BareMetalSandbox;
 var init_bare_metal_sandbox = __esmMin((() => {
 	init_fork_runner();
-	logger$3 = createLogger({ prefix: "bare-metal-sandbox" });
+	logger$4 = createLogger({ prefix: "bare-metal-sandbox" });
 	BareMetalSandbox = class {
 		runnerPath;
 		useBwrap;
@@ -3935,12 +4093,12 @@ var init_bare_metal_sandbox = __esmMin((() => {
 			if (this.useBwrap) try {
 				const { execSync } = await import("node:child_process");
 				execSync("which bwrap", { stdio: "ignore" });
-				if (this.sandboxNetwork === "isolated") logger$3.info("Bubblewrap (bwrap) sandbox enabled with network isolation (--unshare-net)");
-				else logger$3.info("Bubblewrap (bwrap) sandbox enabled with host network (KICI_SANDBOX_NETWORK=host)");
+				if (this.sandboxNetwork === "isolated") logger$4.info("Bubblewrap (bwrap) sandbox enabled with network isolation (--unshare-net)");
+				else logger$4.info("Bubblewrap (bwrap) sandbox enabled with host network (KICI_SANDBOX_NETWORK=host)");
 			} catch {
 				throw new Error("Bubblewrap (bwrap) not found. Install bubblewrap or set sandbox=false. On Debian/Ubuntu: apt install bubblewrap");
 			}
-			else logger$3.warn("Bare-metal without sandbox provides limited isolation. Only environment sanitization is active. Enable sandbox=true with bubblewrap for PID/IPC/filesystem namespace isolation.");
+			else logger$4.warn("Bare-metal without sandbox provides limited isolation. Only environment sanitization is active. Enable sandbox=true with bubblewrap for PID/IPC/filesystem namespace isolation.");
 		}
 		/**
 		* Execute a job by forking the workflow runner with sanitized environment.
@@ -4130,6 +4288,32 @@ function relayApiRequest(stream, options, apiMsg) {
 	} catch {}
 }
 /**
+* Relay cache.request from the container runner to the orchestrator via
+* options.onCacheRequest, then write the response back through `stream`. If
+* the agent doesn't expose a cache relay, write a structured error response
+* so the runner doesn't hang.
+*/
+function relayCacheRequest(stream, options, cacheMsg) {
+	const writeResponse = (response) => {
+		try {
+			stream.write(JSON.stringify(response) + "\n");
+		} catch {}
+	};
+	if (!options.onCacheRequest) {
+		writeResponse({
+			type: "cache.response",
+			requestId: cacheMsg.requestId,
+			error: "Cache not available in this agent configuration"
+		});
+		return;
+	}
+	options.onCacheRequest(cacheMsg).then((response) => writeResponse(response), (err) => writeResponse({
+		type: "cache.response",
+		requestId: cacheMsg.requestId,
+		error: toErrorMessage(err)
+	}));
+}
+/**
 * Apply a job.complete message to the mutable runner state: capture status,
 * merge any bulk-reported step results, propagate plain outputs, and encrypt
 * secret outputs if a run public key is available.
@@ -4144,14 +4328,14 @@ function applyJobComplete(msg, stepResults, state, options) {
 	if (msg.secretOutputs && options.dispatch.runPublicKey) try {
 		state.encryptedSecretOutputs = encryptSecretOutputs(msg.secretOutputs, options.dispatch.runPublicKey);
 	} catch (err) {
-		logger$2.warn("Failed to encrypt secret outputs", { error: toErrorMessage(err) });
+		logger$3.warn("Failed to encrypt secret outputs", { error: toErrorMessage(err) });
 	}
 }
-var logger$2, MAX_STDERR_LINES, ABORT_GRACE_MS, CONTAINER_STOP_TIMEOUT, ContainerSandbox;
+var logger$3, MAX_STDERR_LINES, ABORT_GRACE_MS, CONTAINER_STOP_TIMEOUT, ContainerSandbox;
 var init_container_sandbox = __esmMin((() => {
 	init_fork_runner();
 	init_secret_encryption();
-	logger$2 = createLogger({ prefix: "container-sandbox" });
+	logger$3 = createLogger({ prefix: "container-sandbox" });
 	MAX_STDERR_LINES = 20;
 	ABORT_GRACE_MS = 1e4;
 	CONTAINER_STOP_TIMEOUT = 10;
@@ -4183,7 +4367,7 @@ var init_container_sandbox = __esmMin((() => {
 		async setup(options) {
 			this.containerName = `kici-sandbox-${this.jobId}-${Date.now()}`;
 			const envArray = Object.entries(this.env).map(([k, v]) => `${k}=${v}`);
-			logger$2.info("Creating sandbox container", {
+			logger$3.info("Creating sandbox container", {
 				name: this.containerName,
 				image: this.image,
 				workDir: options.workDir
@@ -4201,7 +4385,7 @@ var init_container_sandbox = __esmMin((() => {
 				HostConfig: { Binds: [`${options.workDir}:/workspace`, `${this.runnerPath}:${this.runnerMountPath}:ro`] }
 			});
 			await this.container.start();
-			logger$2.info("Sandbox container started", {
+			logger$3.info("Sandbox container started", {
 				name: this.containerName,
 				containerId: this.container.id.slice(0, 12)
 			});
@@ -4214,7 +4398,7 @@ var init_container_sandbox = __esmMin((() => {
 			try {
 				outcome = await this.awaitJobCompletion(streamCtx, options);
 			} catch (err) {
-				logger$2.error("Job execution error", {
+				logger$3.error("Job execution error", {
 					error: toErrorMessage(err),
 					stderrTail: streamCtx.stderrLines.slice(-5).join("\n")
 				});
@@ -4264,7 +4448,7 @@ var init_container_sandbox = __esmMin((() => {
 			});
 			const abortHandler = () => {
 				this.handleAbort().catch((err) => {
-					logger$2.warn("Error during abort", { error: toErrorMessage(err) });
+					logger$3.warn("Error during abort", { error: toErrorMessage(err) });
 				});
 			};
 			options.signal.addEventListener("abort", abortHandler, { once: true });
@@ -4301,7 +4485,7 @@ var init_container_sandbox = __esmMin((() => {
 					try {
 						msg = JSON.parse(line);
 					} catch {
-						logger$2.warn("Non-JSON output from runner", { line: line.slice(0, 200) });
+						logger$3.warn("Non-JSON output from runner", { line: line.slice(0, 200) });
 						return;
 					}
 					if (this.dispatchRunnerMessage(msg, stream, options, stepNames, stepResults, state)) resolve({
@@ -4349,7 +4533,9 @@ var init_container_sandbox = __esmMin((() => {
 					options.onStepStatus(msg.stepIndex, name, msg.status, {
 						durationMs: msg.durationMs,
 						...msg.error && { error: msg.error },
-						...msg.secretsAccessed && { secretsAccessed: msg.secretsAccessed }
+						...msg.secretsAccessed && { secretsAccessed: msg.secretsAccessed },
+						...msg.step_type && { step_type: msg.step_type },
+						...msg.data && msg.data
 					});
 					stepResults.push({
 						name,
@@ -4381,11 +4567,14 @@ var init_container_sandbox = __esmMin((() => {
 				case "agent.api.request":
 					relayApiRequest(stream, options, msg);
 					return false;
+				case "cache.request":
+					relayCacheRequest(stream, options, msg);
+					return false;
 				case "job.complete":
 					applyJobComplete(msg, stepResults, state, options);
 					return true;
 				default:
-					logger$2.warn("Unrecognized IPC message from container runner", { type: msg.type });
+					logger$3.warn("Unrecognized IPC message from container runner", { type: msg.type });
 					return false;
 			}
 		}
@@ -4412,14 +4601,14 @@ var init_container_sandbox = __esmMin((() => {
 		async teardown() {
 			if (!this.container) return;
 			if (this.keepFailed && this.jobFailed) {
-				logger$2.info("Keeping failed container for debugging", {
+				logger$3.info("Keeping failed container for debugging", {
 					name: this.containerName,
 					containerId: this.container.id.slice(0, 12)
 				});
 				this.container = null;
 				return;
 			}
-			logger$2.info("Tearing down sandbox container", { name: this.containerName });
+			logger$3.info("Tearing down sandbox container", { name: this.containerName });
 			try {
 				await this.container.stop({ t: CONTAINER_STOP_TIMEOUT });
 			} catch {}
@@ -4450,7 +4639,7 @@ var init_container_sandbox = __esmMin((() => {
 		*/
 		async handleAbort() {
 			if (!this.execStream && !this.container) return;
-			logger$2.info("Aborting sandbox execution", { name: this.containerName });
+			logger$3.info("Aborting sandbox execution", { name: this.containerName });
 			if (this.execStream) try {
 				this.execStream.write(JSON.stringify({ type: "abort" }) + "\n");
 			} catch {}
@@ -4519,7 +4708,7 @@ function determineExecutionMode(jobConfig, agentConfig) {
 	if (agentConfig.scalerManaged) return "firecracker";
 	return "bare-metal";
 }
-var logger$1, JobRunner$1;
+var logger$2, JobRunner$1;
 var init_job_runner = __esmMin((() => {
 	init_git_clone();
 	init_workflow_loader();
@@ -4536,7 +4725,7 @@ var init_job_runner = __esmMin((() => {
 	init_download();
 	init_sandbox();
 	init_prometheus();
-	logger$1 = createLogger({ prefix: "job-runner" });
+	logger$2 = createLogger({ prefix: "job-runner" });
 	JobRunner$1 = class {
 		send;
 		sendDirect;
@@ -4550,6 +4739,7 @@ var init_job_runner = __esmMin((() => {
 		_sendRunEvent;
 		_sendConcurrencyReport;
 		_sendApiRequest;
+		_requestUserCache;
 		/** Tracks running jobs for concurrency and cancellation */
 		activeJobs = /* @__PURE__ */ new Map();
 		/** Active sandbox for the current job (used for abort). */
@@ -4567,6 +4757,7 @@ var init_job_runner = __esmMin((() => {
 			this._sendRunEvent = deps.sendRunEvent;
 			this._sendConcurrencyReport = deps.sendConcurrencyReport;
 			this._sendApiRequest = deps.sendApiRequest;
+			this._requestUserCache = deps.requestUserCache;
 		}
 		/**
 		* Execute a dispatched job through its full lifecycle.
@@ -4634,7 +4825,7 @@ var init_job_runner = __esmMin((() => {
 			}
 			if (jobConfig.buildOnly === true) {
 				if (jobConfig.fullRepo) {
-					logger$1.warn("Build job received for fullRepo run -- skipping (should not happen)", {
+					logger$2.warn("Build job received for fullRepo run -- skipping (should not happen)", {
 						jobId,
 						runId
 					});
@@ -4656,7 +4847,7 @@ var init_job_runner = __esmMin((() => {
 		async executeStandardJob(dispatch, workDir, abortController) {
 			const { runId, jobId } = dispatch;
 			const ctx = getRequestContext();
-			logger$1.info(`Run: ${ctx.runId ?? runId} | Trace: ${ctx.requestId ?? "N/A"}`);
+			logger$2.info(`Run: ${ctx.runId ?? runId} | Trace: ${ctx.requestId ?? "N/A"}`);
 			this.sendJobStatus(dispatch, ExecutionJobStatus.enum.running);
 			const heartbeatTimer = setInterval(() => {
 				this.send({
@@ -4681,7 +4872,7 @@ var init_job_runner = __esmMin((() => {
 				if (sandbox) {
 					this.emitRunEvent(runId, "agent.teardown", { jobId });
 					await sandbox.teardown().catch((err) => {
-						logger$1.warn("Sandbox teardown error", { error: toErrorMessage(err) });
+						logger$2.warn("Sandbox teardown error", { error: toErrorMessage(err) });
 					});
 				}
 			}
@@ -4709,7 +4900,7 @@ var init_job_runner = __esmMin((() => {
 				environmentVars: typedConfig.environmentVars ?? void 0,
 				jobEnv: typedConfig.jobEnv ?? void 0
 			});
-			logger$1.info("Creating execution sandbox", {
+			logger$2.info("Creating execution sandbox", {
 				executionMode,
 				jobId,
 				runnerPath
@@ -4780,6 +4971,7 @@ var init_job_runner = __esmMin((() => {
 				onStepStatus: (stepIndex, stepName, state, data) => {
 					let logBytesStreamed;
 					if (state === ExecutionStepStatus.enum.success || state === ExecutionStepStatus.enum.failed || state === ExecutionStepStatus.enum.skipped) logBytesStreamed = logStreamers.get(stepIndex)?.getTotalBytes() ?? 0;
+					this.maybeEmitCacheRunEvent(runId, jobId, stepIndex, state, data);
 					this.sendStepStatus(dispatch, stepIndex, stepName, state, data, logBytesStreamed);
 				},
 				onLogLine: (stepIndex, line) => {
@@ -4804,6 +4996,7 @@ var init_job_runner = __esmMin((() => {
 					};
 				},
 				onApiRequest: this._sendApiRequest ? async (method, params) => this._sendApiRequest(method, params) : void 0,
+				onCacheRequest: this._requestUserCache ? async (request) => this._requestUserCache(jobId, request) : void 0,
 				onSecretMount: (event) => {
 					this.emitRunEvent(runId, "step.secret_mount", {
 						jobId,
@@ -4837,7 +5030,7 @@ var init_job_runner = __esmMin((() => {
 				stepsTotal.add(1, { status: stepResult.status });
 				if (stepResult.durationMs > 0) stepDurationSeconds.record(stepResult.durationMs / 1e3);
 			}
-			if (result.status === ExecutionJobStatus.enum.failed) logger$1.error("Sandbox returned failed result", {
+			if (result.status === ExecutionJobStatus.enum.failed) logger$2.error("Sandbox returned failed result", {
 				durationMs: result.durationMs,
 				stepCount: result.stepResults.length,
 				steps: result.stepResults.map((r) => `${r.name}:${r.status}`).join(","),
@@ -4866,7 +5059,7 @@ var init_job_runner = __esmMin((() => {
 		async handleBuildJob(dispatch, workDir, abortController) {
 			const { runId, jobId, jobConfig } = dispatch;
 			const buildCtx = getRequestContext();
-			logger$1.info(`Run: ${buildCtx.runId ?? runId} | Trace: ${buildCtx.requestId ?? "N/A"}`);
+			logger$2.info(`Run: ${buildCtx.runId ?? runId} | Trace: ${buildCtx.requestId ?? "N/A"}`);
 			this.sendJobStatus(dispatch, ExecutionJobStatus.enum.running);
 			const buildStreamer = this.createStepStreamer(dispatch, 0);
 			const buildLog = (msg) => buildStreamer.addLine(msg);
@@ -4955,14 +5148,14 @@ var init_job_runner = __esmMin((() => {
 			const cliPublicKey = jobConfig.cliPublicKey;
 			const orchestratorPrivateKey = jobConfig.orchestratorPrivateKey;
 			if (tarballUrl && cliPublicKey && orchestratorPrivateKey) {
-				logger$1.info("Applying overlay tarball for test run", { jobId });
+				logger$2.info("Applying overlay tarball for test run", { jobId });
 				const overlayResult = await applyOverlay({
 					tarballUrl,
 					cliPublicKey,
 					orchestratorPrivateKey,
 					repoDir: workDir
 				});
-				logger$1.info("Overlay applied", {
+				logger$2.info("Overlay applied", {
 					filesApplied: overlayResult.filesApplied,
 					filesDeleted: overlayResult.filesDeleted
 				});
@@ -4990,9 +5183,9 @@ var init_job_runner = __esmMin((() => {
 				platform: os.platform(),
 				arch: os.arch()
 			};
-			logger$1.info("Requesting dep upload URL from orchestrator", { lockfileHash: buildConfig.lockfileHash });
+			logger$2.info("Requesting dep upload URL from orchestrator", { lockfileHash: buildConfig.lockfileHash });
 			const depUploadUrl = await this.requestUploadUrl(dispatch.jobId, "deps", depKey);
-			logger$1.info("Uploading dep tarball to S3", {
+			logger$2.info("Uploading dep tarball to S3", {
 				size: tarball.length,
 				hash: hash.slice(0, 12)
 			});
@@ -5001,7 +5194,7 @@ var init_job_runner = __esmMin((() => {
 				...depKey,
 				depsHash: hash
 			});
-			logger$1.info("Dep tarball upload complete", { lockfileHash: buildConfig.lockfileHash });
+			logger$2.info("Dep tarball upload complete", { lockfileHash: buildConfig.lockfileHash });
 			buildLog(`Deps tarball uploaded (${tarball.length} bytes)`);
 			this.sendJobStatus(dispatch, ExecutionJobStatus.enum.running, {
 				buildEvent: "deps_packed",
@@ -5027,15 +5220,15 @@ var init_job_runner = __esmMin((() => {
 				platform: os.platform(),
 				arch: os.arch()
 			};
-			logger$1.info("Requesting source tarball upload URL from orchestrator", { contentHash: buildConfig.contentHash });
+			logger$2.info("Requesting source tarball upload URL from orchestrator", { contentHash: buildConfig.contentHash });
 			const sourceUploadUrl = await this.requestUploadUrl(dispatch.jobId, "source", sourceKey);
-			logger$1.info("Uploading source tarball to S3", {
+			logger$2.info("Uploading source tarball to S3", {
 				size: tarball.length,
 				contentHash: buildConfig.contentHash
 			});
 			await uploadToPresignedUrl(sourceUploadUrl, tarball);
 			this.sendUploadComplete(dispatch.jobId, "source", sourceKey);
-			logger$1.info("Source tarball upload complete", { contentHash: buildConfig.contentHash });
+			logger$2.info("Source tarball upload complete", { contentHash: buildConfig.contentHash });
 			buildLog(`Source tarball packed and uploaded (${tarball.length} bytes, hash: ${buildConfig.contentHash.slice(0, 12)})`);
 			this.sendJobStatus(dispatch, ExecutionJobStatus.enum.running, {
 				buildEvent: "source_packed",
@@ -5058,7 +5251,7 @@ var init_job_runner = __esmMin((() => {
 		async handleInitJob(dispatch, workDir, abortController) {
 			const { runId, jobId, jobConfig } = dispatch;
 			const config = jobConfig;
-			logger$1.info("Starting init job", {
+			logger$2.info("Starting init job", {
 				jobId,
 				targetJobName: config.targetJobName,
 				workflowName: config.workflowName
@@ -5106,7 +5299,7 @@ var init_job_runner = __esmMin((() => {
 				}
 				const kiciDir = join(workDir, ".kici");
 				const hasPackage = await fileExists(join(kiciDir, "package.json"));
-				logger$1.info("Init job: checking deps", {
+				logger$2.info("Init job: checking deps", {
 					kiciDir,
 					hasPackageJson: hasPackage,
 					source: config.source
@@ -5129,7 +5322,7 @@ var init_job_runner = __esmMin((() => {
 						dynamicConcurrencyGroup: config.dynamicConcurrencyGroup
 					}, config.timeoutMs);
 				});
-				logger$1.info("Init job completed successfully", {
+				logger$2.info("Init job completed successfully", {
 					jobId,
 					hasEnvironment: initResult.environmentName !== void 0,
 					hasEnv: initResult.env !== void 0,
@@ -5145,7 +5338,7 @@ var init_job_runner = __esmMin((() => {
 				});
 			} catch (err) {
 				const errorMsg = toErrorMessage(err);
-				logger$1.error("Init job failed", {
+				logger$2.error("Init job failed", {
 					jobId,
 					error: errorMsg
 				});
@@ -5172,7 +5365,7 @@ var init_job_runner = __esmMin((() => {
 			const { runId, jobId, jobConfig } = dispatch;
 			const config = jobConfig;
 			const timeoutMs = config.timeoutMs ?? 12e4;
-			logger$1.info("Starting DynamicJobFn evaluation", {
+			logger$2.info("Starting DynamicJobFn evaluation", {
 				jobId,
 				workflowName: config.workflowName,
 				sourceIndex: config.source.index
@@ -5273,7 +5466,7 @@ var init_job_runner = __esmMin((() => {
 						workflowName: config.workflowName
 					});
 				});
-				logger$1.info("DynamicJobFn evaluation completed", {
+				logger$2.info("DynamicJobFn evaluation completed", {
 					jobId,
 					generatedJobCount: lockJobs.length,
 					jobNames: lockJobs.map((j) => j.name)
@@ -5288,7 +5481,7 @@ var init_job_runner = __esmMin((() => {
 				});
 			} catch (err) {
 				const errorMsg = toErrorMessage(err);
-				logger$1.error("DynamicJobFn evaluation failed", {
+				logger$2.error("DynamicJobFn evaluation failed", {
 					jobId,
 					error: errorMsg
 				});
@@ -5296,10 +5489,17 @@ var init_job_runner = __esmMin((() => {
 				await evalStreamer.flush();
 				evalStreamer.destroy();
 				this.sendStepStatus(dispatch, 0, "evaluate", ExecutionStepStatus.enum.failed, { error: errorMsg }, evalStreamer.getTotalBytes());
-				this.sendJobStatus(dispatch, ExecutionJobStatus.enum.failed, {
+				const dynamicData = {
 					error: errorMsg,
 					dynamicFailed: true
-				});
+				};
+				if (err instanceof MatrixExpansionError) dynamicData.initFailure = {
+					scope: "job",
+					category: InitFailureCategory.enum.matrix_expansion,
+					message: errorMsg,
+					jobName: err.jobName
+				};
+				this.sendJobStatus(dispatch, ExecutionJobStatus.enum.failed, dynamicData);
 			} finally {
 				clearInterval(heartbeatTimer);
 			}
@@ -5361,6 +5561,31 @@ var init_job_runner = __esmMin((() => {
 			this._sendRunEvent(runId, eventType, opts);
 		}
 		/**
+		* Emit a `cache.restore` / `cache.save` run event for a cache pseudo-step.
+		*
+		* The cache phase tags its `step.complete` IPC with a {@link CacheStepType}
+		* `step_type` and a `data.cacheOutcome` ({@link CacheOutcome}); when one of
+		* those terminal pseudo-step statuses arrives here, mirror it onto the run
+		* timeline as a `run.event` so hit/miss/saved/skipped/error is recorded for
+		* the dashboard. A no-op for regular steps and hooks.
+		*/
+		maybeEmitCacheRunEvent(runId, jobId, stepIndex, state, data) {
+			if (state === ExecutionStepStatus.enum.running) return;
+			const stepType = data?.step_type;
+			const eventType = stepType === CacheStepType.enum["cache:restore"] ? CacheRunEventType.enum["cache.restore"] : stepType === CacheStepType.enum["cache:save"] ? CacheRunEventType.enum["cache.save"] : void 0;
+			if (!eventType) return;
+			this.emitRunEvent(runId, eventType, {
+				jobId,
+				metadata: {
+					stepIndex,
+					...data?.cacheOutcome !== void 0 && { outcome: data.cacheOutcome },
+					...data?.key !== void 0 && { key: data.key },
+					...data?.matchedKey !== void 0 && { matchedKey: data.matchedKey },
+					...data?.bytes !== void 0 && { bytes: data.bytes }
+				}
+			});
+		}
+		/**
 		* Create a LogStreamer for a synthetic step (build, evaluate, etc.).
 		*/
 		createStepStreamer(dispatch, stepIndex) {
@@ -5444,14 +5669,14 @@ var init_job_runner = __esmMin((() => {
 */
 init_console_capture();
 init_npm_resolver();
-const AGENT_VERSION = "0.1.14";
-const BUILD_COMMIT = "0fc7a43c9";
-const SDK_VERSION = "0.1.14";
-const SDK_BUNDLE_HASH = "675aafe4de03e677785ef2794d8f34951b14e2bd1e6f0ea825953d6c2abfe128";
-const SHARED_VERSION = "0.1.14";
-const SHARED_BUNDLE_HASH = "5a44862f00d382dbac676c0bdbf9e3fb3016d1c4667b60ea4ae6cbf8ac8deaf4";
-const ENGINE_VERSION = "0.1.14";
-const ENGINE_BUNDLE_HASH = "8eef210908744b12e19a2b915520298c5dde5abd4a064fa75e87123e237bf932";
+const AGENT_VERSION = "0.1.15";
+const BUILD_COMMIT = "831f6a763";
+const SDK_VERSION = "0.1.15";
+const SDK_BUNDLE_HASH = "cee24b67bbb4a1d2a770e4063dd37a9af33409faeb5ce32f936703b4431316dd";
+const SHARED_VERSION = "0.1.15";
+const SHARED_BUNDLE_HASH = "e82a8b68a7d72698674352158c5de4c0d10824c61bfa7166cc8f846044b8b5e4";
+const ENGINE_VERSION = "0.1.15";
+const ENGINE_BUNDLE_HASH = "032d6b28b3d32bcbea80ba80a52934b017ee2c86a97fcaf8fe8db0d86d72a7f7";
 initTelemetry({
 	serviceName: "kici-agent",
 	otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
@@ -5459,18 +5684,19 @@ initTelemetry({
 const { connectionStatus, jobsActive, jobsTotal } = await Promise.resolve().then(() => (init_prometheus(), prometheus_exports));
 const { JobRunner } = await Promise.resolve().then(() => (init_job_runner(), job_runner_exports));
 setServiceName("agent");
-const logger = createLogger({ prefix: "agent" });
+const logger$1 = createLogger({ prefix: "agent" });
 installConsoleCapture();
-await guardStartup(logger, async () => {
+await guardStartup(logger$1, async () => {
 	const config = loadConfig();
-	logger.info("Agent starting", {
+	logger$1.info("Agent starting", {
 		agentId: config.agentId,
 		orchestratorUrl: config.orchestratorUrl,
 		labels: config.labels,
 		roles: config.roles,
 		port: config.port
 	});
-	logger.info("agent.build.info", {
+	gcStaleAgentTmpDirs();
+	logger$1.info("agent.build.info", {
 		agentVersion: AGENT_VERSION,
 		buildCommit: BUILD_COMMIT,
 		sdkVersion: SDK_VERSION,
@@ -5492,7 +5718,7 @@ await guardStartup(logger, async () => {
 	if (toolErrors.length > 0) throw new Error("Agent required-tools validation failed:\n" + toolErrors.map((e) => `  - ${e}`).join("\n"));
 	if (config.roles === void 0 || config.roles.includes("builder")) {
 		const npmVersion = verifyNpmAvailable();
-		logger.info("Builder role: npm verified", { npmVersion });
+		logger$1.info("Builder role: npm verified", { npmVersion });
 	}
 	let isDraining = false;
 	let idleShutdownTimer;
@@ -5509,7 +5735,8 @@ await guardStartup(logger, async () => {
 		sendJobContext: (runId, jobId, context) => client.sendJobContext(runId, jobId, context),
 		sendRunEvent: (runId, eventType, opts) => client.sendRunEvent(runId, eventType, opts),
 		sendConcurrencyReport: (runId, jobId, group) => client.sendConcurrencyReport(runId, jobId, group),
-		sendApiRequest: (method, params) => client.sendApiRequest(method, params ?? {})
+		sendApiRequest: (method, params) => client.sendApiRequest(method, params ?? {}),
+		requestUserCache: (jobId, request) => client.requestUserCache(jobId, request)
 	});
 	/** Build and send an agent.status message with dynamic OS metadata. */
 	function sendAgentStatus() {
@@ -5533,15 +5760,31 @@ await guardStartup(logger, async () => {
 				jobId: dispatch.jobId
 			}, () => {
 				if (isDraining) {
-					logger.info("Draining: rejecting job dispatch", { jobId: dispatch.jobId });
+					logger$1.info("Draining: rejecting job dispatch", { jobId: dispatch.jobId });
+					client.sendDirect({
+						type: "job.reject",
+						messageId: randomUUID(),
+						runId: dispatch.runId,
+						jobId: dispatch.jobId,
+						reason: "draining",
+						timestamp: Date.now()
+					});
 					sendAgentStatus();
 					return;
 				}
 				if (jobRunner.activeJobs.size > 0) {
-					logger.warn("Already running a job, cannot accept another", {
+					logger$1.warn("Already running a job, rejecting dispatch", {
 						jobId: dispatch.jobId,
 						activeJobs: jobRunner.activeJobs.size
 					});
+					client.sendDirect({
+						type: "job.reject",
+						messageId: randomUUID(),
+						runId: dispatch.runId,
+						jobId: dispatch.jobId,
+						reason: "busy",
+						timestamp: Date.now()
+					});
 					sendAgentStatus();
 					return;
 				}
@@ -5549,7 +5792,14 @@ await guardStartup(logger, async () => {
 					clearTimeout(idleShutdownTimer);
 					idleShutdownTimer = void 0;
 				}
-				logger.info("Accepting job dispatch", {
+				client.sendDirect({
+					type: "job.ack",
+					messageId: randomUUID(),
+					runId: dispatch.runId,
+					jobId: dispatch.jobId,
+					timestamp: Date.now()
+				});
+				logger$1.info("Accepting job dispatch", {
 					jobId: dispatch.jobId,
 					runId: dispatch.runId,
 					activeJobs: jobRunner.activeJobs.size + 1
@@ -5558,7 +5808,7 @@ await guardStartup(logger, async () => {
 				jobRunner.execute(dispatch).then(() => {
 					jobsTotal.add(1, { status: "success" });
 				}).catch((err) => {
-					logger.error("Job execution error", {
+					logger$1.error("Job execution error", {
 						jobId: dispatch.jobId,
 						error: toErrorMessage(err)
 					});
@@ -5569,7 +5819,7 @@ await guardStartup(logger, async () => {
 					sendAgentStatus();
 					if (config.scalerManaged && jobRunner.activeJobs.size === 0) {
 						if (client.state !== "registered") {
-							logger.info("Scaler-managed agent idle but disconnected, deferring shutdown until reconnected");
+							logger$1.info("Scaler-managed agent idle but disconnected, deferring shutdown until reconnected");
 							return;
 						}
 						startIdleShutdownTimer();
@@ -5578,7 +5828,7 @@ await guardStartup(logger, async () => {
 			});
 		},
 		onJobCancel: (cancel) => {
-			logger.info("Job cancel received", {
+			logger$1.info("Job cancel received", {
 				jobId: cancel.jobId,
 				reason: cancel.reason
 			});
@@ -5596,13 +5846,13 @@ await guardStartup(logger, async () => {
 		const idleMs = config.scalerIdleTimeoutMs;
 		if (idleShutdownTimer) clearTimeout(idleShutdownTimer);
 		if (idleMs <= 0) {
-			logger.info("Scaler-managed agent idle after job completion, shutting down");
+			logger$1.info("Scaler-managed agent idle after job completion, shutting down");
 			gracefulShutdown("scaler-idle");
 		} else {
-			logger.info(`Scaler-managed agent idle, waiting ${idleMs}ms for follow-up jobs`);
+			logger$1.info(`Scaler-managed agent idle, waiting ${idleMs}ms for follow-up jobs`);
 			idleShutdownTimer = setTimeout(() => {
 				if (jobRunner.activeJobs.size === 0) {
-					logger.info("Scaler-managed agent still idle after timeout, shutting down");
+					logger$1.info("Scaler-managed agent still idle after timeout, shutting down");
 					gracefulShutdown("scaler-idle");
 				}
 			}, idleMs);
@@ -5612,17 +5862,17 @@ await guardStartup(logger, async () => {
 		if (!config.scalerManaged || jobRunner.activeJobs.size > 0) return;
 		if (pendingDispatch) {
 			const safetyMs = config.scalerPendingDispatchTimeoutMs;
-			logger.info(`Scaler-managed agent registered with pending bound dispatch, deferring idle shutdown for ${safetyMs}ms`);
+			logger$1.info(`Scaler-managed agent registered with pending bound dispatch, deferring idle shutdown for ${safetyMs}ms`);
 			if (idleShutdownTimer) clearTimeout(idleShutdownTimer);
 			idleShutdownTimer = setTimeout(() => {
 				if (jobRunner.activeJobs.size === 0) {
-					logger.warn("Scaler-managed agent pending-dispatch safety timeout exceeded, shutting down");
+					logger$1.warn("Scaler-managed agent pending-dispatch safety timeout exceeded, shutting down");
 					gracefulShutdown("scaler-pending-dispatch-timeout");
 				}
 			}, safetyMs);
 			return;
 		}
-		logger.info("Scaler-managed agent reconnected and idle, starting idle shutdown timer");
+		logger$1.info("Scaler-managed agent reconnected and idle, starting idle shutdown timer");
 		startIdleShutdownTimer();
 	};
 	const wsTransport = new winston.transports.Stream({
@@ -5632,14 +5882,14 @@ await guardStartup(logger, async () => {
 		} }),
 		format: winston.format.combine(winston.format.timestamp(), winston.format.json())
 	});
-	logger.add(wsTransport);
+	logger$1.add(wsTransport);
 	const envProbes = {};
 	for (const [k, v] of Object.entries(process.env)) {
 		if (v === void 0) continue;
 		if (!/_ENV_PROBE$|_ENV_PROBE_/.test(k)) continue;
 		envProbes[k] = v.length <= 64 ? v : `${v.slice(0, 61)}...`;
 	}
-	if (Object.keys(envProbes).length > 0) logger.info("Agent startup env probes (diagnostic)", envProbes);
+	if (Object.keys(envProbes).length > 0) logger$1.info("Agent startup env probes (diagnostic)", envProbes);
 	client.connect();
 	connectionStatus.add(1);
 	const metricsReporter = new MetricsReporter({
@@ -5679,13 +5929,13 @@ await guardStartup(logger, async () => {
 		fetch: app.fetch,
 		port: config.port
 	}, (info) => {
-		logger.info(`Agent started on port ${info.port}`, {
+		logger$1.info(`Agent started on port ${info.port}`, {
 			port: info.port,
 			agentId: config.agentId
 		});
 	});
 	const { shutdown: gracefulShutdown } = setupGracefulShutdown({
-		logger,
+		logger: logger$1,
 		timeoutMs: 1e4,
 		onForceExit: () => {
 			for (const job of jobRunner.activeJobs.values()) job.abortController.abort();
@@ -5703,7 +5953,7 @@ await guardStartup(logger, async () => {
 				name: "Waiting for active jobs to complete",
 				fn: async () => {
 					if (jobRunner.activeJobs.size > 0) {
-						logger.info("Active jobs remaining", { activeJobs: jobRunner.activeJobs.size });
+						logger$1.info("Active jobs remaining", { activeJobs: jobRunner.activeJobs.size });
 						await Promise.allSettled([...jobRunner.activeJobs.values()].map((j) => j.completionPromise));
 					}
 				}
@@ -5737,17 +5987,17 @@ await guardStartup(logger, async () => {
 		]
 	});
 	process.on("SIGUSR1", () => {
-		logger.info("Received SIGUSR1, entering drain mode");
+		logger$1.info("Received SIGUSR1, entering drain mode");
 		isDraining = true;
 		if (jobRunner.activeJobs.size === 0) {
-			logger.info("No active jobs, shutting down immediately");
+			logger$1.info("No active jobs, shutting down immediately");
 			gracefulShutdown("SIGUSR1-drain");
 			return;
 		}
 		const checkDrained = setInterval(() => {
 			if (jobRunner.activeJobs.size === 0) {
 				clearInterval(checkDrained);
-				logger.info("All jobs drained, shutting down");
+				logger$1.info("All jobs drained, shutting down");
 				gracefulShutdown("SIGUSR1-drain");
 			}
 		}, 1e3);