@kici-dev/agent 0.1.27 → 0.2.0

package/dist/server.js

@@ -1,7 +1,7 @@
 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 { createRequire, register } from "node:module";
 import crypto$1, { createCipheriv, createHash, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, randomUUID } from "node:crypto";
 import * as os$1 from "node:os";
 import os, { hostname, tmpdir } from "node:os";
@@ -9,23 +9,25 @@ import { PassThrough, Readable, Transform, Writable } from "node:stream";
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import winston from "winston";
-import { RingBuffer, addLogsToArchive, chunkBuffer, createHealthRoutes, createLogger, createMeter, createMetricsRoutes, deriveSharedSecret, getPrometheusExporter, getReconnectDelay, getRequestContext, guardStartup, initTelemetry, logger, normalizeLineEndings, redactConfig, requestContext, setServiceName, setupGracefulShutdown, sha256, sha256File, toErrorMessage, validateRequiredTools } from "@kici-dev/shared";
+import { AgentDeliveryMode, AgentPlatform, RingBuffer, addLogsToArchive, chunkBuffer, createHealthRoutes, createLogger, createMeter, createMetricsRoutes, deriveSharedSecret, getPrometheusExporter, getReconnectDelay, getRequestContext, guardStartup, initTelemetry, kiciTmpBase, logger, normalizeLineEndings, redactConfig, 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, CacheRunEventType, CacheStepType, ExecutionJobStatus, ExecutionStepStatus, InitFailureCategory, KNOWN_ROLES, PROTOCOL_VERSION, SANDBOX_DEFAULT_VARS, WS_CLOSE_AGENT_AUTH_FAILED, WS_MAX_PAYLOAD_BYTES, applyIncludeExclude, buildTrustedPassthroughEnv, deriveOsArchLabels, expandMatrix, heartbeatSchema, hostLabel, mergeAutoLabels, orchestratorToAgentMessageSchema, parseHostPropertyAssignments, resolveRoleLabels, resolveWhenToRunOn, validateNoReservedLabels } from "@kici-dev/engine";
+import { ALLOWED_SYSTEM_VARS, ArtifactCompleteAckOutcome, CacheRunEventType, CacheStepType, ExecutionJobStatus, ExecutionStepStatus, InitFailureCategory, KNOWN_ROLES, LogStream, MAX_MATRIX_MATERIALIZATION, MatrixShapeError, PROTOCOL_VERSION, SANDBOX_DEFAULT_VARS, WS_CLOSE_AGENT_AUTH_FAILED, WS_MAX_PAYLOAD_BYTES, applyIncludeExclude, buildTrustedPassthroughEnv, deriveOsArchLabels, expandMatrix, hasOrchAgentCapability, heartbeatSchema, hostLabel, matrixCombinationCount, mergeAutoLabels, orchestratorToAgentMessageSchema, parseHostPropertyAssignments, resolveRoleLabels, resolveWhenToRunOn, validateNoReservedLabels } from "@kici-dev/engine";
 import { execFile, execFileSync, execSync, fork, spawn } from "node:child_process";
 import WebSocket from "ws";
 import * as fs$1 from "node:fs";
-import fs, { existsSync } from "node:fs";
+import fs, { createReadStream, createWriteStream, existsSync } from "node:fs";
 import { ZipArchive } from "archiver";
 import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { format, promisify } from "node:util";
+import { OTEL_DATA_POINT_TYPE, mapDataPointTypeToWireKind } from "@kici-dev/engine/metrics/metric-kind-compat";
 import { gcStaleTmpDirs } from "@kici-dev/core/tmp-gc";
-import fsPromises, { access, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, unlink, writeFile } from "node:fs/promises";
+import fsPromises, { access, lstat, mkdir, readFile, readdir, realpath, unlink, writeFile } from "node:fs/promises";
+import { makeTempDir } from "@kici-dev/core/tmp";
 import Docker from "dockerode";
-import { buildKiciApi, buildNeedsContext, isDynamicGroupRef, isDynamicJobFn, isParallelGroup, isStaticArray, isStaticObject } from "@kici-dev/sdk";
+import { buildKiciApi, buildNeedsContext, isDynamicGroupRef, isDynamicJobFn, isParallelGroup, isStaticArray, isStaticObject, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
 import { c, x } from "tar";
 import https from "node:https";
 import http from "node:http";
@@ -101,10 +103,18 @@ const envDef = defineEnv({
 		dockerKeepFailed: z.string().default("false").transform((s) => s === "true"),
 		jobHeartbeatIntervalMs: z.coerce.number().default(6e4),
 		backpressureMode: z.enum(["pause", "drop"]).default("pause"),
+		agentPayloadDir: z.string().optional(),
+		agentCommand: z.string().optional(),
 		sandbox: z.string().default("false").transform((s) => s === "true"),
 		trustedEnv: z.string().default("false").transform((s) => s === "true"),
 		inPlace: z.string().default("false").transform((s) => s === "true"),
 		sandboxNetwork: z.enum(["isolated", "host"]).default("isolated"),
+		sandboxHardened: z.string().default("true").transform((s) => s !== "false"),
+		sandboxReadonlyRootfs: z.string().default("false").transform((s) => s === "true"),
+		sandboxUser: z.string().optional(),
+		sandboxPidsLimit: z.coerce.number().int().positive().default(512),
+		sandboxMemoryBytes: z.coerce.number().int().positive().default(2 * 1024 * 1024 * 1024),
+		sandboxNanoCpus: z.coerce.number().int().positive().default(2 * 1e9),
 		scalerManaged: z.string().optional().transform((s) => s === "1"),
 		scalerIdleTimeoutMs: z.coerce.number().default(5e3),
 		scalerPendingDispatchTimeoutMs: z.coerce.number().default(6e4),
@@ -129,10 +139,18 @@ const envDef = defineEnv({
 		dockerKeepFailed: "KICI_DOCKER_KEEP_FAILED",
 		jobHeartbeatIntervalMs: "KICI_JOB_HEARTBEAT_INTERVAL_MS",
 		backpressureMode: "KICI_BACKPRESSURE_MODE",
+		agentPayloadDir: "KICI_AGENT_PAYLOAD_DIR",
+		agentCommand: "KICI_AGENT_COMMAND",
 		sandbox: "KICI_SANDBOX",
 		trustedEnv: "KICI_TRUSTED_ENV",
 		inPlace: "KICI_IN_PLACE",
 		sandboxNetwork: "KICI_SANDBOX_NETWORK",
+		sandboxHardened: "KICI_SANDBOX_HARDENED",
+		sandboxReadonlyRootfs: "KICI_SANDBOX_READONLY_ROOTFS",
+		sandboxUser: "KICI_SANDBOX_USER",
+		sandboxPidsLimit: "KICI_SANDBOX_PIDS_LIMIT",
+		sandboxMemoryBytes: "KICI_SANDBOX_MEMORY_BYTES",
+		sandboxNanoCpus: "KICI_SANDBOX_NANO_CPUS",
 		scalerManaged: "KICI_SCALER_MANAGED",
 		scalerIdleTimeoutMs: "KICI_SCALER_IDLE_TIMEOUT",
 		scalerPendingDispatchTimeoutMs: "KICI_SCALER_PENDING_DISPATCH_TIMEOUT",
@@ -162,7 +180,13 @@ const envDef = defineEnv({
 * - KICI_SANDBOX (default: false) — enable bubblewrap (bwrap) namespace isolation for bare-metal execution
 * - KICI_TRUSTED_ENV (default: false) — trusted fleet-agent profile: pass the ambient host env (minus the agent's own KiCI identity secrets) through to steps
 * - KICI_IN_PLACE (default: false) — in-place no-clone profile: for a file:// source, use the real repo path as workDir and skip the clone (the routed deploy:stg profile)
-* - KICI_SANDBOX_NETWORK (default: isolated, options: isolated | host) — when sandbox=true, controls bwrap network namespace
+* - KICI_SANDBOX_NETWORK (default: isolated, options: isolated | host) — sandbox network posture for BOTH backends: the bwrap network namespace (when sandbox=true) and the container job network. `host` shares the host network (container backend also binds host /etc/hosts read-only for name resolution); applies to the container backend under the default hardened posture (KICI_SANDBOX_HARDENED=true)
+* - KICI_SANDBOX_HARDENED (default: true) — hardened-by-default job containers (CapDrop ALL, no-new-privileges, cgroup caps, tmpfs /tmp); set false to roll back to the legacy unhardened posture
+* - KICI_SANDBOX_READONLY_ROOTFS (default: false) — opt-in read-only container rootfs (/tmp stays a writable tmpfs)
+* - KICI_SANDBOX_USER (optional) — container user override (uid, uid:gid, or name); honors the image user when unset
+* - KICI_SANDBOX_PIDS_LIMIT (default: 512) — max PIDs in the job container cgroup
+* - KICI_SANDBOX_MEMORY_BYTES (default: 2 GiB) — memory cap in bytes for the job container cgroup
+* - KICI_SANDBOX_NANO_CPUS (default: 2 CPUs) — CPU cap in nano-CPUs for the job container cgroup
 * - KICI_SCALER_MANAGED (set to "1" by the orchestrator's auto-scaler — agent self-shuts down on idle)
 * - KICI_SCALER_IDLE_TIMEOUT (ms, default 5000) — how long a scaler-managed agent waits before shutdown after going idle
 * - KICI_SCALER_PENDING_DISPATCH_TIMEOUT (ms, default 60000) — extended idle window when register.ack signals a queued bound job
@@ -171,7 +195,7 @@ const envDef = defineEnv({
 */
 function loadConfig() {
 	const data = envDef.parse();
-	if (!data.scalerManaged) validateNoReservedLabels(data.labels, "KICI_LABELS");
+	if (!data.scalerManaged && !data.agentToken) validateNoReservedLabels(data.labels, "KICI_LABELS");
 	validateUnknownKiciVars([...envDef.listKnownEnvVars(), ...LOGGER_ENV_VARS]);
 	return {
 		...data,
@@ -302,6 +326,22 @@ var LogBuffer = class extends RingBuffer {
 //#region src/ws/orchestrator-client.ts
 const logger$12 = createLogger({ prefix: "orchestrator-client" });
 /**
+* How long to wait for `artifacts.upload.complete.ack` before failing the step.
+*
+* Deliberately shorter than the sandbox's own 30s artifact-request timeout
+* (`CACHE_RESPONSE_TIMEOUT_MS` in the workflow runner) so a lost ack surfaces
+* this specific reason rather than the sandbox's generic "artifact request
+* timed out". The orchestrator's bounded commit retry finishes in well under a
+* second, so the margin costs nothing.
+*/
+const ARTIFACT_COMPLETE_ACK_TIMEOUT_MS = 25e3;
+/**
+* Tail shared by both give-up messages for an unacknowledged commit. The
+* operator must not be sent hunting for a lost artifact that in fact landed:
+* the orchestrator may well have committed it and only the ack was lost.
+*/
+const COMMIT_MAY_HAVE_LANDED = "the artifact may have been committed";
+/**
 * WebSocket client that connects the agent to the customer orchestrator.
 *
 * Handles:
@@ -323,6 +363,13 @@ var OrchestratorClient = class OrchestratorClient {
 	reconnectTimer = null;
 	reconnectAttempts = 0;
 	intentionalDisconnect = false;
+	/**
+	* Agent-facing capabilities advertised by the orchestrator on `register.ack`.
+	* Undefined until the first ack arrives, and on a pre-capability orchestrator
+	* that never advertises — both cases mean "assume unsupported" for every
+	* optional feature gated on it.
+	*/
+	orchCapabilities;
 	pendingLogBatch = [];
 	logFlushTimer = null;
 	static LOG_BATCH_SIZE = 50;
@@ -335,6 +382,26 @@ var OrchestratorClient = class OrchestratorClient {
 	pendingApiRequests = /* @__PURE__ */ new Map();
 	/** Pending user-cache restore/save requests awaiting orchestrator response. */
 	pendingUserCacheRequests = /* @__PURE__ */ new Map();
+	/** Pending user-artifact upload/download requests awaiting orchestrator response. */
+	pendingUserArtifactRequests = /* @__PURE__ */ new Map();
+	/**
+	* In-flight `artifacts.upload.complete` frames that are safe to re-send after a
+	* reconnect, keyed by their current `messageId`.
+	*
+	* The commit is idempotent server-side (the storage key is derived server-side,
+	* `initMeta` is a re-writable sidecar, and the DB insert is
+	* `onConflict.doNothing()`), so a dropped ack means "we did not hear the
+	* answer", not "it did not happen". `beginUpload` / `download` are deliberately
+	* absent: `beginUpload` mints a presigned PUT and is not idempotent the same
+	* way, and `download` is read-only and cheap to fail.
+	*/
+	resendableCompletes = /* @__PURE__ */ new Map();
+	/**
+	* Completes taken off `pendingUserArtifactRequests` by the disconnect sweep and
+	* parked until the next `register.ack` re-sends them. Their ack timers keep
+	* running — parking does not extend the deadline.
+	*/
+	heldCompletes = /* @__PURE__ */ new Set();
 	/**
 	* Pending step-approval requests awaiting the orchestrator's resolution.
 	* No client-side timeout: the orchestrator owns the (org-/SDK-configured)
@@ -430,6 +497,7 @@ var OrchestratorClient = class OrchestratorClient {
 		this.intentionalDisconnect = true;
 		this.stopHeartbeat();
 		this.cancelReconnect();
+		this.rejectHeldCompletes("the agent disconnected");
 		this.drainPendingLogBatch();
 		if (this.ws) {
 			this.ws.close(1e3, "Agent disconnect");
@@ -721,6 +789,105 @@ var OrchestratorClient = class OrchestratorClient {
 		});
 	}
 	/**
+	* Relay a user-facing artifact request from the sandbox to the orchestrator.
+	*
+	* Translates the sandbox `artifacts.request` IPC into the matching
+	* `artifacts.*` WS message and resolves with the orchestrator's response
+	* mapped onto the IPC response shape:
+	*
+	* - `beginUpload` -> `artifacts.upload.request`, awaits `artifacts.upload.response`.
+	* - `completeUpload` -> `artifacts.upload.complete`, awaits
+	*   `artifacts.upload.complete.ack` when the orchestrator advertises the
+	*   `artifactCompleteAck` capability, and rejects when the commit failed so
+	*   the workflow step fails instead of losing the artifact behind a green run.
+	*   Against an orchestrator that never advertises it, the message stays
+	*   fire-and-forget and resolves immediately.
+	* - `download` -> `artifacts.download.request`, awaits `artifacts.download.response`.
+	*
+	* Times out after 30 seconds for the round-trip ops.
+	*/
+	async requestUserArtifact(jobId, request) {
+		if (request.op === "completeUpload") {
+			const completeId = randomUUID();
+			const complete = {
+				type: "artifacts.upload.complete",
+				messageId: completeId,
+				jobId,
+				name: request.name,
+				sizeBytes: request.sizeBytes,
+				sha256: request.sha256,
+				storageKey: request.storageKey
+			};
+			if (!hasOrchAgentCapability(this.orchCapabilities, "artifactCompleteAck")) {
+				this.sendDirect(complete);
+				return {
+					type: "artifacts.response",
+					requestId: request.requestId
+				};
+			}
+			return new Promise((resolve, reject) => {
+				const record = {
+					messageId: completeId,
+					frame: complete,
+					attempts: 0,
+					pending: {
+						resolve: () => {
+							clearTimeout(timer);
+							resolve({
+								type: "artifacts.response",
+								requestId: request.requestId
+							});
+						},
+						reject: (err) => {
+							clearTimeout(timer);
+							reject(err);
+						}
+					}
+				};
+				const timer = setTimeout(() => {
+					this.forgetComplete(record);
+					reject(/* @__PURE__ */ new Error(`Artifact upload-complete ack timed out (${ARTIFACT_COMPLETE_ACK_TIMEOUT_MS}ms)`));
+				}, ARTIFACT_COMPLETE_ACK_TIMEOUT_MS);
+				this.pendingUserArtifactRequests.set(completeId, record.pending);
+				this.resendableCompletes.set(completeId, record);
+				this.sendDirect(complete);
+			});
+		}
+		const messageId = randomUUID();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pendingUserArtifactRequests.delete(messageId);
+				reject(/* @__PURE__ */ new Error("User-artifact request timed out (30s)"));
+			}, 3e4);
+			this.pendingUserArtifactRequests.set(messageId, {
+				resolve: (response) => {
+					clearTimeout(timer);
+					resolve({
+						...response,
+						requestId: request.requestId
+					});
+				},
+				reject: (err) => {
+					clearTimeout(timer);
+					reject(err);
+				}
+			});
+			if (request.op === "beginUpload") this.sendDirect({
+				type: "artifacts.upload.request",
+				messageId,
+				jobId,
+				name: request.name,
+				declaredSizeBytes: request.declaredSizeBytes
+			});
+			else this.sendDirect({
+				type: "artifacts.download.request",
+				messageId,
+				jobId,
+				name: request.name
+			});
+		});
+	}
+	/**
 	* Relay a provenance bundle upload operation to the orchestrator. Maps the
 	* IPC `provenance.request` onto `requestProvenanceUploadUrl` (returns the
 	* presigned URL) or `sendProvenanceUploadComplete` (fire-and-forget) and
@@ -935,6 +1102,17 @@ var OrchestratorClient = class OrchestratorClient {
 			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.pendingUserArtifactRequests) {
+				const record = this.resendableCompletes.get(id);
+				if (record && !this.intentionalDisconnect) {
+					this.heldCompletes.add(record);
+					continue;
+				}
+				pending.reject(/* @__PURE__ */ new Error("WebSocket disconnected"));
+			}
+			this.pendingUserArtifactRequests.clear();
+			this.resendableCompletes.clear();
+			if (this.intentionalDisconnect) this.rejectHeldCompletes("the agent disconnected");
 			for (const [_id, pending] of this.pendingConcurrencyRequests) pending.reject(/* @__PURE__ */ new Error("WebSocket disconnected"));
 			this.pendingConcurrencyRequests.clear();
 			for (const [_id, pending] of this.pendingStepApprovals) pending.reject(/* @__PURE__ */ new Error("WebSocket disconnected"));
@@ -946,6 +1124,132 @@ var OrchestratorClient = class OrchestratorClient {
 			if (this.ws && this.ws.readyState === WebSocket.OPEN) this.ws.close();
 		});
 	}
+	/**
+	* Resolve a pending user-artifact request from an `artifacts.upload.response`
+	* / `artifacts.download.response` WS message, mapping the wire fields onto the
+	* IPC response shape. No-op when no request is pending for the requestId.
+	*/
+	resolveArtifactResponse(type, raw) {
+		const artMsg = raw;
+		const pending = this.pendingUserArtifactRequests.get(artMsg.requestId);
+		if (!pending) return;
+		this.pendingUserArtifactRequests.delete(artMsg.requestId);
+		const isUpload = type === "artifacts.upload.response";
+		pending.resolve({
+			type: "artifacts.response",
+			requestId: artMsg.requestId,
+			...isUpload && artMsg.outcome !== void 0 && { uploadOutcome: artMsg.outcome },
+			...!isUpload && artMsg.outcome !== void 0 && { downloadOutcome: artMsg.outcome },
+			...artMsg.uploadUrl && { uploadUrl: artMsg.uploadUrl },
+			...artMsg.storageKey && { storageKey: artMsg.storageKey },
+			...artMsg.reason && { reason: artMsg.reason },
+			...artMsg.error && { rejectionDetail: artMsg.error },
+			...artMsg.downloadUrl && { downloadUrl: artMsg.downloadUrl },
+			...artMsg.sizeBytes !== void 0 && { sizeBytes: artMsg.sizeBytes },
+			...artMsg.sha256 && { sha256: artMsg.sha256 }
+		});
+	}
+	/**
+	* Resolve or reject a pending completeUpload from an
+	* `artifacts.upload.complete.ack`. `committed` resolves the relayed IPC
+	* request; `failed` rejects it (carrying the orchestrator's reason), which
+	* propagates through the relay's `response.error` and fails the workflow step
+	* rather than losing the artifact silently. No-op when nothing is pending for
+	* the requestId (an ack for an already-timed-out complete).
+	*/
+	resolveArtifactCompleteAck(raw) {
+		const ack = raw;
+		const pending = this.pendingUserArtifactRequests.get(ack.requestId);
+		if (!pending) return;
+		this.pendingUserArtifactRequests.delete(ack.requestId);
+		this.resendableCompletes.delete(ack.requestId);
+		if (ack.outcome === ArtifactCompleteAckOutcome.enum.committed) pending.resolve({
+			type: "artifacts.response",
+			requestId: ack.requestId
+		});
+		else pending.reject(new Error(ack.reason ?? "artifact upload-complete failed"));
+	}
+	/**
+	* Drop every trace of an in-flight upload-complete, whichever key it currently
+	* lives under and whether or not it is parked awaiting a resend.
+	*
+	* Called from the ack timer, which fires on the original schedule regardless of
+	* how many times the complete has been re-keyed since.
+	*/
+	forgetComplete(record) {
+		this.pendingUserArtifactRequests.delete(record.messageId);
+		this.resendableCompletes.delete(record.messageId);
+		this.heldCompletes.delete(record);
+	}
+	/**
+	* Fail every parked upload-complete closed, for the paths where the reconnect
+	* the park was betting on will never arrive (a deliberate shutdown, a
+	* permanently rejected token). Naming the ambiguity keeps the operator from
+	* hunting for an artifact that in fact landed.
+	*/
+	rejectHeldCompletes(cause) {
+		if (this.heldCompletes.size === 0) return;
+		const held = [...this.heldCompletes];
+		this.heldCompletes.clear();
+		for (const record of held) record.pending.reject(/* @__PURE__ */ new Error(`artifact upload-complete could not be acknowledged before ${cause} — the artifact may have been committed`));
+	}
+	/**
+	* Re-send every upload-complete parked by the disconnect sweep.
+	*
+	* Called from `register.ack`, once the new connection's capabilities are known.
+	* Each frame is re-keyed with a fresh `messageId` before it goes out: the id is
+	* the correlation key, so reusing it would let a late ack for the pre-disconnect
+	* send resolve the new pending.
+	*
+	* The ack timer created when the complete was first sent is deliberately left
+	* alone, so the hold plus every resend stays inside the original
+	* ARTIFACT_COMPLETE_ACK_TIMEOUT_MS budget.
+	*/
+	resendHeldCompletes() {
+		if (this.heldCompletes.size === 0) return;
+		const held = [...this.heldCompletes];
+		this.heldCompletes.clear();
+		const canAck = hasOrchAgentCapability(this.orchCapabilities, "artifactCompleteAck");
+		for (const record of held) {
+			if (!canAck) {
+				record.pending.reject(/* @__PURE__ */ new Error(`artifact upload-complete cannot be acknowledged by the reconnected orchestrator — ${COMMIT_MAY_HAVE_LANDED}`));
+				continue;
+			}
+			if (record.attempts >= 2) {
+				record.pending.reject(/* @__PURE__ */ new Error(`artifact upload-complete could not be acknowledged after 2 reconnects — ${COMMIT_MAY_HAVE_LANDED}`));
+				continue;
+			}
+			record.messageId = randomUUID();
+			record.attempts += 1;
+			record.frame = {
+				...record.frame,
+				messageId: record.messageId
+			};
+			this.pendingUserArtifactRequests.set(record.messageId, record.pending);
+			this.resendableCompletes.set(record.messageId, record);
+			this.sendDirect(record.frame);
+			logger$12.info("Re-sent artifact upload-complete after reconnect", {
+				messageId: record.messageId,
+				attempt: record.attempts
+			});
+		}
+	}
+	/**
+	* Route the orchestrator's replies to a relayed user-artifact request, which
+	* are dispatched off the raw frame rather than the parsed protocol union.
+	* Returns true when the message was consumed.
+	*/
+	handleArtifactReply(type, raw) {
+		if (type === "artifacts.upload.response" || type === "artifacts.download.response") {
+			this.resolveArtifactResponse(type, raw);
+			return true;
+		}
+		if (type === "artifacts.upload.complete.ack") {
+			this.resolveArtifactCompleteAck(raw);
+			return true;
+		}
+		return false;
+	}
 	handleMessage(data) {
 		let raw;
 		try {
@@ -1003,6 +1307,7 @@ var OrchestratorClient = class OrchestratorClient {
 			}
 			return;
 		}
+		if (this.handleArtifactReply(rawMsg.type, raw)) return;
 		const parsed = orchestratorToAgentMessageSchema.safeParse(raw);
 		if (parsed.success) {
 			const msg = parsed.data;
@@ -1031,10 +1336,12 @@ var OrchestratorClient = class OrchestratorClient {
 						scalerManaged: msg.scalerManaged,
 						pendingDispatch: msg.pendingDispatch ?? false
 					});
+					this.orchCapabilities = msg.capabilities;
 					this._state = "registered";
 					this.reconnectAttempts = 0;
 					this.startHeartbeat();
 					this.flushBuffer();
+					this.resendHeldCompletes();
 					this.onRegistered?.({ pendingDispatch: msg.pendingDispatch ?? false });
 					if (msg.scalerManaged || this.scalerManaged) this.blockMmdsAccess();
 					this.sendConfigAck(msg.agentId);
@@ -1348,14 +1655,14 @@ var init_console_capture = __esmMin((() => {
 init_console_capture();
 function safe(name, fallback = "unknown") {
 	switch (name) {
-		case "version": return "0.1.27";
-		case "buildCommit": return "f0747470b";
-		case "sdkVersion": return "0.1.27";
-		case "sdkBundleHash": return "e06bd1acf349ba365bdb357f3d865e0cbb4ad4604a0270b707a681a4f440954e";
-		case "sharedVersion": return "0.1.27";
-		case "sharedBundleHash": return "f8e1f0117cf41fca5a74377633e2ec89e54ce4eda47d9f476cdb83336f1ed962";
-		case "engineVersion": return "0.1.27";
-		case "engineBundleHash": return "ce675fb4790406ed2a938f8f1783db37b283cffd7d8fc1eb12a878e0bfb919b3";
+		case "version": return "0.2.0";
+		case "buildCommit": return "15d5e4447";
+		case "sdkVersion": return "0.2.0";
+		case "sdkBundleHash": return "fcd0a836aa1cb92debd93e0254450614d123b3748511aa4148d956fd72a7c29f";
+		case "sharedVersion": return "0.2.0";
+		case "sharedBundleHash": return "f16fa528a8a9ef1bed8df369f0e88efafca8a9954a749005299fdbcdb93fa188";
+		case "engineVersion": return "0.2.0";
+		case "engineBundleHash": return "c579e54f7d0b0d5b16587a0528a3e66d32f63e2434bb471a93a01366296efd58";
 		default: return fallback;
 	}
 }
@@ -1406,15 +1713,6 @@ function createHealthRoutes$1(deps) {
 * The orchestrator aggregates these metrics from all agents and exposes
 * them on its `/metrics` endpoint for Prometheus scraping.
 */
-/**
-* OTel DataPointType enum values (from @opentelemetry/sdk-metrics).
-* We duplicate them here to avoid a direct runtime dependency on sdk-metrics.
-*/
-const DataPointType = {
-	HISTOGRAM: 0,
-	GAUGE: 2,
-	SUM: 3
-};
 var MetricsReporter = class {
 	timer;
 	agentId;
@@ -1462,7 +1760,7 @@ var MetricsReporter = class {
 			const wireType = this.mapDataPointType(metricData.dataPointType, metricData.isMonotonic);
 			for (const dp of metricData.dataPoints) {
 				const labels = this.extractLabels(dp.attributes);
-				if (metricData.dataPointType === DataPointType.HISTOGRAM) {
+				if (metricData.dataPointType === OTEL_DATA_POINT_TYPE.HISTOGRAM) {
 					const histValue = dp.value;
 					const boundaries = histValue.buckets.boundaries;
 					const counts = histValue.buckets.counts;
@@ -1495,12 +1793,7 @@ var MetricsReporter = class {
 	}
 	/** Map OTel DataPointType to wire format type string. */
 	mapDataPointType(dataPointType, isMonotonic) {
-		switch (dataPointType) {
-			case DataPointType.HISTOGRAM: return "histogram";
-			case DataPointType.GAUGE: return "gauge";
-			case DataPointType.SUM: return isMonotonic === false ? "upDownCounter" : "counter";
-			default: return "gauge";
-		}
+		return mapDataPointTypeToWireKind(dataPointType, isMonotonic);
 	}
 	/** Extract string labels from OTel Attributes. */
 	extractLabels(attributes) {
@@ -1581,28 +1874,57 @@ 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.
+* Bare job workdirs (`kici-<6 random chars>`, see job-runner.ts), labeled
+* allocator dirs (`kici-<label>-<6 random chars>`, minted by the global temp
+* allocator `@kici-dev/core/tmp`, which guarantees every allocation carries
+* the `kici-` prefix), 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.
+*
+* The deterministic persistent caches (`kici-agent-payloads`, `kici-data`,
+* `kici-scaler-ledger`) also live directly under the temp root and can be far
+* older than a day, so they are explicitly excluded — `kici-scaler-ledger`
+* even structurally matches the allocator pattern (`ledger` is a 6-char label
+* suffix), which a regex alone cannot distinguish.
 */
 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}$/;
+/**
+* Bare `kici-<6 chars>` workdirs and labeled `kici-<label>-<6 chars>`
+* allocator dirs. The optional label group makes both families eligible.
+*/
+const AGENT_WORKDIR_PATTERN = /^kici-([a-z0-9-]+-)?[A-Za-z0-9]{6}$/;
 const PNPM_STORE_PATTERN = /^kici-pnpm-store-/;
 /**
+* Deterministic persistent caches that share the `kici-` prefix but must
+* never be collected — `kici-scaler-ledger` even matches the allocator
+* pattern, so a basename exclude (not a regex) is the only correct guard.
+*/
+const PERSISTENT_CACHES = /* @__PURE__ */ new Set([
+	"kici-agent-payloads",
+	"kici-data",
+	"kici-scaler-ledger"
+]);
+/**
 * Collect this agent's stale temp dirs. `base` is overridable for tests;
 * production callers use the default temp root. Never throws.
+*
+* The default base is `kiciTmpBase()`, not the OS temp root, so it scans the
+* exact directory the agent now writes payloads/clones/pnpm stores into: the
+* global temp allocator and the payload cache both honor `KICI_TMPDIR` via the
+* same helper. If the GC scanned a different root, stale-temp reaping would
+* silently stop working whenever `KICI_TMPDIR` is set.
 */
-async function gcStaleAgentTmpDirs(base = tmpdir()) {
+async function gcStaleAgentTmpDirs(base = kiciTmpBase()) {
 	const log = (m) => logger.info(m);
 	return [...await gcStaleTmpDirs({
 		base,
 		pattern: AGENT_WORKDIR_PATTERN,
 		maxAgeMs: AGENT_TMP_GC_MAX_AGE_MS,
+		exclude: PERSISTENT_CACHES,
 		log
 	}), ...await gcStaleTmpDirs({
 		base,
@@ -1758,7 +2080,7 @@ var init_prometheus = __esmMin((() => {
 */
 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 { path: tempDir, cleanup } = await makeTempDir("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");
@@ -1779,12 +2101,7 @@ async function setupSshAuth(opts) {
 	return {
 		gitSshCommand: parts.join(" "),
 		tempDir,
-		async cleanup() {
-			await rm(tempDir, {
-				recursive: true,
-				force: true
-			});
-		}
+		cleanup
 	};
 }
 /**
@@ -1836,19 +2153,16 @@ async function gitClone(options) {
 	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 { writeFile } = await import("node:fs/promises");
 		const path = await import("node:path");
-		const dir = await mkdtemp(path.join(tmpdir(), "kici-gitcfg-"));
+		const { makeTempDir } = await import("@kici-dev/core/tmp");
+		const { path: dir, cleanup } = await makeTempDir("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(() => {});
+			await cleanup().catch(() => {});
 		};
 	}
 	let sshSetup;
@@ -1961,11 +2275,46 @@ var workflow_loader_exports = /* @__PURE__ */ __exportAll({
 	extractSteps: () => extractSteps,
 	extractStepsFromDynamicJob: () => extractStepsFromDynamicJob,
 	extractWorkflow: () => extractWorkflow,
-	loadWorkflowSource: () => loadWorkflowSource
+	loadWorkflowSource: () => loadWorkflowSource,
+	resolveWorkflowSdkSetters: () => resolveWorkflowSdkSetters
 });
+/**
+* Resolve the `@kici-dev/sdk` instance the workflow module itself imports.
+*
+* The workflow's `.result` proxies read the module-global step-outputs map of
+* whichever SDK copy the workflow file resolves — which is generally a
+* different physical module than the agent's bundled SDK (the workflow is
+* imported from the cloned source tree and resolves its deps against that
+* tree's `node_modules`). Resolving via `createRequire(workflowFilePath)` walks
+* `node_modules` from the workflow file exactly the way the workflow's own
+* `import '@kici-dev/sdk'` does — including any hoisted copy — so the returned
+* setters mutate the SAME module-global map object the proxies read. Node caches
+* ESM modules by resolved URL, so importing that path yields the workflow's live
+* singleton, not a fresh copy.
+*
+* Falls back to the agent's bundled setters when resolution fails (mirrors
+* `resolveSdkSetters` in the compiler's test runner).
+*/
+async function resolveWorkflowSdkSetters(workflowFilePath) {
+	try {
+		const sdk = await import(pathToFileURL(createRequire(workflowFilePath).resolve("@kici-dev/sdk")).href);
+		if (typeof sdk.setStepOutputsMap === "function" && typeof sdk.setStepRefMap === "function" && typeof sdk.setJobOutputsMap === "function") return {
+			setStepOutputsMap: sdk.setStepOutputsMap,
+			setStepRefMap: sdk.setStepRefMap,
+			setJobOutputsMap: sdk.setJobOutputsMap
+		};
+	} catch {}
+	return {
+		setStepOutputsMap,
+		setStepRefMap,
+		setJobOutputsMap
+	};
+}
 function ensureLoaderHookRegistered() {
 	if (hookRegistered) return;
-	register("@kici-dev/core/ts-loader-hook", import.meta.url);
+	const hookPath = process.env.KICI_TS_LOADER_HOOK_PATH;
+	if (hookPath) register(pathToFileURL(hookPath).href, import.meta.url);
+	else register("@kici-dev/core/ts-loader-hook", import.meta.url);
 	hookRegistered = true;
 }
 /**
@@ -2020,7 +2369,10 @@ async function loadWorkflowSource(workDir, sourceFile, expectedContentHash, reso
 		const actualHash = computeContentHash(rawSource, assetDigest);
 		if (actualHash !== expectedContentHash) throw new Error(`Lock file is out of date: workflow source changed without regenerating kici.lock.json (expected contentHash ${expectedContentHash}, got ${actualHash}, agent baked @kici-dev/sdk@${AGENT_SDK_VERSION} bundleHash=${AGENT_SDK_BUNDLE_HASH}). Run 'kici compile' and commit the updated lock file.`);
 	}
-	return { module: await import(pathToFileURL(filePath).href + `?t=${Date.now()}`) };
+	return {
+		module: await import(pathToFileURL(filePath).href + `?t=${Date.now()}`),
+		sdkSetters: await resolveWorkflowSdkSetters(filePath)
+	};
 }
 /**
 * Type guard for Workflow shape (discriminant: `_tag === 'Workflow'`).
@@ -2118,8 +2470,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.27";
-	AGENT_SDK_BUNDLE_HASH = "e06bd1acf349ba365bdb357f3d865e0cbb4ad4604a0270b707a681a4f440954e";
+	AGENT_SDK_VERSION = "0.2.0";
+	AGENT_SDK_BUNDLE_HASH = "fcd0a836aa1cb92debd93e0254450614d123b3748511aa4148d956fd72a7c29f";
 	hookRegistered = false;
 }));
 //#endregion
@@ -2582,7 +2934,16 @@ async function evaluateDynamicFields(workflow, jobName, event, flags, timeoutMs
 			},
 			env: { ...process.env }
 		};
-		let combos = expandMatrix(await withTimeout(() => job.matrix(matrixContext), timeoutMs, `dynamicMatrix for job '${jobName}'`));
+		const resolved = await withTimeout(() => job.matrix(matrixContext), timeoutMs, `dynamicMatrix for job '${jobName}'`);
+		let combos;
+		try {
+			const rawCount = matrixCombinationCount(resolved);
+			if (rawCount > MAX_MATRIX_MATERIALIZATION) throw new MatrixShapeError(`matrix is too large to expand: ${rawCount} raw combinations (max ${MAX_MATRIX_MATERIALIZATION})`);
+			combos = expandMatrix(resolved);
+		} catch (err) {
+			if (err instanceof MatrixShapeError) throw new MatrixShapeError(`dynamicMatrix for job '${jobName}': ${err.message}`);
+			throw err;
+		}
 		if (job.include || job.exclude) combos = applyIncludeExclude(combos, job.include, job.exclude);
 		result.matrixValues = combos;
 	}
@@ -2665,13 +3026,14 @@ async function sshExec(reach, privateKey, command, opts = {}, deps = {}) {
 	const hostKeyMode = opts.hostKeyMode ?? "accept-new";
 	const { dest, port } = resolveTarget(reach, opts.port);
 	return withEphemeralAgent(privateKey, spawnFn, async (env) => {
-		return spawnFn("ssh", [
+		const args = [
 			...baseSshOptions(hostKeyMode),
 			"-p",
 			String(port),
 			dest,
 			command
-		], {
+		];
+		return spawnFn("ssh", args, {
 			env,
 			stdin: opts.stdin
 		});
@@ -2687,13 +3049,14 @@ async function sshPush(reach, privateKey, localBytes, remotePath, opts = {}, dep
 	const hostKeyMode = opts.hostKeyMode ?? "accept-new";
 	const { dest, port } = resolveTarget(reach, opts.port);
 	const result = await withEphemeralAgent(privateKey, spawnFn, async (env) => {
-		return spawnFn("ssh", [
+		const args = [
 			...baseSshOptions(hostKeyMode),
 			"-p",
 			String(port),
 			dest,
 			`cat > '${remotePath.replace(/'/g, `'\\''`)}'`
-		], {
+		];
+		return spawnFn("ssh", args, {
 			env,
 			stdin: localBytes
 		});
@@ -2701,6 +3064,32 @@ async function sshPush(reach, privateKey, localBytes, remotePath, opts = {}, dep
 	if (result.exitCode !== 0) throw new Error(`sshPush(${reach.agentId}:${remotePath}): exit ${result.exitCode}${result.stderr ? `\n${result.stderr}` : ""}`);
 }
 /**
+* Ship a local FILE to a remote path over `scp` (a binary channel), using the
+* same ephemeral-key discipline as `sshExec`/`sshPush`.
+*
+* Unlike `sshPush` — which pipes a JS string through `ssh 'cat > path'` and so
+* corrupts binary payloads (a ~50 MB tarball) — `scp` streams the file's raw
+* bytes untouched. This is the ONLY sanctioned path for a binary payload
+* transfer; the string `cat >` path is for text (launcher scripts) only. Throws
+* on a non-zero exit (a payload push must succeed end-to-end).
+*/
+async function sshPushFile(reach, privateKey, localFilePath, remotePath, opts = {}, deps = {}) {
+	const spawnFn = deps.spawnFn ?? defaultSpawn;
+	const hostKeyMode = opts.hostKeyMode ?? "accept-new";
+	const { dest, port } = resolveTarget(reach, opts.port);
+	const result = await withEphemeralAgent(privateKey, spawnFn, async (env) => {
+		const args = [
+			...baseSshOptions(hostKeyMode),
+			"-P",
+			String(port),
+			localFilePath,
+			`${dest}:${remotePath}`
+		];
+		return spawnFn("scp", args, { env });
+	});
+	if (result.exitCode !== 0) throw new Error(`sshPushFile(${reach.agentId}:${remotePath}): exit ${result.exitCode}${result.stderr ? `\n${result.stderr}` : ""}`);
+}
+/**
 * Start a per-call ephemeral ssh-agent, load the key via stdin (never a file),
 * run `body` with `SSH_AUTH_SOCK` in env, and kill the agent in `finally`.
 *
@@ -2716,7 +3105,7 @@ async function sshPush(reach, privateKey, localBytes, remotePath, opts = {}, dep
 */
 async function withEphemeralAgent(privateKey, spawnFn, body) {
 	const baseEnv = { ...process.env };
-	const agentDir = await mkdtemp(join(tmpdir(), "kici-bootstrap-ssh-"));
+	const { path: agentDir, cleanup } = await makeTempDir("bootstrap-ssh");
 	const sock = join(agentDir, "agent.sock");
 	try {
 		const start = await spawnFn("ssh-agent", [
@@ -2729,10 +3118,11 @@ async function withEphemeralAgent(privateKey, spawnFn, body) {
 		const agentEnv = {
 			...baseEnv,
 			SSH_AUTH_SOCK: sock,
-			...pid ? { SSH_AGENT_PID: pid } : {},
 			SSH_ASKPASS: "/bin/false",
 			DISPLAY: ""
 		};
+		if (pid) agentEnv.SSH_AGENT_PID = pid;
+		else delete agentEnv.SSH_AGENT_PID;
 		try {
 			const add = await spawnFn("ssh-add", ["-"], {
 				env: agentEnv,
@@ -2744,10 +3134,7 @@ async function withEphemeralAgent(privateKey, spawnFn, body) {
 			await spawnFn("ssh-agent", ["-k"], { env: agentEnv }).catch(() => {});
 		}
 	} finally {
-		await rm(agentDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanup().catch(() => {});
 	}
 }
 /** Extract `SSH_AGENT_PID=<n>;` from `ssh-agent -s` output (best-effort). */
@@ -2779,7 +3166,10 @@ var init_ssh_exec = __esmMin((() => {
 			stdout,
 			stderr
 		}));
-		if (opts.stdin !== void 0) child.stdin?.end(opts.stdin);
+		if (opts.stdin !== void 0) {
+			child.stdin?.on("error", () => {});
+			child.stdin?.end(opts.stdin);
+		}
 	});
 	SSH_USER_DEFAULT = "root";
 	SSH_PORT_DEFAULT = 22;
@@ -2789,8 +3179,166 @@ var init_ssh_exec = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region src/bootstrap/probe-platform.ts
+/**
+* Probe a bring-up target's platform over SSH.
+*
+* A stock rescue box has nothing but sshd — no `kici-agent`, no Node — so we
+* cannot ask the box what to run; we must ask what it IS, then stage the
+* matching self-contained payload. One `uname -s -m` (+ a libc check) maps to
+* an `AgentPlatform`; an unsupported target (musl-only, non-Linux, unknown
+* arch) throws early, naming what was detected, rather than staging bytes that
+* won't boot.
+*/
+/**
+* Map `uname -s -m` (+ libc line) output to an `AgentPlatform`. Pure + directly
+* unit-tested. Throws a self-describing error for any unsupported target.
+*/
+function parseUname(stdout) {
+	const lines = stdout.split("\n");
+	const unameLine = (lines[0] ?? "").trim();
+	const libc = lines.slice(1).join("\n").toLowerCase();
+	const [os, arch] = unameLine.split(/\s+/);
+	if (os !== "Linux") throw new Error(`unsupported bring-up target OS "${os}" (uname: "${unameLine}") — Linux only`);
+	if (libc.includes("musl") || libc.includes("ld-musl")) throw new Error(`unsupported bring-up target: musl libc detected (uname: "${unameLine}") — glibc Linux only`);
+	if (arch === "x86_64") return AgentPlatform.enum["linux-x64"];
+	if (arch === "aarch64") return AgentPlatform.enum["linux-arm64"];
+	throw new Error(`unsupported bring-up target arch "${arch}" (uname: "${unameLine}") — x86_64 or aarch64 only`);
+}
+/** SSH into `reach` and detect its `AgentPlatform` (one probe, fail-fast on unsupported). */
+async function probeTargetPlatform(reach, privateKey, deps = {}) {
+	const res = await sshExec(reach, privateKey, PROBE_COMMAND, {}, deps);
+	if (res.exitCode !== 0) throw new Error(`platform probe on ${reach.agentId} failed: exit ${res.exitCode}${res.stderr ? `\n${res.stderr}` : ""}`);
+	return parseUname(res.stdout);
+}
+var PROBE_COMMAND;
+var init_probe_platform = __esmMin((() => {
+	init_ssh_exec();
+	PROBE_COMMAND = "uname -s -m; (ldd --version 2>&1 | head -1) || true";
+}));
+//#endregion
+//#region src/bootstrap/stage-agent-payload.ts
+/**
+* Stage a self-contained agent payload onto a bring-up target.
+*
+* The reusable core mechanism behind fresh-box bring-up: resolve a version-keyed
+* payload from an `AgentPayloadSource`, verify it, deliver it to the box, verify
+* it again ON the box before extracting, and return the launcher path. The
+* launcher boots the agent on its VENDORED Node, so a stock rescue box (no Node)
+* becomes a connected agent.
+*
+* Two delivery modes: `ssh-push` (the ops agent pulls the payload from its
+* source, then streams it to the box over a binary-safe scp) and `s3-direct`
+* (the box pulls a presigned URL itself, so no 50 MB transits the ops agent).
+* Every path is fail-closed: a hash it cannot verify is never extracted.
+*/
+/** Streamed sha256 of a local file (the default ops-agent-side verify). */
+function hashFileSha256(filePath) {
+	return new Promise((resolve, reject) => {
+		const hash = createHash("sha256");
+		createReadStream(filePath).on("error", reject).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve(hash.digest("hex")));
+	});
+}
+/** Single-quote a value for safe embedding in a remote shell command. */
+function shQuote$2(v) {
+	return `'${v.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* Verify the resolved payload on the ops agent BEFORE any transfer. A payload
+* with no sidecar hash is unverifiable and refused (fail-closed); a hash
+* mismatch throws so corrupt/tampered bytes never leave this process.
+*/
+async function verifyLocalPayload(tarballPath, expectedSha256, deps) {
+	if (!expectedSha256) throw new Error(`refusing to stage ${tarballPath}: no sha256 sidecar — cannot verify the payload (run \`kici-admin agent package\` to (re)generate it with a hash)`);
+	const actual = await (deps.hashLocalFile ?? hashFileSha256)(tarballPath);
+	if (actual !== expectedSha256) throw new Error(`payload hash mismatch for ${tarballPath}: expected ${expectedSha256}, got ${actual}`);
+	return expectedSha256;
+}
+/**
+* On the box: verify the pushed tarball's hash, then extract it into
+* `extractDir`. `sha256sum -c` fails the whole `&&` chain if the hash differs,
+* so extraction only ever runs on verified bytes.
+*/
+async function verifyAndExtractRemote(reach, privateKey, sha256, extractDir, deps) {
+	const remoteBase = path.posix.basename(REMOTE_TARBALL_PATH);
+	const res = await sshExec(reach, privateKey, [
+		`cd ${shQuote$2(path.posix.dirname(REMOTE_TARBALL_PATH))}`,
+		`echo ${shQuote$2(`${sha256}  ${remoteBase}`)} | sha256sum -c -`,
+		`mkdir -p ${shQuote$2(extractDir)}`,
+		`tar xzf ${shQuote$2(remoteBase)} -C ${shQuote$2(extractDir)}`
+	].join(" && "), {}, deps);
+	if (res.exitCode !== 0) throw new Error(`on-box verify/extract on ${reach.agentId} failed: exit ${res.exitCode}${res.stderr ? `\n${res.stderr}` : ""}`);
+}
+/** Resolve → verify locally → push → verify+extract on box. */
+async function stageSshPush(reach, privateKey, opts, extractDir, deps) {
+	if (!deps.payloadSource) throw new Error("ssh-push delivery requires a payload source (KICI_AGENT_BINARY_SOURCE / KICI_AGENT_PAYLOAD_DIR)");
+	const staged = await deps.payloadSource.resolve(opts.platform, opts.version);
+	const sha256 = await verifyLocalPayload(staged.tarballPath, staged.sha256, deps);
+	await sshPushFile(reach, privateKey, staged.tarballPath, REMOTE_TARBALL_PATH, {}, deps);
+	await verifyAndExtractRemote(reach, privateKey, sha256, extractDir, deps);
+}
+/**
+* `s3-direct`: the box pulls the presigned URL itself, verifies the sha256, and
+* extracts — all in one `sshExec`, so the 50 MB payload never transits the ops
+* agent. Fail-closed: `sha256sum -c` breaks the `&&` chain on mismatch, so the
+* box only ever extracts verified bytes, and `curl -f` fails the chain on a
+* non-2xx (expired/absent presign).
+*/
+async function stageS3Direct(reach, privateKey, presignedUrl, sha256, extractDir, deps) {
+	const remoteBase = path.posix.basename(REMOTE_TARBALL_PATH);
+	const res = await sshExec(reach, privateKey, [
+		`cd ${shQuote$2(path.posix.dirname(REMOTE_TARBALL_PATH))}`,
+		`curl -fsSL ${shQuote$2(presignedUrl)} -o ${shQuote$2(remoteBase)}`,
+		`echo ${shQuote$2(`${sha256}  ${remoteBase}`)} | sha256sum -c -`,
+		`mkdir -p ${shQuote$2(extractDir)}`,
+		`tar xzf ${shQuote$2(remoteBase)} -C ${shQuote$2(extractDir)}`
+	].join(" && "), {}, deps);
+	if (res.exitCode !== 0) throw new Error(`s3-direct pull/verify/extract on ${reach.agentId} failed: exit ${res.exitCode}${res.stderr ? `\n${res.stderr}` : ""}`);
+}
+/**
+* Stage a payload onto `reach` and return the launcher path the caller runs as
+* the init-runner's `agentCommand`.
+*/
+async function stageAgentPayload(reach, privateKey, opts, deps) {
+	const extractDir = deps.extractDir ?? DEFAULT_EXTRACT_DIR;
+	switch (opts.delivery.mode) {
+		case "ssh-push":
+			await stageSshPush(reach, privateKey, opts, extractDir, deps);
+			break;
+		case "s3-direct":
+			await stageS3Direct(reach, privateKey, opts.delivery.presignedUrl, opts.delivery.sha256, extractDir, deps);
+			break;
+	}
+	return { launcherPath: path.posix.join(extractDir, "kici-agent") };
+}
+var DEFAULT_EXTRACT_DIR, REMOTE_TARBALL_PATH;
+var init_stage_agent_payload = __esmMin((() => {
+	init_ssh_exec();
+	DEFAULT_EXTRACT_DIR = "/opt/kici-init";
+	REMOTE_TARBALL_PATH = "/tmp/kici-agent-payload.tar.gz";
+}));
+//#endregion
 //#region src/bootstrap/ensure-init-runner.ts
 /**
+* Agent-side init-runner bring-up.
+*
+* Runs in the AGENT process (never the workflow sandbox), so the bring-up SSH
+* key and bootstrap token the orchestrator hands back never reach user
+* workflow code. The flow:
+*
+*   1. Call the orchestrator's privileged `kici.ensureInitRunner` handler — it
+*      gates on this agent's `kici:capability:ssh-transport` capability,
+*      resolves the target's reach + SSH key, mints a single-use bootstrap
+*      token, audits, and returns the material (or `{ broughtUp: false }` when
+*      the target already has a live agent).
+*   2. Over SSH (ephemeral key, never on disk): drop a launcher onto the target
+*      that starts `kici-agent` with the bootstrap env (token + agent id +
+*      orchestrator URL + labels), and start it detached.
+*
+* The init-runner then connects → `auth.request` (bootstrap token) →
+* `agent.register` auto-enroll as a temporary `kici:init` agent.
+*/
+/**
 * Build the launcher script that starts the init-runner on the target with its
 * bootstrap env. Detached (`setsid … &`) so the SSH session can return while
 * the agent keeps running and dials the orchestrator.
@@ -2800,10 +3348,11 @@ function buildLauncher(material, agentCommand) {
 		"#!/usr/bin/env bash",
 		"set -euo pipefail",
 		`setsid env ${[
-			`KICI_AGENT_TOKEN=${shQuote(material.bootstrapToken)}`,
-			`KICI_AGENT_ID=${shQuote(material.targetAgentId)}`,
-			`KICI_ORCHESTRATOR_URL=${shQuote(material.orchestratorUrl)}`,
-			`KICI_LABELS=${shQuote(material.labels.join(","))}`,
+			`KICI_AGENT_TOKEN=${shQuote$1(material.bootstrapToken)}`,
+			`KICI_AGENT_ID=${shQuote$1(material.targetAgentId)}`,
+			`KICI_ORCHESTRATOR_URL=${shQuote$1(material.orchestratorUrl)}`,
+			`KICI_LABELS=${shQuote$1(material.labels.join(","))}`,
+			"KICI_ROLES=",
 			"KICI_EXECUTION_MODE=bare-metal",
 			"KICI_PORT=0"
 		].join(" \\\n  ")} \\`,
@@ -2812,10 +3361,60 @@ function buildLauncher(material, agentCommand) {
 	].join("\n");
 }
 /** Single-quote a value for safe embedding in the launcher's env assignment. */
-function shQuote(v) {
+function shQuote$1(v) {
 	return `'${v.replace(/'/g, `'\\''`)}'`;
 }
 /**
+* Resolve the command the launcher invokes to start the init-runner.
+*
+* - A `deps.agentCommand` override short-circuits staging (golden image).
+* - Otherwise a payload source is required: probe the target's platform, stage
+*   the version-keyed self-contained payload over SSH, and return the staged
+*   launcher path (which boots the agent on its vendored Node — no system Node).
+* - No override AND no source is a misconfiguration, not a silent Node
+*   assumption — throw a clear error.
+*/
+async function resolveAgentCommand(transport, reach, privateKey, material, deps) {
+	if (deps.agentCommand) return deps.agentCommand;
+	if (!material.version) throw new Error(`orchestrator returned no version for ${material.targetAgentId} — cannot stage a payload`);
+	if (!(deps.delivery?.mode === AgentDeliveryMode.enum["s3-direct"] || material.deliveryMode === AgentDeliveryMode.enum["s3-direct"]) && !deps.payloadSource) throw new Error(`no agent payload source configured for bringing up ${material.targetAgentId}: set KICI_AGENT_BINARY_SOURCE (object storage), KICI_AGENT_PAYLOAD_DIR (air-gap), or KICI_AGENT_COMMAND (golden image)`);
+	const platform = await probeTargetPlatform(reach, privateKey, deps);
+	const delivery = await resolveDelivery$1(transport, material, platform, deps);
+	const { launcherPath } = await stageAgentPayload(reach, privateKey, {
+		platform,
+		version: material.version,
+		delivery
+	}, {
+		spawnFn: deps.spawnFn,
+		payloadSource: deps.payloadSource,
+		extractDir: deps.extractDir,
+		hashLocalFile: deps.hashLocalFile
+	});
+	return launcherPath;
+}
+/**
+* Decide how the payload reaches the box. An explicit `deps.delivery` override
+* wins (test/escape hatch); otherwise honor the orchestrator's per-host choice.
+* For `s3-direct` we ask the orchestrator (which knows the probed platform now)
+* to mint a box-routable presigned URL via `kici.presignAgentPackage`; a payload
+* with no sha256 is refused (fail-closed — never extract unverifiable bytes).
+*/
+async function resolveDelivery$1(transport, material, platform, deps) {
+	if (deps.delivery) return deps.delivery;
+	if (material.deliveryMode !== AgentDeliveryMode.enum["s3-direct"]) return { mode: "ssh-push" };
+	const presigned = await transport("kici.presignAgentPackage", {
+		targetAgentId: material.targetAgentId,
+		platform
+	});
+	if (!presigned?.url) throw new Error(`orchestrator returned no presigned URL for ${material.targetAgentId}`);
+	if (!presigned.sha256) throw new Error(`refusing s3-direct delivery for ${material.targetAgentId}: no sha256 for the payload (cannot verify on the box)`);
+	return {
+		mode: "s3-direct",
+		presignedUrl: presigned.url,
+		sha256: presigned.sha256
+	};
+}
+/**
 * Bring up a temporary init-runner on `targetAgentId`. Returns `{ broughtUp }`:
 * false when the target already had a live agent (the orchestrator no-op'd),
 * true when this call dropped + started the init-runner.
@@ -2825,7 +3424,7 @@ async function ensureInitRunner(transport, targetAgentId, deps = {}) {
 	if (!material.broughtUp) return { broughtUp: false };
 	const { reach, privateKey, bootstrapToken, orchestratorUrl, labels } = material;
 	if (!reach || !privateKey || !bootstrapToken || !orchestratorUrl || !labels) throw new Error(`orchestrator returned incomplete bring-up material for ${targetAgentId}`);
-	const agentCommand = deps.agentCommand ?? DEFAULT_AGENT_COMMAND;
+	const agentCommand = await resolveAgentCommand(transport, reach, privateKey, material, deps);
 	await sshPush(reach, privateKey, buildLauncher({
 		bootstrapToken,
 		targetAgentId,
@@ -2836,10 +3435,11 @@ async function ensureInitRunner(transport, targetAgentId, deps = {}) {
 	if (run.exitCode !== 0) throw new Error(`init-runner launch on ${targetAgentId} failed: exit ${run.exitCode}${run.stderr ? `\n${run.stderr}` : ""}`);
 	return { broughtUp: true };
 }
-var DEFAULT_AGENT_COMMAND, LAUNCHER_REMOTE_PATH;
+var LAUNCHER_REMOTE_PATH;
 var init_ensure_init_runner = __esmMin((() => {
 	init_ssh_exec();
-	DEFAULT_AGENT_COMMAND = "kici-agent";
+	init_probe_platform();
+	init_stage_agent_payload();
 	LAUNCHER_REMOTE_PATH = "/tmp/kici-init-runner.sh";
 }));
 //#endregion
@@ -2866,6 +3466,141 @@ var init_pre_boot_send = __esmMin((() => {
 	init_ssh_exec();
 }));
 //#endregion
+//#region src/bootstrap/restage-agent.ts
+/**
+* External-actor agent re-stage + restart (fleet auto-upgrade apply).
+*
+* Runs in the OPS agent (the one holding `kici:capability:ssh-transport`) —
+* never on the target host itself, so there is NO self-update-handoff: an
+* external actor swaps the bytes and restarts the target's agent, which
+* reconnects on its OWN persistent token (this function never mints or handles
+* a token). The install is folder-anchored (mirroring the versioned-upgrade
+* layout): the target version is staged into `<installDir>/kici-agent-<version>`
+* and an atomic symlink swap makes it current, so a stage failure aborts BEFORE
+* the swap and never leaves a half-upgraded install. Idempotent — a box already
+* on the target version is a no-op.
+*/
+/** Single-quote a value for safe embedding in a remote shell command. */
+function shQuote(v) {
+	return `'${v.replace(/'/g, `'\\''`)}'`;
+}
+/** The versioned payload directory for a version under the install base. */
+function versionDir(installDir, version) {
+	return path.posix.join(installDir, `kici-agent-${version}`);
+}
+/**
+* Read the version the `kici-agent` symlink currently points at, or null when
+* no install is present. The symlink target is `kici-agent-<version>`.
+*/
+async function readCurrentVersion(reach, privateKey, installDir, deps) {
+	const target = (await sshExec(reach, privateKey, `readlink ${shQuote(path.posix.join(installDir, "kici-agent"))} 2>/dev/null || true`, {}, deps)).stdout.trim();
+	const match = /(?:^|\/)kici-agent-(.+)$/.exec(target);
+	return match ? match[1] : null;
+}
+/**
+* Atomically point `<installDir>/kici-agent` at the target version directory.
+* `ln -sfn` onto a temp name + `mv -T` is a single rename, so a reader never
+* sees a missing symlink. The target is stored relative so the tree is movable.
+*/
+async function swapInstall(reach, privateKey, installDir, version, deps) {
+	const link = path.posix.join(installDir, "kici-agent");
+	const tmp = `${link}.swap`;
+	const res = await sshExec(reach, privateKey, [`ln -sfn ${shQuote(`kici-agent-${version}`)} ${shQuote(tmp)}`, `mv -T ${shQuote(tmp)} ${shQuote(link)}`].join(" && "), {}, deps);
+	if (res.exitCode !== 0) throw new Error(`install swap on ${reach.agentId} failed: exit ${res.exitCode}${res.stderr ? `\n${res.stderr}` : ""}`);
+}
+/** Run the drain (stop) then the restart (start) over SSH. */
+async function drainAndRestart(reach, privateKey, restart, deps) {
+	const stopRes = await sshExec(reach, privateKey, restart.stop, {}, deps);
+	if (stopRes.exitCode !== 0) throw new Error(`agent drain on ${reach.agentId} failed: exit ${stopRes.exitCode}${stopRes.stderr ? `\n${stopRes.stderr}` : ""}`);
+	const startRes = await sshExec(reach, privateKey, restart.start, {}, deps);
+	if (startRes.exitCode !== 0) throw new Error(`agent restart on ${reach.agentId} failed: exit ${startRes.exitCode}${startRes.stderr ? `\n${startRes.stderr}` : ""}`);
+}
+/**
+* Re-stage the target version onto `reach` and restart its agent. Returns
+* `{ restaged: false }` when the host is already on the target version (no
+* stage, no swap, no restart), `{ restaged: true }` when this call swapped it.
+*/
+async function restageAgent(reach, privateKey, opts, deps) {
+	const installDir = opts.installDir ?? DEFAULT_INSTALL_DIR;
+	if (await readCurrentVersion(reach, privateKey, installDir, deps) === opts.version) return { restaged: false };
+	await stageAgentPayload(reach, privateKey, {
+		platform: opts.platform ?? await probeTargetPlatform(reach, privateKey, deps),
+		version: opts.version,
+		delivery: opts.delivery
+	}, {
+		spawnFn: deps.spawnFn,
+		payloadSource: deps.payloadSource,
+		extractDir: versionDir(installDir, opts.version),
+		hashLocalFile: deps.hashLocalFile
+	});
+	await swapInstall(reach, privateKey, installDir, opts.version, deps);
+	await drainAndRestart(reach, privateKey, opts.restart, deps);
+	return { restaged: true };
+}
+var DEFAULT_INSTALL_DIR;
+var init_restage_agent = __esmMin((() => {
+	init_ssh_exec();
+	init_probe_platform();
+	init_stage_agent_payload();
+	DEFAULT_INSTALL_DIR = "/opt/kici-agent";
+}));
+//#endregion
+//#region src/bootstrap/run-restage.ts
+/**
+* Agent-process driver for the `kici.restageAgent` fleet-upgrade apply.
+*
+* Intercepted in the ops agent (like `ensureInitRunner`): the privileged
+* resolve — capability gate, availability gate, reach + SSH key, restart spec —
+* runs on the orchestrator; this driver performs the SSH transport (probe →
+* stage → swap → restart) so the bring-up key never reaches user workflow code.
+* The re-staged permanent agent reconnects on its own persistent credential, so
+* no token is minted or handled here (no self-update-handoff).
+*/
+/**
+* Resolve the delivery mode for the re-stage. `ssh-push` needs a local payload
+* source; `s3-direct` asks the orchestrator to mint a box-routable presigned URL
+* (keyed by the now-probed platform) and refuses a payload with no sha256
+* (fail-closed — never extract unverifiable bytes on the box).
+*/
+async function resolveDelivery(transport, targetAgentId, deliveryMode, platform) {
+	if (deliveryMode !== AgentDeliveryMode.enum["s3-direct"]) return { mode: "ssh-push" };
+	const presigned = await transport("kici.presignAgentPackage", {
+		targetAgentId,
+		platform
+	});
+	if (!presigned?.url) throw new Error(`orchestrator returned no presigned URL for re-staging ${targetAgentId}`);
+	if (!presigned.sha256) throw new Error(`refusing s3-direct re-stage for ${targetAgentId}: no sha256 for the payload (cannot verify on the box)`);
+	return {
+		mode: "s3-direct",
+		presignedUrl: presigned.url,
+		sha256: presigned.sha256
+	};
+}
+/**
+* Drive one external-actor re-stage: fetch the material, probe the target
+* platform, resolve delivery, then stage + swap + restart via {@link restageAgent}.
+* Returns `{ restaged: false }` when the host is already on the target version.
+*/
+async function runRestage(transport, targetAgentId, deps) {
+	const { reach, privateKey, version, deliveryMode, restart } = await transport("kici.restageAgent", { targetAgentId });
+	if (!reach || !privateKey || !version || !restart) throw new Error(`orchestrator returned incomplete re-stage material for ${targetAgentId}`);
+	const platform = await probeTargetPlatform(reach, privateKey, deps);
+	return restageAgent(reach, privateKey, {
+		platform,
+		version,
+		delivery: await resolveDelivery(transport, targetAgentId, deliveryMode, platform),
+		...restart.installDir ? { installDir: restart.installDir } : {},
+		restart: {
+			stop: restart.stop,
+			start: restart.start
+		}
+	}, deps);
+}
+var init_run_restage = __esmMin((() => {
+	init_probe_platform();
+	init_restage_agent();
+}));
+//#endregion
 //#region src/bootstrap/api-intercept.ts
 /**
 * Wrap the orchestrator API transport so the two bootstrap methods are handled
@@ -2884,15 +3619,131 @@ function withBootstrapInterception(relay, deps = {}) {
 			}, deps);
 			return;
 		}
+		if (method === RESTAGE_AGENT) return runRestage(relay, String(params.targetAgentId ?? ""), deps);
 		return relay(method, params);
 	};
 }
-var ENSURE_INIT_RUNNER, PRE_BOOT_SEND;
+var ENSURE_INIT_RUNNER, PRE_BOOT_SEND, RESTAGE_AGENT;
 var init_api_intercept = __esmMin((() => {
 	init_ensure_init_runner();
 	init_pre_boot_send();
+	init_run_restage();
 	ENSURE_INIT_RUNNER = "kici.ensureInitRunner";
 	PRE_BOOT_SEND = "kici.preBootSend";
+	RESTAGE_AGENT = "kici.restageAgent";
+}));
+//#endregion
+//#region src/bootstrap/payload-source.ts
+/**
+* Agent payload source abstraction.
+*
+* A one-method plug so the place a self-contained agent+Node payload comes from
+* is swappable and overridable: the local-dir fallback here reads the tarballs
+* a `kici-admin agent package` producer wrote to disk; an S3-backed source
+* (fetching from the orchestrator cache bucket via presigned URL) plugs in the
+* same interface. Payloads are version-keyed and fail-fast — a missing version
+* throws loudly rather than silently staging stale bytes.
+*/
+/** The payload tarball name for a platform (matches the producer's layout). */
+function tarballName$1(platform) {
+	return `kici-agent-${platform}.tar.gz`;
+}
+/** Extract the leading hex token from a `sha256sum`-style `<hex>  <name>` line. */
+function parseSidecarHash(contents) {
+	const first = contents.trim().split(/\s+/)[0];
+	if (!first) throw new Error("empty .sha256 sidecar");
+	return first;
+}
+var defaultPayloadFs, LocalDirPayloadSource;
+var init_payload_source = __esmMin((() => {
+	defaultPayloadFs = {
+		exists: async (filePath) => {
+			try {
+				await access(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		readFile: (filePath) => readFile(filePath, "utf8")
+	};
+	LocalDirPayloadSource = class {
+		baseDir;
+		fs;
+		constructor(baseDir, fs = defaultPayloadFs) {
+			this.baseDir = baseDir;
+			this.fs = fs;
+		}
+		async resolve(platform, version) {
+			const tarballPath = path.join(this.baseDir, version, tarballName$1(platform));
+			if (!await this.fs.exists(tarballPath)) throw new Error(`no agent payload for version ${version} (${platform}) at ${tarballPath} — run \`kici-admin agent package --platform ${platform} --out ${this.baseDir}\``);
+			const sidecarPath = `${tarballPath}.sha256`;
+			return {
+				tarballPath,
+				sha256: await this.fs.exists(sidecarPath) ? parseSidecarHash(await this.fs.readFile(sidecarPath)) : null
+			};
+		}
+	};
+}));
+//#endregion
+//#region src/bootstrap/s3-payload-source.ts
+/**
+* Object-storage agent payload source — the ops agent's PRIMARY source.
+*
+* Resolves a version-keyed self-contained agent+Node payload from the
+* orchestrator's own cache bucket via a presigned GET URL the orchestrator
+* mints (`kici.presignAgentPackage`), fetches it once into a local cache dir,
+* and returns it for the SSH-push delivery path. No standing S3 credential ever
+* reaches the ops agent — only a time-limited presigned URL. Payloads are
+* version-keyed and fail-fast: a missing object throws loudly (names the
+* version + platform) rather than staging stale bytes.
+*
+* For the `s3-direct` delivery path the box pulls the presigned URL itself, so
+* this source is not involved there; it backs `ssh-push` (box cannot reach
+* object storage). `LocalDirPayloadSource` remains the air-gap fallback.
+*/
+/** The payload tarball name for a platform (matches the producer's layout). */
+function tarballName(platform) {
+	return `kici-agent-${platform}.tar.gz`;
+}
+/** Default cache root the ops agent stores pulled payloads under (cache-once). */
+function defaultPayloadCacheDir() {
+	return path.join(kiciTmpBase(), "kici-agent-payloads");
+}
+/** Default existence check for the cache-once short-circuit. */
+async function payloadFileExists(filePath) {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Stream a (presigned) URL into a local file, binary-safe (no in-memory buffer). */
+async function fetchUrlToFile(url, dest) {
+	await mkdir(path.dirname(dest), { recursive: true });
+	const res = await fetch(url);
+	if (!res.ok || !res.body) throw new Error(`fetch payload failed: HTTP ${res.status} ${res.statusText}`);
+	await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+}
+var S3PayloadSource;
+var init_s3_payload_source = __esmMin((() => {
+	S3PayloadSource = class {
+		deps;
+		constructor(deps) {
+			this.deps = deps;
+		}
+		async resolve(platform, version) {
+			const presigned = await this.deps.presign(platform, version);
+			if (!presigned) throw new Error(`no agent payload for version ${version} (${platform}) in the orchestrator cache bucket — run \`kici-admin agent package --platform ${platform} --upload\` to publish it`);
+			const tarballPath = path.join(this.deps.cacheDir, version, tarballName(platform));
+			if (!(this.deps.exists ? await this.deps.exists(tarballPath) : false)) await this.deps.fetchToFile(presigned.url, tarballPath);
+			return {
+				tarballPath,
+				sha256: presigned.sha256
+			};
+		}
+	};
 }));
 //#endregion
 //#region src/execution/streaming-zx-log.ts
@@ -2921,20 +3772,30 @@ var init_api_intercept = __esmMin((() => {
 * `verbose: false` (suppressed). A `verbose: false` base would flag ordinary
 * output `verbose: false` too, and this gate would then drop every line.
 *
-* The returned callback owns a per-shell line buffer, so partial chunks are
-* coalesced into whole lines before `emit` is called.
+* The returned callback owns one line buffer PER STREAM, so partial chunks are
+* coalesced into whole lines before `emit` is called. The buffers are separate
+* because the two streams are independent pipes: a stdout chunk ending mid-line
+* and a stderr chunk arriving next would otherwise concatenate into a single
+* spliced line attributed to whichever kind completed it.
+*
+* `emit` receives the originating stream alongside the line so a diagnostic
+* written to stderr stays distinguishable from ordinary progress output all the
+* way to the persisted run log.
 */
 function makeStreamingZxLog(emit) {
-	let lineBuf = "";
+	const lineBufs = {
+		[LogStream.enum.stdout]: "",
+		[LogStream.enum.stderr]: ""
+	};
 	return (entry) => {
 		const e = entry;
 		if (e.kind !== "stdout" && e.kind !== "stderr") return;
 		if (!e.verbose) return;
+		const stream = e.kind === "stderr" ? LogStream.enum.stderr : LogStream.enum.stdout;
 		const text = typeof e.data === "string" ? e.data : String(e.data ?? "");
-		lineBuf += text;
-		const lines = lineBuf.split("\n");
-		lineBuf = lines.pop();
-		for (const line of lines) if (line) emit(line);
+		const lines = (lineBufs[stream] + text).split("\n");
+		lineBufs[stream] = lines.pop();
+		for (const line of lines) if (line) emit(line, stream);
 	};
 }
 var init_streaming_zx_log = __esmMin((() => {}));
@@ -3163,6 +4024,8 @@ var init_log_streamer = __esmMin((() => {
 		flushTimer = null;
 		totalBytes = 0;
 		truncated = false;
+		/** Which stream the currently-buffered lines came from. */
+		bufferStream = LogStream.enum.stdout;
 		/** Number of lines dropped due to backpressure (drop mode). */
 		droppedCount = 0;
 		/** Whether we are currently in a backpressured state (pause mode). */
@@ -3202,9 +4065,24 @@ var init_log_streamer = __esmMin((() => {
 		/**
 		* Add a line to the buffer. Triggers flush if threshold reached,
 		* otherwise schedules a timer-based flush.
+		*
+		* A chunk carries a single stream, so a kind flip closes the pending chunk
+		* before the new line is buffered. Chunks are delivered in order, so the
+		* stdout/stderr interleaving is preserved across that boundary.
+		*
+		* `bufferStream` is only advanced once the buffer is actually empty. Under
+		* pause-mode backpressure `flush()` deliberately leaves the buffer intact
+		* until the socket drains, so the flip cannot close the pending chunk;
+		* advancing the tag there would relabel the already-buffered lines as the
+		* newly-arrived stream. The buffer keeps the tag of its first lines instead,
+		* which means a chunk assembled while backpressured reports one stream for
+		* lines that came from both — stderr in such a chunk is under-reported as
+		* stdout. Separating them needs a queue of pending per-stream chunks.
 		*/
-		addLine(line) {
+		addLine(line, stream = LogStream.enum.stdout) {
 			if (this.truncated) return;
+			if (this.buffer.length > 0 && stream !== this.bufferStream) this.flush();
+			if (this.buffer.length === 0) this.bufferStream = stream;
 			if (this.totalBytes >= this.maxLogSizeBytes) {
 				this.buffer.push(`[TRUNCATED: log output exceeded ${this.maxLogSizeBytes} bytes]`);
 				this.truncated = true;
@@ -3259,7 +4137,8 @@ var init_log_streamer = __esmMin((() => {
 				jobId: this.jobId,
 				stepIndex: this.stepIndex,
 				lines,
-				timestamp: Date.now()
+				timestamp: Date.now(),
+				stream: this.bufferStream
 			});
 		}
 		/**
@@ -3321,7 +4200,8 @@ var init_log_streamer = __esmMin((() => {
 				jobId: this.jobId,
 				stepIndex: this.stepIndex,
 				lines,
-				timestamp: Date.now()
+				timestamp: Date.now(),
+				stream: this.bufferStream
 			});
 		}
 		/**
@@ -3416,7 +4296,7 @@ function decryptBuffer(encrypted, aesKey) {
 */
 async function applyOverlay(config) {
 	const { tarballUrl, cliPublicKey, orchestratorPrivateKey, repoDir } = config;
-	const tmpDir = await fsPromises.mkdtemp(path.join(os.tmpdir(), "kici-overlay-"));
+	const { path: tmpDir, cleanup } = await makeTempDir("overlay");
 	try {
 		logger$7.info("Downloading overlay tarball", { url: tarballUrl.replace(/\?.*$/, "?[redacted]") });
 		let encryptedData;
@@ -3490,10 +4370,7 @@ async function applyOverlay(config) {
 			verified: true
 		};
 	} finally {
-		await fsPromises.rm(tmpDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanup().catch(() => {});
 	}
 }
 var logger$7, IV_LENGTH$1, AUTH_TAG_LENGTH;
@@ -3676,7 +4553,7 @@ async function applyYarnrcBerryConfig(args) {
 	const hasPrivateRegistry = registries.length > 0 || Object.keys(installEnvSecrets).length > 0;
 	const yarnrcPath = join(args.kiciDir, ".yarnrc.yml");
 	const { raw: original, doc } = await readOriginalYarnrc(yarnrcPath);
-	const cacheFolder = await mkdtemp(join(tmpdir(), "kici-yarn-berry-cache-"));
+	const { path: cacheFolder, cleanup: cleanupCache } = await makeTempDir("yarn-berry-cache");
 	const merged = {
 		...doc,
 		nodeLinker: "node-modules",
@@ -3713,10 +4590,7 @@ async function applyYarnrcBerryConfig(args) {
 			if (original === null) await unlink(yarnrcPath).catch(() => {});
 			else await writeFile(yarnrcPath, original, { encoding: "utf8" });
 		} catch {}
-		await rm(cacheFolder, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanupCache().catch(() => {});
 	};
 	return {
 		extraEnv: {
@@ -4059,9 +4933,9 @@ async function detectKiciYarnFlavor(repoRoot, kiciDir) {
 * Install `.kici/` dependencies inline with the repo's package manager.
 *
 * Falls back to this when the dep cache is unavailable or a download fails.
-* The install runs with an isolated cache/store directory (created in
-* `os.tmpdir()`) to prevent cache poisoning between build jobs; the directory
-* is removed after installation.
+* The install runs with an isolated cache/store directory (allocated under the
+* global temp base, which honors `KICI_TMPDIR`) to prevent cache poisoning
+* between build jobs; the directory is removed after installation.
 *
 * If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, a job-scoped
 * `.kici/.npmrc` overlay is synthesized for the install, restored in `finally`,
@@ -4150,7 +5024,7 @@ function envWithNodeOnPath(extraEnv, nodeDir) {
 /** Run `npm install` in `.kici/` with an isolated cache directory. */
 async function runNpmInstall(args) {
 	const { npmCliPath, nodeExe, nodeDir } = resolveNpm();
-	const cacheDir = await mkdtemp(join(tmpdir(), "kici-npm-cache-"));
+	const { path: cacheDir, cleanup } = await makeTempDir("npm-cache");
 	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
 	const buildArgs = (...prefix) => {
 		const a = [
@@ -4175,10 +5049,7 @@ async function runNpmInstall(args) {
 			maxBuffer: INSTALL_MAX_BUFFER
 		});
 	} finally {
-		await rm(cacheDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanup().catch(() => {});
 	}
 }
 /**
@@ -4192,7 +5063,7 @@ async function runNpmInstall(args) {
 async function runPnpmInstall(args) {
 	await assertPnpmAvailable();
 	const { nodeDir } = resolveNpm();
-	const storeDir = await mkdtemp(join(tmpdir(), "kici-pnpm-store-"));
+	const { path: storeDir, cleanup } = await makeTempDir("pnpm-store");
 	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
 	const argv = [
 		"install",
@@ -4212,10 +5083,7 @@ async function runPnpmInstall(args) {
 			maxBuffer: INSTALL_MAX_BUFFER
 		});
 	} finally {
-		await rm(storeDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanup().catch(() => {});
 	}
 }
 /** Pure: argv for `yarn install` with an isolated cache folder. */
@@ -4241,7 +5109,7 @@ function buildYarnInstallArgs(cacheDir, hasPrivateRegistry) {
 async function runYarnInstall(args) {
 	await assertYarnAvailable();
 	const { nodeDir } = resolveNpm();
-	const cacheDir = await mkdtemp(join(tmpdir(), "kici-yarn-cache-"));
+	const { path: cacheDir, cleanup } = await makeTempDir("yarn-cache");
 	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
 	const argv = buildYarnInstallArgs(cacheDir, args.hasPrivateRegistry);
 	try {
@@ -4253,10 +5121,7 @@ async function runYarnInstall(args) {
 			maxBuffer: INSTALL_MAX_BUFFER
 		});
 	} finally {
-		await rm(cacheDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanup().catch(() => {});
 	}
 }
 /** Pure: argv for a berry `yarn install`. Cache + linker live in .yarnrc.yml. */
@@ -4708,6 +5573,7 @@ function buildRequest(dispatch, workDir) {
 		workflowRepoIdentifier: jobConfig.workflowRepoIdentifier,
 		hasConcurrencyGroup: jobConfig.hasConcurrencyGroup ?? false,
 		concurrencyEvaluationTimeoutMs: jobConfig.concurrencyEvaluationTimeoutMs,
+		concurrencyWaitTimeoutMs: dispatch.concurrencyWaitTimeoutMs,
 		branch: dispatch.ref,
 		upstreamJobOutputs: dispatch.upstreamJobOutputs,
 		upstreamJobStatuses: dispatch.upstreamJobStatuses,
@@ -4775,6 +5641,7 @@ function buildBwrapArgs(workDir, nodeExecPath, networkIsolation = false, runnerP
 		const libIdx = args.indexOf("/lib", args.indexOf("--ro-bind") + 1);
 		if (libIdx !== -1) args.splice(libIdx + 2, 0, "--ro-bind", "/lib64", "/lib64");
 	}
+	for (const nssFile of ["/etc/hosts", "/etc/nsswitch.conf"]) if (existsSync(nssFile)) args.push("--ro-bind", nssFile, nssFile);
 	const nodeDir = dirname(nodeExecPath);
 	const nodeInstallRoot = dirname(nodeDir);
 	if (!nodeInstallRoot.startsWith("/usr") && !nodeInstallRoot.startsWith("/bin") && nodeInstallRoot !== "/" && nodeInstallRoot !== "") args.push("--ro-bind", nodeInstallRoot, nodeInstallRoot);
@@ -4819,6 +5686,28 @@ function buildBwrapArgs(workDir, nodeExecPath, networkIsolation = false, runnerP
 	return args;
 }
 /**
+* Derive the read-only bind path(s) for a `file://` clone source. The workflow
+* runner clones the repo from inside the sandbox, so a local `file://` URL's
+* source directory must be exposed read-only or `git clone` fails with
+* `does not appear to be a git repository`. Returns `[]` for non-`file://`
+* remotes (https/ssh need no host bind) and for a malformed `file://` URL (the
+* clone then surfaces the real error rather than being masked here).
+*
+* Shared by both sandboxes that clone a local source: the bare-metal (bwrap)
+* backend threads the result into `buildBwrapArgs`'s `extraReadOnlyBinds`, and
+* the container backend binds each `<dir>:<dir>:ro` into the job container —
+* the same clone-source affordance across both isolation models.
+*/
+function fileCloneSourceBinds(repoUrl) {
+	if (typeof repoUrl !== "string" || !repoUrl.startsWith("file://")) return [];
+	try {
+		const url = new URL(repoUrl);
+		return url.pathname && url.pathname !== "/" ? [url.pathname] : [];
+	} catch {
+		return [];
+	}
+}
+/**
 * Spawn the workflow-runner child process. Returns the child handle and a
 * boolean indicating whether the spawn produced a usable PID. On Windows
 * services (shawl) fork() can fail silently when IPC pipes cannot be set up;
@@ -4967,6 +5856,24 @@ function relayProvenanceRequest$1(msg, ctx) {
 		error: toErrorMessage(err)
 	}));
 }
+/** Relay `artifacts.request` and pipe the orchestrator response (or an error
+*  response, or a "not configured" response when the callback isn't wired) back
+*  into the sandbox runner. */
+function relayArtifactRequest$1(msg, ctx) {
+	if (!ctx.execOptions.onArtifactRequest) {
+		safeSendToChild(ctx.child, {
+			type: "artifacts.response",
+			requestId: msg.requestId,
+			error: "Artifacts not available in this agent configuration"
+		});
+		return;
+	}
+	ctx.execOptions.onArtifactRequest(msg).then((response) => safeSendToChild(ctx.child, response), (err) => safeSendToChild(ctx.child, {
+		type: "artifacts.response",
+		requestId: msg.requestId,
+		error: toErrorMessage(err)
+	}));
+}
 /** Relay `approval.request` and pipe the orchestrator's resolution (or a
 *  fail-closed reject when the callback isn't wired or the relay throws) back
 *  into the sandbox runner. */
@@ -5021,7 +5928,7 @@ function relayChildIpcMessage(msg, dispatch, ctx) {
 			});
 			return;
 		case "log.line":
-			ctx.execOptions.onLogLine(msg.stepIndex, msg.line);
+			ctx.execOptions.onLogLine(msg.stepIndex, msg.line, msg.stream);
 			return;
 		case "step.start": {
 			ctx.stepNames.set(msg.stepIndex, msg.stepName);
@@ -5069,6 +5976,9 @@ function relayChildIpcMessage(msg, dispatch, ctx) {
 		case "cache.request":
 			relayCacheRequest$1(msg, ctx);
 			return;
+		case "artifacts.request":
+			relayArtifactRequest$1(msg, ctx);
+			return;
 		case "provenance.request":
 			relayProvenanceRequest$1(msg, ctx);
 			return;
@@ -5286,14 +6196,7 @@ var init_bare_metal_sandbox = __esmMin((() => {
 		* Execute a job by forking the workflow runner with sanitized environment.
 		*/
 		async executeJob(options) {
-			const extraReadOnlyBinds = [];
-			if (this.useBwrap) {
-				const repoUrl = options.dispatch.repoUrl;
-				if (typeof repoUrl === "string" && repoUrl.startsWith("file://")) try {
-					const url = new URL(repoUrl);
-					if (url.pathname) extraReadOnlyBinds.push(url.pathname);
-				} catch {}
-			}
+			const extraReadOnlyBinds = this.useBwrap ? fileCloneSourceBinds(options.dispatch.repoUrl) : [];
 			this.runner = createForkRunner({
 				runnerPath: this.runnerPath,
 				env: this.env,
@@ -5380,6 +6283,43 @@ var init_firecracker_sandbox = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region src/execution/sandbox/container-hardening.ts
+/**
+* Build the hardened HostConfig fragment for a job sandbox container.
+*
+* Pure and side-effect-free: given resolved inputs it returns the fields the
+* container-sandbox merges into `docker.createContainer`. When `hardened` is
+* false it returns an empty posture (the rollback affordance).
+*/
+function buildContainerHardening(opts) {
+	if (!opts.hardened) return { hostConfig: {} };
+	const grant = opts.grant;
+	const hostConfig = {
+		CapDrop: [...CAP_DROP_ALL],
+		SecurityOpt: [...NO_NEW_PRIVILEGES],
+		PidsLimit: opts.pidsLimit,
+		Memory: opts.memoryBytes,
+		MemorySwap: opts.memoryBytes,
+		NanoCpus: opts.nanoCpus,
+		Tmpfs: { "/tmp": "rw,exec,nosuid,nodev" }
+	};
+	if (grant?.capabilities && grant.capabilities.length > 0) hostConfig.CapAdd = [...grant.capabilities];
+	if (grant?.readonlyRootfs ?? opts.readonlyRootfs) hostConfig.ReadonlyRootfs = true;
+	const network = grant?.network ?? opts.networkMode;
+	if (network === "none") hostConfig.NetworkMode = "none";
+	else if (network === "host") hostConfig.NetworkMode = "host";
+	const user = grant?.user ?? opts.user;
+	return user ? {
+		hostConfig,
+		user
+	} : { hostConfig };
+}
+var CAP_DROP_ALL, NO_NEW_PRIVILEGES;
+var init_container_hardening = __esmMin((() => {
+	CAP_DROP_ALL = ["ALL"];
+	NO_NEW_PRIVILEGES = ["no-new-privileges"];
+}));
+//#endregion
 //#region src/execution/sandbox/container-sandbox.ts
 /**
 * Container execution sandbox implementation.
@@ -5522,6 +6462,32 @@ function relayProvenanceRequest(stream, options, provMsg) {
 	}));
 }
 /**
+* Relay artifacts.request from the container runner to the orchestrator via
+* options.onArtifactRequest, then write the response back through `stream`. If
+* the agent doesn't expose an artifacts relay, write a structured error so the
+* runner doesn't hang.
+*/
+function relayArtifactRequest(stream, options, artMsg) {
+	const writeResponse = (response) => {
+		try {
+			stream.write(JSON.stringify(response) + "\n");
+		} catch {}
+	};
+	if (!options.onArtifactRequest) {
+		writeResponse({
+			type: "artifacts.response",
+			requestId: artMsg.requestId,
+			error: "Artifacts not available in this agent configuration"
+		});
+		return;
+	}
+	options.onArtifactRequest(artMsg).then((response) => writeResponse(response), (err) => writeResponse({
+		type: "artifacts.response",
+		requestId: artMsg.requestId,
+		error: toErrorMessage(err)
+	}));
+}
+/**
 * Relay approval.request from the container runner to the orchestrator via
 * options.onApprovalRequest, then write the resolution back through `stream`.
 * If the agent doesn't expose an approval relay (or it throws), write a
@@ -5565,22 +6531,30 @@ function applyJobComplete(msg, stepResults, state, options) {
 		logger$3.warn("Failed to encrypt secret outputs", { error: toErrorMessage(err) });
 	}
 }
-var logger$3, MAX_STDERR_LINES, ABORT_GRACE_MS, CONTAINER_STOP_TIMEOUT, ContainerSandbox;
+var logger$3, MAX_STDERR_LINES, ABORT_GRACE_MS, CONTAINER_STOP_TIMEOUT, HOOK_MOUNT_PATH, INTERNAL_ENV, ContainerSandbox;
 var init_container_sandbox = __esmMin((() => {
 	init_fork_runner();
 	init_secret_encryption();
+	init_container_hardening();
 	logger$3 = createLogger({ prefix: "container-sandbox" });
 	MAX_STDERR_LINES = 20;
 	ABORT_GRACE_MS = 1e4;
 	CONTAINER_STOP_TIMEOUT = 10;
+	HOOK_MOUNT_PATH = "/opt/kici/ts-loader-hook.js";
+	INTERNAL_ENV = [`KICI_TS_LOADER_HOOK_PATH=${HOOK_MOUNT_PATH}`, "KICI_LOG_STDERR=1"];
 	ContainerSandbox = class {
 		docker;
 		image;
 		runnerPath;
 		runnerMountPath;
+		/** Host path to the pure-JS container loader-hook bundle (bind-mounted :ro). */
+		hookHostPath;
 		env;
 		keepFailed;
 		jobId;
+		hardening;
+		/** Resolved container user (image-user override / grant), applied to createContainer + each exec. */
+		resolvedUser;
 		/** The running container instance (set during setup). */
 		container = null;
 		/** The active exec stream (set during executeJob, used for abort). */
@@ -5594,29 +6568,66 @@ var init_container_sandbox = __esmMin((() => {
 			this.image = options.image;
 			this.runnerPath = options.runnerPath;
 			this.runnerMountPath = options.runnerMountPath ?? "/opt/kici/workflow-runner.js";
+			this.hookHostPath = options.hookPath ?? join(dirname(options.runnerPath), "container-ts-loader-hook.js");
 			this.env = options.env;
 			this.keepFailed = options.keepFailed ?? false;
 			this.jobId = options.jobId ?? `unknown-${Date.now()}`;
+			this.hardening = options.hardening;
+		}
+		/**
+		* Ensure the job's container image is present locally, pulling it on demand
+		* when it is not.
+		*
+		* dockerode's `createContainer` — unlike `docker run` / `podman run` — never
+		* auto-pulls a missing image; it fails with `(HTTP code 404) ... No such
+		* image`. A bare-metal executor that aggressively prunes unused images under
+		* disk pressure can leave a container job with nothing to run, so the agent
+		* pulls the image itself. Already-present images (the common case, and how
+		* private images pre-pulled with registry auth stay working) skip the pull.
+		*/
+		async ensureImagePresent() {
+			try {
+				await this.docker.getImage(this.image).inspect();
+				return;
+			} catch {}
+			logger$3.info("Pulling sandbox image (not present locally)", { image: this.image });
+			const stream = await this.docker.pull(this.image);
+			await new Promise((resolve, reject) => {
+				this.docker.modem.followProgress(stream, (err) => err ? reject(err) : resolve());
+			});
+			logger$3.info("Sandbox image pulled", { image: this.image });
 		}
 		async setup(options) {
 			this.containerName = `kici-sandbox-${this.jobId}-${Date.now()}`;
-			const envArray = Object.entries(this.env).map(([k, v]) => `${k}=${v}`);
+			const envArray = [...Object.entries(this.env).map(([k, v]) => `${k}=${v}`), ...INTERNAL_ENV];
 			logger$3.info("Creating sandbox container", {
 				name: this.containerName,
 				image: this.image,
 				workDir: options.workDir
 			});
+			const hardened = this.hardening ? buildContainerHardening(this.hardening) : {
+				hostConfig: {},
+				user: void 0
+			};
+			this.resolvedUser = hardened.user;
+			const binds = this.buildBinds(options, hardened.hostConfig);
+			await this.ensureImagePresent();
 			this.container = await this.docker.createContainer({
 				Image: this.image,
 				name: this.containerName,
 				Cmd: ["sleep", "infinity"],
 				Env: envArray,
 				WorkingDir: "/workspace",
+				Volumes: { "/workspace": {} },
+				...hardened.user ? { User: hardened.user } : {},
 				Labels: {
 					"kici-sandbox": "true",
 					"kici-job-id": this.jobId
 				},
-				HostConfig: { Binds: [`${options.workDir}:/workspace`, `${this.runnerPath}:${this.runnerMountPath}:ro`] }
+				HostConfig: {
+					Binds: binds,
+					...hardened.hostConfig
+				}
 			});
 			await this.container.start();
 			logger$3.info("Sandbox container started", {
@@ -5624,6 +6635,36 @@ var init_container_sandbox = __esmMin((() => {
 				containerId: this.container.id.slice(0, 12)
 			});
 		}
+		/**
+		* Build the container's read-only bind list.
+		*
+		* The workspace is NOT bound here — it is a container-owned anonymous volume
+		* (`Volumes: { '/workspace': {} }` on the container config), so the container
+		* user can write it on every runtime with `CapDrop: ['ALL']` intact. This
+		* method binds the workflow runner (read-only) plus two parity affordances
+		* that mirror the bare-metal bwrap sandbox — both strictly additive and gated,
+		* so the default posture for a production (https-source, bridge-network) job is
+		* unchanged:
+		*
+		* - **`file://` clone-source dir(s)** (`options.extraReadOnlyBinds`): the
+		*   workflow runner clones the repo from inside the container, so a local
+		*   `file://` source dir must be exposed read-only or `git clone` fails.
+		*   Empty for https/ssh remotes — mirrors fork-runner's `extraReadOnlyBinds`.
+		* - **Host name-resolution files under host networking**: when the effective
+		*   network posture is `host` (`KICI_SANDBOX_NETWORK=host`, or a per-job host
+		*   grant), bind the host's `/etc/hosts` (+ `/etc/nsswitch.conf`) read-only so
+		*   an `/etc/hosts`-only name the host resolves — e.g. a private registry —
+		*   resolves inside the container too. Mirrors fork-runner's
+		*   `--ro-bind /etc/hosts` for the bwrap host-network mode.
+		*/
+		buildBinds(options, hostConfig) {
+			const binds = [`${this.runnerPath}:${this.runnerMountPath}:ro`, `${this.hookHostPath}:${HOOK_MOUNT_PATH}:ro`];
+			for (const dir of options.extraReadOnlyBinds ?? []) if (dir) binds.push(`${dir}:${dir}:ro`);
+			if (hostConfig.NetworkMode === "host") {
+				for (const nssFile of ["/etc/hosts", "/etc/nsswitch.conf"]) if (existsSync(nssFile)) binds.push(`${nssFile}:${nssFile}:ro`);
+			}
+			return binds;
+		}
 		async executeJob(options) {
 			if (!this.container) throw new Error("ContainerSandbox.executeJob() called before setup()");
 			const startTime = Date.now();
@@ -5655,14 +6696,15 @@ var init_container_sandbox = __esmMin((() => {
 		* stderr lines for crash diagnostics, and install the abort listener.
 		*/
 		async attachExecStream(options) {
-			const execEnv = Object.entries(this.env).map(([k, v]) => `${k}=${v}`);
+			const execEnv = [...Object.entries(this.env).map(([k, v]) => `${k}=${v}`), ...INTERNAL_ENV];
 			const stream = await (await this.container.exec({
 				Cmd: ["node", this.runnerMountPath],
 				AttachStdin: true,
 				AttachStdout: true,
 				AttachStderr: true,
 				Env: execEnv,
-				WorkingDir: "/workspace"
+				WorkingDir: "/workspace",
+				...this.resolvedUser ? { User: this.resolvedUser } : {}
 			})).start({
 				hijack: true,
 				stdin: true
@@ -5793,7 +6835,7 @@ var init_container_sandbox = __esmMin((() => {
 					return false;
 				}
 				case "log.line":
-					options.onLogLine(msg.stepIndex, msg.line);
+					options.onLogLine(msg.stepIndex, msg.line, msg.stream);
 					return false;
 				case "step.secret_mount":
 					options.onSecretMount?.({
@@ -5816,6 +6858,9 @@ var init_container_sandbox = __esmMin((() => {
 				case "cache.request":
 					relayCacheRequest(stream, options, msg);
 					return false;
+				case "artifacts.request":
+					relayArtifactRequest(stream, options, msg);
+					return false;
 				case "provenance.request":
 					relayProvenanceRequest(stream, options, msg);
 					return false;
@@ -5865,7 +6910,10 @@ var init_container_sandbox = __esmMin((() => {
 				await this.container.stop({ t: CONTAINER_STOP_TIMEOUT });
 			} catch {}
 			try {
-				await this.container.remove({ force: true });
+				await this.container.remove({
+					force: true,
+					v: true
+				});
 			} catch {}
 			this.container = null;
 		}
@@ -5909,13 +6957,15 @@ var init_sandbox = __esmMin((() => {
 	init_bare_metal_sandbox();
 	init_firecracker_sandbox();
 	init_container_sandbox();
+	init_fork_runner();
 }));
 //#endregion
 //#region src/execution/job-runner.ts
 var job_runner_exports = /* @__PURE__ */ __exportAll({
 	JobRunner: () => JobRunner$1,
 	buildEvalNeedsContext: () => buildEvalNeedsContext,
-	resolveJobWorkDir: () => resolveJobWorkDir
+	resolveJobWorkDir: () => resolveJobWorkDir,
+	resolveRunnerBundlePath: () => resolveRunnerBundlePath
 });
 /**
 * Check if a file exists at the given path.
@@ -5950,6 +7000,19 @@ function resolveRunnerPath() {
 	return bundlePath;
 }
 /**
+* Derive the self-contained runner bundle path from the resolved runner path.
+*
+* The container backend mounts the runner as a single file into the customer
+* job container, so it must run `workflow-runner-bundle.js` (zx + `@kici-dev/*`
+* inlined) rather than the external `workflow-runner.js`, which cannot resolve
+* its bare imports without the agent's node_modules / pnpm workspace. The
+* bundle is a flat sibling emitted alongside the runner by build-service.mjs.
+* bwrap / firecracker keep the external runner (they bind the workspace).
+*/
+function resolveRunnerBundlePath(runnerPath) {
+	return join(dirname(runnerPath), "workflow-runner-bundle.js");
+}
+/**
 * Determine the execution mode from agent config and job config.
 *
 * Priority:
@@ -5990,14 +7053,11 @@ async function resolveJobWorkDir(inPlace, repoUrl) {
 		cleanup: async () => {},
 		inPlace: true
 	};
-	const workDir = await fsPromises.mkdtemp(join(tmpdir(), "kici-"));
+	const { path: workDir, cleanup } = await makeTempDir("workdir");
 	return {
 		workDir,
 		cleanup: async () => {
-			await fsPromises.rm(workDir, {
-				recursive: true,
-				force: true
-			}).catch(() => {});
+			await cleanup().catch(() => {});
 		},
 		inPlace: false
 	};
@@ -6011,6 +7071,8 @@ var init_job_runner = __esmMin((() => {
 	init_init_runner();
 	init_api_intercept();
 	init_ensure_init_runner();
+	init_payload_source();
+	init_s3_payload_source();
 	init_timeout_util();
 	init_streaming_zx_log();
 	init_dynamic_job_serializer();
@@ -6025,7 +7087,6 @@ var init_job_runner = __esmMin((() => {
 	logger$2 = createLogger({ prefix: "job-runner" });
 	JobRunner$1 = class {
 		send;
-		sendDirect;
 		config;
 		requestUploadUrl;
 		sendUploadComplete;
@@ -6038,6 +7099,7 @@ var init_job_runner = __esmMin((() => {
 		_sendApiRequest;
 		_requestUserCache;
 		_relayProvenance;
+		_requestUserArtifact;
 		_sendStepApproval;
 		/** Tracks running jobs for concurrency and cancellation */
 		activeJobs = /* @__PURE__ */ new Map();
@@ -6045,7 +7107,6 @@ var init_job_runner = __esmMin((() => {
 		activeSandbox = null;
 		constructor(deps) {
 			this.send = deps.send;
-			this.sendDirect = deps.sendDirect;
 			this.config = deps.config;
 			this.requestUploadUrl = deps.requestUploadUrl;
 			this.sendUploadComplete = deps.sendUploadComplete;
@@ -6058,6 +7119,7 @@ var init_job_runner = __esmMin((() => {
 			this._sendApiRequest = deps.sendApiRequest;
 			this._requestUserCache = deps.requestUserCache;
 			this._relayProvenance = deps.relayProvenance;
+			this._requestUserArtifact = deps.requestUserArtifact;
 			this._sendStepApproval = deps.sendStepApproval;
 		}
 		/**
@@ -6161,13 +7223,15 @@ var init_job_runner = __esmMin((() => {
 				});
 			}, this.config.jobHeartbeatIntervalMs);
 			let sandbox;
+			const logStreamers = /* @__PURE__ */ new Map();
 			try {
 				const setupResult = await this.setupSandboxForExecution(dispatch, workDir, abortController);
 				if (!setupResult) return;
 				sandbox = setupResult.sandbox;
-				const { result, logStreamers } = await this.runSandboxExecution(dispatch, sandbox, abortController);
+				const result = await this.runSandboxExecution(dispatch, sandbox, abortController, logStreamers);
 				this.reportExecutionResult(dispatch, result, logStreamers);
 			} catch (error) {
+				for (const streamer of logStreamers.values()) streamer.destroy();
 				const errorMsg = toErrorMessage(error);
 				this.sendJobStatus(dispatch, ExecutionJobStatus.enum.failed, { error: errorMsg });
 			} finally {
@@ -6218,7 +7282,8 @@ var init_job_runner = __esmMin((() => {
 			this.activeSandbox = sandbox;
 			await sandbox.setup({
 				workDir,
-				env: sanitizedEnv
+				env: sanitizedEnv,
+				extraReadOnlyBinds: fileCloneSourceBinds(dispatch.repoUrl)
 			});
 			if (abortController.signal.aborted) {
 				this.sendJobStatus(dispatch, ExecutionJobStatus.enum.cancelled);
@@ -6243,13 +7308,13 @@ var init_job_runner = __esmMin((() => {
 		/**
 		* Drive `sandbox.executeJob` with IPC callbacks wired to the WS pipeline.
 		*
-		* Lazily creates per-step LogStreamers, forwards step + log + event-emit +
+		* Lazily populates `logStreamers` (owned by the caller so a throw still
+		* leaves the buffered output flushable), forwards step + log + event-emit +
 		* concurrency-report + api-request messages, and emits the
 		* `agent.execution.start` / `agent.execution.end` lifecycle events.
 		*/
-		async runSandboxExecution(dispatch, sandbox, abortController) {
+		async runSandboxExecution(dispatch, sandbox, abortController, logStreamers) {
 			const { runId, jobId } = dispatch;
-			const logStreamers = /* @__PURE__ */ new Map();
 			const maxLogSizeBytes = dispatch.maxLogSizeBytes ?? this.config.maxLogSizeBytes;
 			const getOrCreateLogStreamer = (stepIndex) => {
 				let streamer = logStreamers.get(stepIndex);
@@ -6278,8 +7343,8 @@ var init_job_runner = __esmMin((() => {
 					this.maybeEmitCacheRunEvent(runId, jobId, stepIndex, state, data);
 					this.sendStepStatus(dispatch, stepIndex, stepName, state, data, logBytesStreamed);
 				},
-				onLogLine: (stepIndex, line) => {
-					getOrCreateLogStreamer(stepIndex).addLine(line);
+				onLogLine: (stepIndex, line, stream) => {
+					getOrCreateLogStreamer(stepIndex).addLine(line, stream);
 				},
 				signal: abortController.signal,
 				onEventEmit: async (request) => {
@@ -6302,6 +7367,7 @@ var init_job_runner = __esmMin((() => {
 				onApiRequest: this._sendApiRequest ? withBootstrapInterception(async (method, params) => this._sendApiRequest(method, params)) : void 0,
 				onCacheRequest: this._requestUserCache ? async (request) => this._requestUserCache(jobId, request) : void 0,
 				onProvenanceRequest: this._relayProvenance ? async (request) => this._relayProvenance(jobId, request) : void 0,
+				onArtifactRequest: this._requestUserArtifact ? async (request) => this._requestUserArtifact(jobId, request) : void 0,
 				onApprovalRequest: this._sendStepApproval ? async (request) => this._sendStepApproval(dispatch.runId, dispatch.jobId, request) : void 0,
 				onSecretMount: (event) => {
 					this.emitRunEvent(runId, "step.secret_mount", {
@@ -6321,10 +7387,7 @@ var init_job_runner = __esmMin((() => {
 				durationMs: Date.now() - executionStartMs,
 				metadata: { status: result.status }
 			});
-			return {
-				result,
-				logStreamers
-			};
+			return result;
 		}
 		/**
 		* Tear down log streamers, record step Prometheus metrics, log sandbox
@@ -6386,7 +7449,19 @@ var init_job_runner = __esmMin((() => {
 				if (!targetAgentId) throw new Error("bring-up job missing bringupTarget");
 				if (!this._sendApiRequest) throw new Error("bring-up job requires an orchestrator API transport");
 				streamer.addLine(`Bringing up init-runner on ${targetAgentId}…`);
-				const result = await ensureInitRunner(async (method, params) => this._sendApiRequest(method, params), targetAgentId);
+				const transport = async (method, params) => this._sendApiRequest(method, params);
+				const result = await ensureInitRunner(transport, targetAgentId, {
+					payloadSource: this.config.agentPayloadDir ? new LocalDirPayloadSource(this.config.agentPayloadDir) : new S3PayloadSource({
+						presign: async (platform) => await transport("kici.presignAgentPackage", {
+							targetAgentId,
+							platform
+						}),
+						fetchToFile: fetchUrlToFile,
+						cacheDir: defaultPayloadCacheDir(),
+						exists: payloadFileExists
+					}),
+					agentCommand: this.config.agentCommand
+				});
 				streamer.addLine(result.broughtUp ? `Init-runner brought up on ${targetAgentId}.` : `${targetAgentId} already has a live agent — no bring-up needed.`);
 				await streamer.flush();
 				this.sendStepStatus(dispatch, 0, "bring-up", ExecutionStepStatus.enum.success, void 0, streamer.getTotalBytes());
@@ -6783,7 +7858,7 @@ var init_job_runner = __esmMin((() => {
 					env: { ...process.env },
 					verbose: true,
 					quiet: false,
-					log: makeStreamingZxLog((line) => evalStreamer.addLine(line))
+					log: makeStreamingZxLog((line, stream) => evalStreamer.addLine(line, stream))
 				});
 				const evalSink = { addLine: (line) => evalStreamer.addLine(line) };
 				const dynamicJobLogger = {
@@ -6868,10 +7943,20 @@ var init_job_runner = __esmMin((() => {
 					return new ContainerSandbox({
 						docker: new Docker(),
 						image,
-						runnerPath: opts.runnerPath,
+						runnerPath: resolveRunnerBundlePath(opts.runnerPath),
 						env: opts.env,
 						keepFailed: this.config.dockerKeepFailed,
-						jobId: opts.jobId
+						jobId: opts.jobId,
+						hardening: {
+							hardened: this.config.sandboxHardened,
+							readonlyRootfs: this.config.sandboxReadonlyRootfs,
+							user: this.config.sandboxUser,
+							pidsLimit: this.config.sandboxPidsLimit,
+							memoryBytes: this.config.sandboxMemoryBytes,
+							nanoCpus: this.config.sandboxNanoCpus,
+							networkMode: this.config.sandboxNetwork === "host" ? "host" : "default",
+							grant: opts.jobConfig.sandboxGrant
+						}
 					});
 				}
 				case "firecracker": return new FirecrackerSandbox({
@@ -6960,7 +8045,7 @@ var init_job_runner = __esmMin((() => {
 		* they are included as a top-level field on the WS message (not nested in data).
 		*/
 		sendJobStatus(dispatch, state, data, secretOutputs) {
-			this.sendDirect({
+			this.send({
 				type: "job.status",
 				messageId: randomUUID(),
 				runId: dispatch.runId,
@@ -6986,7 +8071,7 @@ var init_job_runner = __esmMin((() => {
 			const groupId = data?.groupId;
 			const { secretsAccessed: _s, concurrencyKind: _c, groupId: _g, ...restData } = data ?? {};
 			const hasRestData = Object.keys(restData).length > 0;
-			this.sendDirect({
+			this.send({
 				type: "step.status",
 				messageId: randomUUID(),
 				runId: dispatch.runId,
@@ -7012,7 +8097,7 @@ var init_job_runner = __esmMin((() => {
 * Startup sequence:
 * 1. Load config
 * 2. Create logger
-* 3. Create JobRunner with send/sendDirect callbacks
+* 3. Create JobRunner with send callbacks
 * 4. Create OrchestratorClient with dispatch and cancel handlers
 * 5. Add WS log transport (if not scaler-managed)
 * 6. Connect OrchestratorClient
@@ -7026,14 +8111,14 @@ var init_job_runner = __esmMin((() => {
 */
 init_console_capture();
 init_npm_resolver();
-const AGENT_VERSION = "0.1.27";
-const BUILD_COMMIT = "f0747470b";
-const SDK_VERSION = "0.1.27";
-const SDK_BUNDLE_HASH = "e06bd1acf349ba365bdb357f3d865e0cbb4ad4604a0270b707a681a4f440954e";
-const SHARED_VERSION = "0.1.27";
-const SHARED_BUNDLE_HASH = "f8e1f0117cf41fca5a74377633e2ec89e54ce4eda47d9f476cdb83336f1ed962";
-const ENGINE_VERSION = "0.1.27";
-const ENGINE_BUNDLE_HASH = "ce675fb4790406ed2a938f8f1783db37b283cffd7d8fc1eb12a878e0bfb919b3";
+const AGENT_VERSION = "0.2.0";
+const BUILD_COMMIT = "15d5e4447";
+const SDK_VERSION = "0.2.0";
+const SDK_BUNDLE_HASH = "fcd0a836aa1cb92debd93e0254450614d123b3748511aa4148d956fd72a7c29f";
+const SHARED_VERSION = "0.2.0";
+const SHARED_BUNDLE_HASH = "f16fa528a8a9ef1bed8df369f0e88efafca8a9954a749005299fdbcdb93fa188";
+const ENGINE_VERSION = "0.2.0";
+const ENGINE_BUNDLE_HASH = "c579e54f7d0b0d5b16587a0528a3e66d32f63e2434bb471a93a01366296efd58";
 initTelemetry({
 	serviceName: "kici-agent",
 	otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
@@ -7103,7 +8188,6 @@ await guardStartup(logger$1, async () => {
 	let client;
 	const jobRunner = new JobRunner({
 		send: (msg) => client.send(msg),
-		sendDirect: (msg) => client.sendDirect(msg),
 		config,
 		requestUploadUrl: (jobId, cacheType, key) => client.requestUploadUrl(jobId, cacheType, key),
 		sendUploadComplete: (jobId, cacheType, key) => client.sendUploadComplete(jobId, cacheType, key),
@@ -7124,6 +8208,7 @@ await guardStartup(logger$1, async () => {
 		},
 		requestUserCache: (jobId, request) => client.requestUserCache(jobId, request),
 		relayProvenance: (jobId, request) => client.relayProvenance(jobId, request),
+		requestUserArtifact: (jobId, request) => client.requestUserArtifact(jobId, request),
 		sendStepApproval: (runId, jobId, request) => client.sendStepApproval(runId, jobId, request)
 	});
 	/** Build and send an agent.status message with dynamic OS metadata. */