@omg-dev/sandbox 0.4.26 → 0.4.28

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as compileStartScript, c as download, d as templateRuntimeContract, f as templateVersionRef, h as assertTemplateId, i as check, l as run, m as SandboxClient, n as apt, o as compileStep, p as waitForSnapshotUpload, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as templateDefinitionHash } from "./templates-CdQWcmOC.mjs";
-export { SandboxClient, applyTemplate, apt, assertTemplateId, bakeTemplate, check, compileStartScript, compileStep, defineTemplate, download, run, templateDefinitionHash, templateRuntimeContract, templateVersionRef, waitForSnapshotUpload };
+import { _ as SandboxClient, a as compileStartScript, c as download, d as templateContentVersionRef, f as templateDefinitionHash, g as SandboxApiError, h as waitForSnapshotUpload, i as check, l as files, m as templateVersionRef, n as apt, o as compileStep, p as templateRuntimeContract, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as run, v as assertTemplateId } from "./templates-C3mBSGdT.mjs";
+export { SandboxApiError, SandboxClient, applyTemplate, apt, assertTemplateId, bakeTemplate, check, compileStartScript, compileStep, defineTemplate, download, files, run, templateContentVersionRef, templateDefinitionHash, templateRuntimeContract, templateVersionRef, waitForSnapshotUpload };

package/dist/{templates-CdQWcmOC.mjs → templates-C3mBSGdT.mjs}

@@ -1,5 +1,18 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
 //#region src/client.ts
+/** Error thrown by SandboxClient.request carrying the HTTP status, so callers
+* can branch on well-defined statuses (e.g. 404 template probe) instead of
+* string-matching error messages. */
+var SandboxApiError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "SandboxApiError";
+		this.status = status;
+	}
+};
 const TEMPLATE_ID = /^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$/;
 function assertTemplateId(id) {
 	const normalized = id.trim().toLowerCase();
@@ -38,7 +51,7 @@ var SandboxClient = class {
 		} catch {}
 		if (!response.ok) {
 			const detail = parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : text || `HTTP ${response.status}`;
-			throw new Error(`sandbox API ${method} ${path}: ${response.status} ${detail}`);
+			throw new SandboxApiError(`sandbox API ${method} ${path}: ${response.status} ${detail}`, response.status);
 		}
 		return parsed;
 	}
@@ -49,6 +62,9 @@ var SandboxClient = class {
 	async getSnapshot(id) {
 		return this.request("GET", `/v1/snapshots/${encodeURIComponent(id)}`);
 	}
+	async deleteSnapshot(id) {
+		await this.request("DELETE", `/v1/snapshots/${encodeURIComponent(id)}`);
+	}
 	async publishTemplate(templateId, snapshotId, runtime) {
 		const id = assertTemplateId(templateId);
 		await this.request("POST", `/v1/templates/${id}/latest`, {
@@ -107,6 +123,14 @@ function run(options) {
 		...options
 	};
 }
+const files = { copy(options) {
+	if (!options.sourceDir.trim()) throw new Error("files.copy requires a sourceDir");
+	if (!options.destination.trim()) throw new Error("files.copy requires a destination");
+	return {
+		kind: "files",
+		...options
+	};
+} };
 const check = {
 	command(command, options = {}) {
 		return {
@@ -129,11 +153,18 @@ function defineTemplate(definition) {
 	for (const port of definition.ports ?? []) if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`invalid template port ${port}`);
 	return Object.freeze(definition);
 }
-function templateVersionRef(definition) {
-	const suffix = `-v${definition.version.toLowerCase().replace(/[^a-z0-9-]+/g, "-")}`;
+function refWithSuffix(id, suffix) {
 	const maxBase = 40 - suffix.length;
 	if (maxBase < 2) throw new Error("template id and version are too long for registry");
-	return assertTemplateId(`${definition.id.slice(0, maxBase).replace(/-+$/, "")}${suffix}`);
+	return assertTemplateId(`${id.slice(0, maxBase).replace(/-+$/, "")}${suffix}`);
+}
+function templateVersionRef(definition) {
+	return refWithSuffix(definition.id, `-v${definition.version.toLowerCase().replace(/[^a-z0-9-]+/g, "-")}`);
+}
+function templateContentVersionRef(definition, contentKey) {
+	if (!contentKey.trim()) throw new Error("template content key (base rootfs sha) is required");
+	const hash = createHash("sha256").update(`${templateDefinitionHash(definition)}\n${contentKey.trim()}`).digest("hex").slice(0, 8);
+	return refWithSuffix(definition.id, `-v${definition.version.toLowerCase().replace(/[^a-z0-9-]+/g, "-")}-${hash}`);
 }
 function templateDefinitionHash(definition) {
 	return createHash("sha256").update(JSON.stringify(definition)).digest("hex");
@@ -150,10 +181,19 @@ function templateRuntimeContract(definition, immutableRef) {
 function quote(value) {
 	return `'${value.replaceAll("'", `'\"'\"'`)}'`;
 }
+const PROXY_ENV_VARS = [
+	"OMG_AI_URL",
+	"ANTHROPIC_BASE_URL",
+	"ANTHROPIC_API_KEY",
+	"OPENAI_BASE_URL",
+	"OPENAI_API_KEY",
+	"OMG_MEDIA_URL"
+];
 function commandForUser(command, user) {
 	if (!user) return `/bin/bash -lc ${quote(command)}`;
 	const home = user === "root" ? "/root" : `/home/${user}`;
-	return `sudo -u ${quote(user)} -H env HOME=${quote(home)} PATH=${quote(`${home}/.bun/bin:/usr/local/bin:/usr/bin:/bin`)} /bin/bash -c ${quote(command)}`;
+	const proxyEnv = PROXY_ENV_VARS.map((name) => `${name}="\${${name}:-}"`).join(" ");
+	return `sudo -u ${quote(user)} -H env HOME=${quote(home)} PATH=${quote(`${home}/.bun/bin:/usr/local/bin:/usr/bin:/bin`)} ${proxyEnv} /bin/bash -c ${quote(command)}`;
 }
 function shellEnvAssignments(env) {
 	return Object.entries(env).map(([key, value]) => {
@@ -162,6 +202,7 @@ function shellEnvAssignments(env) {
 	});
 }
 function compileStep(step) {
+	if (step.kind === "files") throw new Error("files steps transfer local content and are applied via applyTemplate(), not compileStep()");
 	if (step.kind === "apt") return { script: `set -euo pipefail\napt-get update -qq\nDEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends ${step.packages.map(quote).join(" ")}\nrm -rf /var/lib/apt/lists/*` };
 	if (step.kind === "archive") {
 		const strip = step.stripComponents ?? 1;
@@ -187,11 +228,113 @@ function compileStartScript(start) {
 async function assertExec(label, result) {
 	if (result.exitCode !== 0) throw new Error(`${label} failed (${result.exitCode}): ${(result.stderr || result.stdout).trim().slice(-1200)}`);
 }
+async function runTemplateStep(sandbox, label, script, timeoutMs) {
+	const workDir = `/tmp/omg-template-step-${randomUUID()}`;
+	const pidPath = `${workDir}/pid`;
+	const statusPath = `${workDir}/status`;
+	const stdoutPath = `${workDir}/stdout`;
+	const stderrPath = `${workDir}/stderr`;
+	const wrapper = [
+		"set -u",
+		`mkdir -p ${quote(workDir)}`,
+		`printf '%s\\n' \"$$\" > ${quote(pidPath)}`,
+		`set +e; /bin/bash -lc ${quote(script)} > ${quote(stdoutPath)} 2> ${quote(stderrPath)}`,
+		"code=$?",
+		`printf '%s\\n' \"$code\" > ${quote(`${statusPath}.tmp`)}`,
+		`mv ${quote(`${statusPath}.tmp`)} ${quote(statusPath)}`,
+		"exit \"$code\""
+	].join("\n");
+	const prepared = await sandbox.shell(`mkdir -p ${quote(workDir)}`, { timeoutMs: 1e4 });
+	await assertExec(`${label} workspace preparation`, prepared);
+	const deadline = Date.now() + timeoutMs;
+	const launchDeadline = Math.min(deadline, Date.now() + 1e4);
+	try {
+		if (!(await sandbox.shell(wrapper, { detached: true })).commandId) throw new Error(`${label} did not start as a detached guest command`);
+		while (Date.now() < deadline) {
+			const probe = await sandbox.shell([
+				`if test -f ${quote(statusPath)}; then`,
+				"  printf 'done\\n'",
+				`  cat ${quote(statusPath)}`,
+				`elif test -f ${quote(pidPath)} && kill -0 \"$(cat ${quote(pidPath)})\" 2>/dev/null; then`,
+				"  printf 'running\\n'",
+				`elif test ! -f ${quote(pidPath)}; then`,
+				"  printf 'starting\\n'",
+				"else",
+				"  printf 'lost\\n'",
+				"fi"
+			].join("\n"), { timeoutMs: 1e4 });
+			await assertExec(`${label} status probe`, probe);
+			const [state, rawExitCode] = probe.stdout.trim().split(/\s+/, 2);
+			if (state === "done") {
+				const exitCode = Number(rawExitCode);
+				if (!Number.isInteger(exitCode)) throw new Error(`${label} wrote an invalid exit status: ${JSON.stringify(rawExitCode)}`);
+				const stdout = await sandbox.shell(`cat ${quote(stdoutPath)} 2>/dev/null || true`, { timeoutMs: 1e4 });
+				const stderr = await sandbox.shell(`cat ${quote(stderrPath)} 2>/dev/null || true`, { timeoutMs: 1e4 });
+				await assertExec(`${label} stdout read`, stdout);
+				await assertExec(`${label} stderr read`, stderr);
+				return {
+					exitCode,
+					stdout: stdout.stdout,
+					stderr: stderr.stdout
+				};
+			}
+			if (state === "lost") throw new Error(`${label} guest process exited without a completion record`);
+			if (state === "starting" && Date.now() >= launchDeadline) throw new Error(`${label} guest process never initialized`);
+			if (state !== "running" && state !== "starting") throw new Error(`${label} returned an invalid guest state: ${JSON.stringify(state)}`);
+			await new Promise((resolve) => setTimeout(resolve, 1e3));
+		}
+		await sandbox.shell(`test ! -f ${quote(pidPath)} || kill \"$(cat ${quote(pidPath)})\" 2>/dev/null || true`, { timeoutMs: 1e4 }).catch(() => {});
+		throw new Error(`${label} exceeded its ${timeoutMs}ms guest execution deadline`);
+	} finally {
+		await sandbox.shell(`rm -rf ${quote(workDir)}`, { timeoutMs: 1e4 }).catch(() => {});
+	}
+}
+const FILES_STEP_SKIP_NAMES = new Set([".gitkeep", ".DS_Store"]);
+async function walkSourceDir(dir) {
+	const out = [];
+	async function visit(d) {
+		const entries = await readdir(d, { withFileTypes: true });
+		for (const entry of entries) {
+			const full = join(d, entry.name);
+			if (entry.isDirectory()) {
+				await visit(full);
+				continue;
+			}
+			if (!entry.isFile() || FILES_STEP_SKIP_NAMES.has(entry.name)) continue;
+			out.push({
+				relPath: relative(dir, full),
+				buf: await readFile(full)
+			});
+		}
+	}
+	await visit(dir);
+	return out;
+}
+async function applyFilesStep(sandbox, step, onLog) {
+	const walked = await walkSourceDir(step.sourceDir);
+	if (!walked.length) throw new Error(`files step: no files found under ${step.sourceDir}`);
+	const destination = step.destination.replace(/\/$/, "");
+	const batchSize = 50;
+	for (let i = 0; i < walked.length; i += batchSize) {
+		const batch = walked.slice(i, i + batchSize).map((f) => ({
+			path: `${destination}/${f.relPath}`,
+			content: f.buf,
+			mode: 420
+		}));
+		await sandbox.writeFiles(batch);
+	}
+	onLog(`files: wrote ${walked.length} files from ${step.sourceDir} to ${destination}`);
+}
 async function applyTemplate(sandbox, definition, onLog = () => {}) {
 	for (const [index, step] of definition.install.entries()) {
 		onLog(`install ${index + 1}/${definition.install.length}: ${step.kind}`);
+		if (step.kind === "files") {
+			await applyFilesStep(sandbox, step, onLog);
+			continue;
+		}
 		const compiled = compileStep(step);
-		await assertExec(`template step ${index + 1}`, await sandbox.shell(compiled.script, { timeoutMs: compiled.timeoutMs ?? 10 * 6e4 }));
+		const label = `template step ${index + 1}`;
+		await assertExec(label, await runTemplateStep(sandbox, label, compiled.script, compiled.timeoutMs ?? 10 * 6e4));
 	}
 	if (definition.start) await sandbox.writeFiles([{
 		path: "/home/user/.omg/template/bootstrap.sh",
@@ -215,14 +358,14 @@ async function applyTemplate(sandbox, definition, onLog = () => {}) {
 async function waitForSnapshotUpload(client, snapshot, timeoutMs = 10 * 6e4) {
 	const deadline = Date.now() + timeoutMs;
 	while (Date.now() < deadline) {
-		if ((await client.getSnapshot(snapshot.id)).uploadedToTigris) return;
+		const uploaded = await client.getSnapshot(snapshot.id);
+		if (uploaded.uploadedToTigris) return uploaded;
 		await new Promise((resolve) => setTimeout(resolve, 2e3));
 	}
 	throw new Error(`snapshot ${snapshot.id} was not uploaded within ${timeoutMs}ms`);
 }
 async function bakeTemplate(client, definition, options = {}) {
 	const log = options.onLog ?? (() => {});
-	const versionRef = templateVersionRef(definition);
 	const sandbox = await client.create({
 		ports: [...definition.ports ?? []],
 		skipAppProcesses: true,
@@ -233,19 +376,44 @@ async function bakeTemplate(client, definition, options = {}) {
 		await applyTemplate(sandbox, definition, log);
 		const snapshot = await sandbox.snapshot();
 		snapshotted = true;
-		await waitForSnapshotUpload(client, snapshot);
-		const runtime = templateRuntimeContract(definition, client.ownerId ? void 0 : versionRef);
-		await client.publishTemplate(versionRef, snapshot.id, runtime);
-		if (options.publishLatest !== false) await client.publishTemplate(definition.id, snapshot.id, runtime);
+		const rootfsSha = (await waitForSnapshotUpload(client, snapshot)).rootfsSha?.trim();
+		if (!rootfsSha) throw new Error(`snapshot ${snapshot.id} has no rootfsSha — cannot derive an immutable template version identity`);
+		const versionRef = templateContentVersionRef(definition, rootfsSha);
+		const publishClient = options.systemClient ?? client;
+		const runtime = templateRuntimeContract(definition, publishClient.ownerId ? void 0 : versionRef);
+		const existing = await resolveTemplateVersion(publishClient, versionRef);
+		if (existing) {
+			log(`version ${versionRef} already published (snapshot ${existing.snapshotId}) — reusing, this bake's snapshot is redundant`);
+			if (options.publishLatest !== false) await publishClient.publishTemplate(definition.id, existing.snapshotId, runtime);
+			await client.deleteSnapshot(snapshot.id).catch(() => {});
+			return {
+				templateId: definition.id,
+				versionRef,
+				definitionHash: templateDefinitionHash(definition),
+				snapshotId: existing.snapshotId,
+				reusedExisting: true
+			};
+		}
+		await publishClient.publishTemplate(versionRef, snapshot.id, runtime);
+		if (options.publishLatest !== false) await publishClient.publishTemplate(definition.id, snapshot.id, runtime);
 		return {
 			templateId: definition.id,
 			versionRef,
 			definitionHash: templateDefinitionHash(definition),
-			snapshotId: snapshot.id
+			snapshotId: snapshot.id,
+			reusedExisting: false
 		};
 	} finally {
 		if (!snapshotted) await sandbox.stop().catch(() => {});
 	}
 }
+async function resolveTemplateVersion(client, versionRef) {
+	try {
+		return await client.resolveTemplate(versionRef);
+	} catch (err) {
+		if (err instanceof SandboxApiError && err.status === 404) return void 0;
+		throw err;
+	}
+}
 //#endregion
-export { compileStartScript as a, download as c, templateRuntimeContract as d, templateVersionRef as f, assertTemplateId as h, check as i, run as l, SandboxClient as m, apt as n, compileStep as o, waitForSnapshotUpload as p, bakeTemplate as r, defineTemplate as s, applyTemplate as t, templateDefinitionHash as u };
+export { SandboxClient as _, compileStartScript as a, download as c, templateContentVersionRef as d, templateDefinitionHash as f, SandboxApiError as g, waitForSnapshotUpload as h, check as i, files as l, templateVersionRef as m, apt as n, compileStep as o, templateRuntimeContract as p, bakeTemplate as r, defineTemplate as s, applyTemplate as t, run as u, assertTemplateId as v };

package/dist/templates.mjs

@@ -1,2 +1,2 @@
-import { a as compileStartScript, c as download, d as templateRuntimeContract, f as templateVersionRef, i as check, l as run, n as apt, o as compileStep, p as waitForSnapshotUpload, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as templateDefinitionHash } from "./templates-CdQWcmOC.mjs";
-export { applyTemplate, apt, bakeTemplate, check, compileStartScript, compileStep, defineTemplate, download, run, templateDefinitionHash, templateRuntimeContract, templateVersionRef, waitForSnapshotUpload };
+import { a as compileStartScript, c as download, d as templateContentVersionRef, f as templateDefinitionHash, h as waitForSnapshotUpload, i as check, l as files, m as templateVersionRef, n as apt, o as compileStep, p as templateRuntimeContract, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as run } from "./templates-C3mBSGdT.mjs";
+export { applyTemplate, apt, bakeTemplate, check, compileStartScript, compileStep, defineTemplate, download, files, run, templateContentVersionRef, templateDefinitionHash, templateRuntimeContract, templateVersionRef, waitForSnapshotUpload };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omg-dev/sandbox",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "type": "module",
   "exports": {
     ".": {

package/src/__fixtures__/mini-template/nested/hello.txt

@@ -0,0 +1 @@
+hello from the fixture

package/src/__fixtures__/mini-template/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "mini-template-fixture",
+  "private": true
+}

package/src/client.test.ts

@@ -1,39 +1,104 @@
 import { describe, expect, test } from "bun:test";
 import { SandboxClient } from "./client";
-import { bakeTemplate, defineTemplate } from "./templates";
+import { bakeTemplate, defineTemplate, templateContentVersionRef, templateVersionRef } from "./templates";
+
+interface RecordedCall { method: string; path: string; body?: unknown; owner?: string | null }
+
+// Fake infra API for bake flows. Registry versions are immutable content-
+// addressed refs: GET on an unknown ref 404s (fresh publish), GET on a known
+// ref returns its snapshot (reuse path). POSTing an existing immutable ref
+// with a different snapshot would 409 in production — tests assert bakeTemplate
+// never attempts it.
+function fakeInfra(options: { existingVersions?: Record<string, string>; snapshotRootfsSha?: string | null } = {}) {
+  const calls: RecordedCall[] = [];
+  const existing = options.existingVersions ?? {};
+  const fakeFetch = (async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const url = new URL(String(input));
+    const method = init?.method ?? "GET";
+    const body = init?.body ? JSON.parse(String(init.body)) : undefined;
+    calls.push({ method, path: url.pathname, body, owner: new Headers(init?.headers).get("x-on-behalf-of") });
+    const json = (value: unknown, status = 200) => new Response(JSON.stringify(value), { status, headers: { "content-type": "application/json" } });
+    if (url.pathname === "/v1/sandboxes" && method === "POST") return json({ id: "sb-1" });
+    if (url.pathname.endsWith("/files")) return json({ ok: true });
+    if (url.pathname.endsWith("/snapshot")) return json({ id: "snap-1", sizeBytes: 42, createdAt: "2026-01-01T00:00:00Z" });
+    if (url.pathname === "/v1/snapshots/snap-1" && method === "GET") {
+      const snap: Record<string, unknown> = { id: "snap-1", sizeBytes: 42, createdAt: "2026-01-01T00:00:00Z", uploadedToTigris: true };
+      if (options.snapshotRootfsSha !== null) snap.rootfsSha = options.snapshotRootfsSha ?? "rootfs-sha-1";
+      return json(snap);
+    }
+    if (url.pathname === "/v1/snapshots/snap-1" && method === "DELETE") return new Response(null, { status: 204 });
+    const templateMatch = url.pathname.match(/^\/v1\/templates\/([^/]+)\/latest$/);
+    if (templateMatch && method === "GET") {
+      const snapshotId = existing[templateMatch[1]!];
+      if (!snapshotId) return json({ error: "template not found" }, 404);
+      return json({ templateId: templateMatch[1], snapshotId });
+    }
+    if (templateMatch && method === "POST") return json({ ok: true });
+    throw new Error(`unexpected ${method} ${url.pathname}`);
+  }) as typeof fetch;
+  return { calls, fakeFetch };
+}
+
+describe("template version identity", () => {
+  const definition = defineTemplate({
+    id: "my-agent",
+    version: "3",
+    title: "Mine",
+    install: [],
+  });
+
+  test("content ref covers definition AND base rootfs", () => {
+    const ref = templateContentVersionRef(definition, "rootfs-sha-1");
+    expect(ref).toMatch(/^my-agent-v3-[0-9a-f]{8}$/);
+    // Deterministic for identical inputs — identical content resolves to the
+    // same immutable version instead of minting duplicates.
+    expect(templateContentVersionRef(definition, "rootfs-sha-1")).toBe(ref);
+    // A rootfs change (same catalog definition) MUST mint a new identity —
+    // this is the exact collision that 409ed the Jul-18 rebake, where the
+    // static <id>-v<version> ref could not express a base-image change.
+    expect(templateContentVersionRef(definition, "rootfs-sha-2")).not.toBe(ref);
+    // A definition change also mints a new identity.
+    const bumped = defineTemplate({ ...definition, title: "Mine v2" });
+    expect(templateContentVersionRef(bumped, "rootfs-sha-1")).not.toBe(ref);
+  });
+
+  test("empty content key fails loud instead of falling back to the static ref", () => {
+    expect(() => templateContentVersionRef(definition, "")).toThrow(/content key/);
+    expect(() => templateContentVersionRef(definition, "   ")).toThrow(/content key/);
+  });
+
+  test("long ids truncate to fit the 40-char registry limit", () => {
+    const long = defineTemplate({ id: "a".repeat(40), version: "12", title: "Long", install: [] });
+    const ref = templateContentVersionRef(long, "rootfs-sha-1");
+    expect(ref.length).toBeLessThanOrEqual(40);
+    expect(ref).toMatch(/-v12-[0-9a-f]{8}$/);
+    expect(templateVersionRef(long).length).toBeLessThanOrEqual(40);
+  });
+});
 
 describe("SandboxClient template bake", () => {
   test("attributes ownership and publishes private version plus latest pointers", async () => {
-    const calls: Array<{ method: string; path: string; body?: unknown; owner?: string | null }> = [];
-    const fakeFetch = (async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
-      const url = new URL(String(input));
-      const body = init?.body ? JSON.parse(String(init.body)) : undefined;
-      calls.push({ method: init?.method ?? "GET", path: url.pathname, body, owner: new Headers(init?.headers).get("x-on-behalf-of") });
-      const json = (value: unknown) => new Response(JSON.stringify(value), { status: 200, headers: { "content-type": "application/json" } });
-      if (url.pathname === "/v1/sandboxes" && init?.method === "POST") return json({ id: "sb-1" });
-      if (url.pathname.endsWith("/files")) return json({ ok: true });
-      if (url.pathname.endsWith("/snapshot")) return json({ id: "snap-1", sizeBytes: 42, createdAt: "2026-01-01T00:00:00Z" });
-      if (url.pathname === "/v1/snapshots/snap-1") return json({ id: "snap-1", sizeBytes: 42, createdAt: "2026-01-01T00:00:00Z", uploadedToTigris: true });
-      if (url.pathname.startsWith("/v1/templates/")) return json({ ok: true });
-      throw new Error(`unexpected ${init?.method} ${url.pathname}`);
-    }) as typeof fetch;
+    const { calls, fakeFetch } = fakeInfra();
     const client = new SandboxClient({ baseUrl: "https://infra.example", token: "secret", ownerId: "user-123", fetch: fakeFetch });
-    const result = await bakeTemplate(client, defineTemplate({
+    const definition = defineTemplate({
       id: "my-agent",
       version: "3",
       title: "Mine",
       ports: [8766],
       install: [],
       start: { command: "bun start", readiness: { port: 8766, path: "/health" } },
-    }));
-    expect(result.versionRef).toBe("my-agent-v3");
+    });
+    const expectedRef = templateContentVersionRef(definition, "rootfs-sha-1");
+    const result = await bakeTemplate(client, definition);
+    expect(result.versionRef).toBe(expectedRef);
+    expect(result.reusedExisting).toBe(false);
     expect(calls.every((call) => call.owner === "user-123")).toBe(true);
-    expect(calls.filter((call) => call.path.includes("/v1/templates/")).map((call) => call.path)).toEqual([
-      "/v1/templates/my-agent-v3/latest",
+    expect(calls.filter((call) => call.path.includes("/v1/templates/") && call.method === "POST").map((call) => call.path)).toEqual([
+      `/v1/templates/${expectedRef}/latest`,
       "/v1/templates/my-agent/latest",
     ]);
     expect(calls[0]?.body).toEqual({ ports: [8766], skipAppProcesses: true, projectSlug: "my-agent" });
-    expect(calls.filter((call) => call.path.includes("/v1/templates/")).map((call) => call.body)).toEqual([
+    expect(calls.filter((call) => call.path.includes("/v1/templates/") && call.method === "POST").map((call) => call.body)).toEqual([
       {
         snapshotId: "snap-1",
         startCommand: "exec /home/user/.omg/template/bootstrap.sh",
@@ -50,4 +115,46 @@ describe("SandboxClient template bake", () => {
       },
     ]);
   });
+
+  test("systemClient publishes the registry entries unscoped even when the sandbox-lifecycle client carries an ownerId", async () => {
+    const { calls, fakeFetch } = fakeInfra();
+    const client = new SandboxClient({ baseUrl: "https://infra.example", token: "secret", ownerId: "svc:template-builder", fetch: fakeFetch });
+    const systemClient = new SandboxClient({ baseUrl: "https://infra.example", token: "secret", fetch: fakeFetch });
+    await bakeTemplate(client, defineTemplate({
+      id: "my-agent",
+      version: "3",
+      title: "Mine",
+      install: [],
+    }), { systemClient });
+    const sandboxCalls = calls.filter((call) => !call.path.includes("/v1/templates/"));
+    const templateCalls = calls.filter((call) => call.path.includes("/v1/templates/"));
+    expect(sandboxCalls.every((call) => call.owner === "svc:template-builder")).toBe(true);
+    expect(templateCalls.every((call) => call.owner === null)).toBe(true);
+  });
+
+  test("an already-published content identity is reused: latest repoints, the immutable version is never republished", async () => {
+    const definition = defineTemplate({ id: "my-agent", version: "3", title: "Mine", install: [] });
+    const ref = templateContentVersionRef(definition, "rootfs-sha-1");
+    const { calls, fakeFetch } = fakeInfra({ existingVersions: { [ref]: "snap-old" } });
+    const client = new SandboxClient({ baseUrl: "https://infra.example", token: "secret", ownerId: "user-123", fetch: fakeFetch });
+    const result = await bakeTemplate(client, definition);
+    expect(result.reusedExisting).toBe(true);
+    expect(result.versionRef).toBe(ref);
+    expect(result.snapshotId).toBe("snap-old");
+    const publishes = calls.filter((call) => call.path.includes("/v1/templates/") && call.method === "POST");
+    // Never POSTs the immutable ref (would 409); only the mutable latest
+    // pointer moves, and it moves to the EXISTING version's snapshot so
+    // latest and the immutable ref stay consistent.
+    expect(publishes.map((call) => call.path)).toEqual(["/v1/templates/my-agent/latest"]);
+    expect(publishes[0]?.body).toMatchObject({ snapshotId: "snap-old" });
+    // The redundant duplicate snapshot from this bake is cleaned up.
+    expect(calls.some((call) => call.method === "DELETE" && call.path === "/v1/snapshots/snap-1")).toBe(true);
+  });
+
+  test("missing rootfsSha fails loud instead of publishing a collision-prone static ref", async () => {
+    const { fakeFetch } = fakeInfra({ snapshotRootfsSha: null });
+    const client = new SandboxClient({ baseUrl: "https://infra.example", token: "secret", ownerId: "user-123", fetch: fakeFetch });
+    await expect(bakeTemplate(client, defineTemplate({ id: "my-agent", version: "3", title: "Mine", install: [] })))
+      .rejects.toThrow(/rootfsSha/);
+  });
 });

package/src/client.ts

@@ -25,6 +25,20 @@ export interface Snapshot {
   sizeBytes: number;
   createdAt: string;
   uploadedToTigris?: boolean;
+  /** sha256 of the base rootfs the source sandbox was created from. */
+  rootfsSha?: string;
+}
+
+/** Error thrown by SandboxClient.request carrying the HTTP status, so callers
+ * can branch on well-defined statuses (e.g. 404 template probe) instead of
+ * string-matching error messages. */
+export class SandboxApiError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "SandboxApiError";
+    this.status = status;
+  }
 }
 
 export interface CreateSandboxOptions {
@@ -98,7 +112,7 @@ export class SandboxClient {
       const detail = parsed && typeof parsed === "object" && "error" in parsed
         ? String((parsed as { error: unknown }).error)
         : text || `HTTP ${response.status}`;
-      throw new Error(`sandbox API ${method} ${path}: ${response.status} ${detail}`);
+      throw new SandboxApiError(`sandbox API ${method} ${path}: ${response.status} ${detail}`, response.status);
     }
     return parsed as T;
   }
@@ -112,6 +126,10 @@ export class SandboxClient {
     return this.request("GET", `/v1/snapshots/${encodeURIComponent(id)}`);
   }
 
+  async deleteSnapshot(id: string): Promise<void> {
+    await this.request("DELETE", `/v1/snapshots/${encodeURIComponent(id)}`);
+  }
+
   async publishTemplate(templateId: string, snapshotId: string, runtime?: TemplateRuntimeContract): Promise<void> {
     const id = assertTemplateId(templateId);
     await this.request("POST", `/v1/templates/${id}/latest`, { snapshotId, ...runtime });

package/src/templates.test.ts

@@ -1,6 +1,30 @@
 import { describe, expect, test } from "bun:test";
-import { apt, check, compileStartScript, compileStep, defineTemplate, download, run, templateRuntimeContract, templateVersionRef } from "./templates";
+import { join } from "node:path";
+import { applyTemplate, apt, check, compileStartScript, compileStep, defineTemplate, download, files, run, templateRuntimeContract, templateVersionRef } from "./templates";
 import { agentTemplates } from "../../../templates/agent-catalog";
+import type { Sandbox } from "./client";
+
+const FIXTURE_DIR = join(import.meta.dirname, "__fixtures__", "mini-template");
+
+function fakeSandbox(): Sandbox & { writeBatches: Array<Array<{ path: string; content: Uint8Array | string; mode?: number }>>; shellCalls: string[] } {
+  const writeBatches: Array<Array<{ path: string; content: Uint8Array | string; mode?: number }>> = [];
+  const shellCalls: string[] = [];
+  return {
+    id: "fake",
+    writeBatches,
+    shellCalls,
+    exec: async () => ({ stdout: "", stderr: "", exitCode: 0 }),
+    shell: async (script: string) => {
+      shellCalls.push(script);
+      return { stdout: "", stderr: "", exitCode: 0 };
+    },
+    writeFiles: async (batch) => {
+      writeBatches.push(batch);
+    },
+    snapshot: async () => ({ id: "snap", sizeBytes: 0, createdAt: new Date(0).toISOString() }),
+    stop: async () => {},
+  };
+}
 
 describe("sandbox templates", () => {
   test("defines a typed, immutable versioned template", () => {
@@ -23,19 +47,128 @@ describe("sandbox templates", () => {
     expect(() => compileStep(run({ command: "true", env: { "BAD-NAME": "x" } }))).toThrow("invalid environment variable");
   });
 
+  test("files.copy requires non-empty sourceDir/destination", () => {
+    expect(() => files.copy({ sourceDir: "", destination: "/home/user/app" })).toThrow("sourceDir");
+    expect(() => files.copy({ sourceDir: "/tmp/x", destination: "" })).toThrow("destination");
+  });
+
+  test("compileStep rejects files steps — they are applied, not compiled", () => {
+    expect(() => compileStep(files.copy({ sourceDir: "/tmp/x", destination: "/home/user/app" }))).toThrow("applyTemplate");
+  });
+
+  test("applyTemplate copies a local directory into the sandbox via writeFiles, skipping .gitkeep", async () => {
+    const sandbox = fakeSandbox();
+    const definition = defineTemplate({
+      id: "files-fixture",
+      version: "1",
+      title: "files fixture",
+      install: [files.copy({ sourceDir: FIXTURE_DIR, destination: "/home/user/app/" })],
+    });
+    await applyTemplate(sandbox, definition);
+    // applyTemplate also writes the manifest (definition.json) after every
+    // install step — the files-step batch is whichever call carries our
+    // fixture's paths.
+    const scaffoldBatch = sandbox.writeBatches.find((batch) => batch.some((f) => f.path.startsWith("/home/user/app/")));
+    expect(scaffoldBatch).toBeDefined();
+    const paths = scaffoldBatch!.map((f) => f.path).sort();
+    expect(paths).toEqual(["/home/user/app/nested/hello.txt", "/home/user/app/package.json"]);
+    // trailing slash on destination is normalized, not doubled
+    expect(paths.every((p) => !p.includes("//"))).toBe(true);
+  });
+
+  test("applyTemplate throws loud when a files step's sourceDir has no files", async () => {
+    const sandbox = fakeSandbox();
+    const definition = defineTemplate({
+      id: "empty-fixture",
+      version: "1",
+      title: "empty fixture",
+      install: [files.copy({ sourceDir: join(FIXTURE_DIR, "nested", "does-not-exist"), destination: "/home/user/app" })],
+    });
+    await expect(applyTemplate(sandbox, definition)).rejects.toThrow();
+  });
+
+  test("applyTemplate runs install commands out of band from the CDN request window", async () => {
+    const calls: Array<{ script: string; detached?: boolean }> = [];
+    const writes: Array<Array<{ path: string; content: Uint8Array | string; mode?: number }>> = [];
+    const sandbox: Sandbox = {
+      id: "fake",
+      exec: async () => ({ stdout: "", stderr: "", exitCode: 0 }),
+      shell: async (script, options = {}) => {
+        calls.push({ script, detached: options.detached });
+        if (options.detached) return { stdout: "", stderr: "", exitCode: 0, commandId: "cmd-1" };
+        if (script.includes("printf 'done")) return { stdout: "done\n0\n", stderr: "", exitCode: 0 };
+        if (script.includes("/stdout")) return { stdout: "installed\n", stderr: "", exitCode: 0 };
+        if (script.includes("/stderr")) return { stdout: "", stderr: "", exitCode: 0 };
+        return { stdout: "", stderr: "", exitCode: 0 };
+      },
+      writeFiles: async (batch) => { writes.push(batch); },
+      snapshot: async () => ({ id: "snap", sizeBytes: 0, createdAt: new Date(0).toISOString() }),
+      stop: async () => {},
+    };
+
+    await applyTemplate(sandbox, defineTemplate({
+      id: "async-install",
+      version: "1",
+      title: "async install",
+      install: [run({ command: "sleep 120 && echo installed" })],
+    }));
+
+    const detached = calls.find((call) => call.detached);
+    expect(detached).toBeDefined();
+    expect(detached?.script).toContain("sleep 120 && echo installed");
+    expect(calls.some((call) => call.script.includes("printf 'done"))).toBe(true);
+    expect(calls.some((call) => call.script.includes("printf 'starting"))).toBe(true);
+    expect(writes.some((batch) => batch.some((file) => file.path.endsWith("definition.json")))).toBe(true);
+  });
+
+  test("applyTemplate preserves a detached install's failing exit status and stderr", async () => {
+    const sandbox = fakeSandbox();
+    sandbox.shell = async (script, options = {}) => {
+      if (options.detached) return { stdout: "", stderr: "", exitCode: 0, commandId: "cmd-2" };
+      if (script.includes("printf 'done")) return { stdout: "done\n42\n", stderr: "", exitCode: 0 };
+      if (script.includes("/stdout")) return { stdout: "", stderr: "", exitCode: 0 };
+      if (script.includes("/stderr")) return { stdout: "package exploded\n", stderr: "", exitCode: 0 };
+      return { stdout: "", stderr: "", exitCode: 0 };
+    };
+
+    await expect(applyTemplate(sandbox, defineTemplate({
+      id: "async-failure",
+      version: "1",
+      title: "async failure",
+      install: [run({ command: "exit 42" })],
+    }))).rejects.toThrow("package exploded");
+  });
+
   test("LFG owns every runtime dependency and zero-config transport default", () => {
     const lfg = agentTemplates.lfg;
-    expect(templateVersionRef(lfg)).toBe("agent-lfg-v10");
+    expect(templateVersionRef(lfg)).toBe("agent-lfg-v17");
     expect(lfg.install).toContainEqual(apt.packages(["tmux"]));
     expect(lfg.checks).toContainEqual(check.command("tmux"));
     expect(lfg.start?.env?.LIVE_TRANSPORT).toBe("ws");
     expect(lfg.start?.readiness?.port).toBe(8766);
     expect(templateRuntimeContract(lfg, templateVersionRef(lfg))).toEqual({
-      immutableRef: "agent-lfg-v10",
+      immutableRef: "agent-lfg-v17",
       startCommand: "exec /home/user/.omg/template/bootstrap.sh",
       readinessPort: 8766,
       readinessPath: "/",
-      ports: [8766],
+      ports: [8766, 5173],
     });
   });
+
+  test("LFG bakes the react-ts scaffold into /home/user/project at bake time", () => {
+    const lfg = agentTemplates.lfg;
+    const filesSteps = lfg.install.filter((step) => step.kind === "files");
+    expect(filesSteps).toHaveLength(1);
+    const scaffold = filesSteps[0] as Extract<(typeof filesSteps)[number], { kind: "files" }>;
+    expect(scaffold.destination).toBe("/home/user/project");
+    expect(scaffold.sourceDir.endsWith(join("templates", "react-ts"))).toBe(true);
+    // recipe.sh (shadcn init) must run against the baked scaffold, not just
+    // land on disk unused — otherwise Computers still improvise shadcn init
+    // on first turn and the whole point of baking is lost.
+    const commands = lfg.install
+      .filter((step): step is Extract<typeof step, { kind: "run" }> => step.kind === "run")
+      .map((step) => step.command);
+    expect(commands.some((c) => c.includes("recipe.sh"))).toBe(true);
+    expect(lfg.metadata?.lfgRelease).toBe("v0.1.40");
+  });
 });

package/src/templates.ts

@@ -1,11 +1,21 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
 import type { Sandbox, SandboxClient, Snapshot } from "./client.js";
-import { assertTemplateId } from "./client.js";
+import { assertTemplateId, SandboxApiError } from "./client.js";
 
 export type TemplateStep =
   | { kind: "apt"; packages: readonly string[] }
   | { kind: "archive"; url: string; destination: string; stripComponents?: number }
-  | { kind: "run"; command: string; cwd?: string; user?: string; env?: Record<string, string>; timeoutMs?: number };
+  | { kind: "run"; command: string; cwd?: string; user?: string; env?: Record<string, string>; timeoutMs?: number }
+  // Copies a local directory (resolved by the caller at definition-authoring
+  // time — e.g. templates/react-ts) into the sandbox at bake time. Unlike the
+  // other steps this is NOT a shell script: compileStep() rejects it, and
+  // applyTemplate() special-cases it to walk sourceDir on the local
+  // filesystem (the bake runs from a full monorepo checkout) and batch
+  // sandbox.writeFiles() calls, same pattern as build-template.ts's own
+  // walkTemplate/writeFilesBatched for the legacy (non-typed) templates.
+  | { kind: "files"; sourceDir: string; destination: string };
 
 export type TemplateCheck =
   | { kind: "command"; command: string; user?: string }
@@ -36,6 +46,10 @@ export interface BakeResult {
   versionRef: string;
   definitionHash: string;
   snapshotId: string;
+  /** True when this exact content identity (definition + base rootfs) was
+   * already published: the existing immutable version was reused and no new
+   * registry version was created. */
+  reusedExisting: boolean;
 }
 
 export const apt = {
@@ -56,6 +70,14 @@ export function run(options: Omit<Extract<TemplateStep, { kind: "run" }>, "kind"
   return { kind: "run", ...options };
 }
 
+export const files = {
+  copy(options: { sourceDir: string; destination: string }): TemplateStep {
+    if (!options.sourceDir.trim()) throw new Error("files.copy requires a sourceDir");
+    if (!options.destination.trim()) throw new Error("files.copy requires a destination");
+    return { kind: "files", ...options };
+  },
+};
+
 export const check = {
   command(command: string, options: { user?: string } = {}): TemplateCheck {
     return { kind: "command", command, ...options };
@@ -73,11 +95,38 @@ export function defineTemplate<const T extends SandboxTemplate>(definition: T):
   return Object.freeze(definition);
 }
 
-export function templateVersionRef(definition: SandboxTemplate): string {
-  const suffix = `-v${definition.version.toLowerCase().replace(/[^a-z0-9-]+/g, "-")}`;
+function refWithSuffix(id: string, suffix: string): string {
   const maxBase = 40 - suffix.length;
   if (maxBase < 2) throw new Error("template id and version are too long for registry");
-  return assertTemplateId(`${definition.id.slice(0, maxBase).replace(/-+$/, "")}${suffix}`);
+  return assertTemplateId(`${id.slice(0, maxBase).replace(/-+$/, "")}${suffix}`);
+}
+
+export function templateVersionRef(definition: SandboxTemplate): string {
+  return refWithSuffix(definition.id, `-v${definition.version.toLowerCase().replace(/[^a-z0-9-]+/g, "-")}`);
+}
+
+// templateContentVersionRef is the identity a bake publishes as its immutable
+// registry version: <id>-v<version>-<hash8>, where the hash covers BOTH the
+// template definition and the base image the bake ran on (contentKey — the
+// snapshot's rootfsSha). Registry versions are immutable, so the ref MUST
+// change whenever the baked content can differ. The hand-bumped catalog
+// `version` alone cannot express that: a rootfs/agent change alters every
+// bake's output without touching the catalog, and republishing the same
+// static ref (e.g. agent-claude-v2) with a new snapshot is a 409 immutability
+// violation by design. Content-addressing the ref makes that collision
+// structurally impossible — new content → new ref; identical content → same
+// ref, which bakeTemplate resolves and reuses instead of republishing.
+export function templateContentVersionRef(definition: SandboxTemplate, contentKey: string): string {
+  if (!contentKey.trim()) {
+    // No silent fallback to the static ref: an empty content key would revert
+    // to exactly the colliding identity this function exists to prevent.
+    throw new Error("template content key (base rootfs sha) is required");
+  }
+  const hash = createHash("sha256")
+    .update(`${templateDefinitionHash(definition)}\n${contentKey.trim()}`)
+    .digest("hex")
+    .slice(0, 8);
+  return refWithSuffix(definition.id, `-v${definition.version.toLowerCase().replace(/[^a-z0-9-]+/g, "-")}-${hash}`);
 }
 
 export function templateDefinitionHash(definition: SandboxTemplate): string {
@@ -96,10 +145,21 @@ export function templateRuntimeContract(definition: SandboxTemplate, immutableRe
 
 function quote(value: string): string { return `'${value.replaceAll("'", `'\"'\"'`)}'`; }
 
+// Manager.Exec (apps/infra) injects the platform LLM-proxy vars into every
+// exec call's own root-level env, but "sudo -u <user>" resets the
+// environment by default and (absent this) only HOME/PATH were forwarded —
+// a template's `start` command (e.g. lfg's pi backend) would otherwise see
+// real-Anthropic 401s instead of the sandbox proxy. Forwarding them as
+// literal VAR=value args to env(1) is not "preserving" the invoking shell's
+// env (which sudoers' env_reset would still block) — it is env(1) itself
+// setting them in the de-privileged child, which needs no sudoers policy.
+const PROXY_ENV_VARS = ["OMG_AI_URL", "ANTHROPIC_BASE_URL", "ANTHROPIC_API_KEY", "OPENAI_BASE_URL", "OPENAI_API_KEY", "OMG_MEDIA_URL"];
+
 function commandForUser(command: string, user?: string): string {
   if (!user) return `/bin/bash -lc ${quote(command)}`;
   const home = user === "root" ? "/root" : `/home/${user}`;
-  return `sudo -u ${quote(user)} -H env HOME=${quote(home)} PATH=${quote(`${home}/.bun/bin:/usr/local/bin:/usr/bin:/bin`)} /bin/bash -c ${quote(command)}`;
+  const proxyEnv = PROXY_ENV_VARS.map((name) => `${name}="\${${name}:-}"`).join(" ");
+  return `sudo -u ${quote(user)} -H env HOME=${quote(home)} PATH=${quote(`${home}/.bun/bin:/usr/local/bin:/usr/bin:/bin`)} ${proxyEnv} /bin/bash -c ${quote(command)}`;
 }
 
 function shellEnvAssignments(env: Record<string, string>): string[] {
@@ -110,6 +170,9 @@ function shellEnvAssignments(env: Record<string, string>): string[] {
 }
 
 export function compileStep(step: TemplateStep): { script: string; timeoutMs?: number } {
+  if (step.kind === "files") {
+    throw new Error("files steps transfer local content and are applied via applyTemplate(), not compileStep()");
+  }
   if (step.kind === "apt") {
     return { script: `set -euo pipefail\napt-get update -qq\nDEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends ${step.packages.map(quote).join(" ")}\nrm -rf /var/lib/apt/lists/*` };
   }
@@ -140,11 +203,127 @@ async function assertExec(label: string, result: { exitCode: number; stdout: str
   if (result.exitCode !== 0) throw new Error(`${label} failed (${result.exitCode}): ${(result.stderr || result.stdout).trim().slice(-1200)}`);
 }
 
+// Template installs routinely outlive Cloudflare's request window (apt and
+// package-manager steps can take several minutes). A blocking /exec request
+// therefore makes a healthy guest look failed with a 524. Launch the command
+// inside the guest and make its on-disk completion record the authority; every
+// control-plane request below is short and bounded, while exit status and logs
+// still fail loud exactly once.
+async function runTemplateStep(
+  sandbox: Sandbox,
+  label: string,
+  script: string,
+  timeoutMs: number,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const workDir = `/tmp/omg-template-step-${randomUUID()}`;
+  const pidPath = `${workDir}/pid`;
+  const statusPath = `${workDir}/status`;
+  const stdoutPath = `${workDir}/stdout`;
+  const stderrPath = `${workDir}/stderr`;
+  const wrapper = [
+    "set -u",
+    `mkdir -p ${quote(workDir)}`,
+    `printf '%s\\n' \"$$\" > ${quote(pidPath)}`,
+    `set +e; /bin/bash -lc ${quote(script)} > ${quote(stdoutPath)} 2> ${quote(stderrPath)}`,
+    "code=$?",
+    `printf '%s\\n' \"$code\" > ${quote(`${statusPath}.tmp`)}`,
+    `mv ${quote(`${statusPath}.tmp`)} ${quote(statusPath)}`,
+    "exit \"$code\"",
+  ].join("\n");
+
+  const prepared = await sandbox.shell(`mkdir -p ${quote(workDir)}`, { timeoutMs: 10_000 });
+  await assertExec(`${label} workspace preparation`, prepared);
+  const deadline = Date.now() + timeoutMs;
+  const launchDeadline = Math.min(deadline, Date.now() + 10_000);
+  try {
+    const started = await sandbox.shell(wrapper, { detached: true });
+    if (!started.commandId) throw new Error(`${label} did not start as a detached guest command`);
+    while (Date.now() < deadline) {
+      const probe = await sandbox.shell([
+        `if test -f ${quote(statusPath)}; then`,
+        "  printf 'done\\n'",
+        `  cat ${quote(statusPath)}`,
+        `elif test -f ${quote(pidPath)} && kill -0 \"$(cat ${quote(pidPath)})\" 2>/dev/null; then`,
+        "  printf 'running\\n'",
+        `elif test ! -f ${quote(pidPath)}; then`,
+        "  printf 'starting\\n'",
+        "else",
+        "  printf 'lost\\n'",
+        "fi",
+      ].join("\n"), { timeoutMs: 10_000 });
+      await assertExec(`${label} status probe`, probe);
+      const [state, rawExitCode] = probe.stdout.trim().split(/\s+/, 2);
+      if (state === "done") {
+        const exitCode = Number(rawExitCode);
+        if (!Number.isInteger(exitCode)) throw new Error(`${label} wrote an invalid exit status: ${JSON.stringify(rawExitCode)}`);
+        const stdout = await sandbox.shell(`cat ${quote(stdoutPath)} 2>/dev/null || true`, { timeoutMs: 10_000 });
+        const stderr = await sandbox.shell(`cat ${quote(stderrPath)} 2>/dev/null || true`, { timeoutMs: 10_000 });
+        await assertExec(`${label} stdout read`, stdout);
+        await assertExec(`${label} stderr read`, stderr);
+        return { exitCode, stdout: stdout.stdout, stderr: stderr.stdout };
+      }
+      if (state === "lost") throw new Error(`${label} guest process exited without a completion record`);
+      if (state === "starting" && Date.now() >= launchDeadline) throw new Error(`${label} guest process never initialized`);
+      if (state !== "running" && state !== "starting") throw new Error(`${label} returned an invalid guest state: ${JSON.stringify(state)}`);
+      await new Promise((resolve) => setTimeout(resolve, 1_000));
+    }
+    await sandbox.shell(`test ! -f ${quote(pidPath)} || kill \"$(cat ${quote(pidPath)})\" 2>/dev/null || true`, { timeoutMs: 10_000 }).catch(() => {});
+    throw new Error(`${label} exceeded its ${timeoutMs}ms guest execution deadline`);
+  } finally {
+    await sandbox.shell(`rm -rf ${quote(workDir)}`, { timeoutMs: 10_000 }).catch(() => {});
+  }
+}
+
+const FILES_STEP_SKIP_NAMES = new Set([".gitkeep", ".DS_Store"]);
+
+async function walkSourceDir(dir: string): Promise<Array<{ relPath: string; buf: Buffer }>> {
+  const out: Array<{ relPath: string; buf: Buffer }> = [];
+  async function visit(d: string): Promise<void> {
+    const entries = await readdir(d, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) {
+        await visit(full);
+        continue;
+      }
+      if (!entry.isFile() || FILES_STEP_SKIP_NAMES.has(entry.name)) continue;
+      out.push({ relPath: relative(dir, full), buf: await readFile(full) });
+    }
+  }
+  await visit(dir);
+  return out;
+}
+
+async function applyFilesStep(
+  sandbox: Sandbox,
+  step: Extract<TemplateStep, { kind: "files" }>,
+  onLog: (line: string) => void,
+): Promise<void> {
+  const walked = await walkSourceDir(step.sourceDir);
+  if (!walked.length) throw new Error(`files step: no files found under ${step.sourceDir}`);
+  const destination = step.destination.replace(/\/$/, "");
+  const batchSize = 50;
+  for (let i = 0; i < walked.length; i += batchSize) {
+    const batch = walked.slice(i, i + batchSize).map((f) => ({
+      path: `${destination}/${f.relPath}`,
+      content: f.buf,
+      mode: 0o644,
+    }));
+    await sandbox.writeFiles(batch);
+  }
+  onLog(`files: wrote ${walked.length} files from ${step.sourceDir} to ${destination}`);
+}
+
 export async function applyTemplate(sandbox: Sandbox, definition: SandboxTemplate, onLog: (line: string) => void = () => {}): Promise<void> {
   for (const [index, step] of definition.install.entries()) {
     onLog(`install ${index + 1}/${definition.install.length}: ${step.kind}`);
+    if (step.kind === "files") {
+      await applyFilesStep(sandbox, step, onLog);
+      continue;
+    }
     const compiled = compileStep(step);
-    await assertExec(`template step ${index + 1}`, await sandbox.shell(compiled.script, { timeoutMs: compiled.timeoutMs ?? 10 * 60_000 }));
+    const label = `template step ${index + 1}`;
+    await assertExec(label, await runTemplateStep(sandbox, label, compiled.script, compiled.timeoutMs ?? 10 * 60_000));
   }
   if (definition.start) {
     await sandbox.writeFiles([{ path: "/home/user/.omg/template/bootstrap.sh", content: compileStartScript(definition.start), mode: 0o755 }]);
@@ -157,33 +336,76 @@ export async function applyTemplate(sandbox: Sandbox, definition: SandboxTemplat
   }
 }
 
-export async function waitForSnapshotUpload(client: SandboxClient, snapshot: Snapshot, timeoutMs = 10 * 60_000): Promise<void> {
+export async function waitForSnapshotUpload(client: SandboxClient, snapshot: Snapshot, timeoutMs = 10 * 60_000): Promise<Snapshot> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    if ((await client.getSnapshot(snapshot.id)).uploadedToTigris) return;
+    const uploaded = await client.getSnapshot(snapshot.id);
+    if (uploaded.uploadedToTigris) return uploaded;
     await new Promise((resolve) => setTimeout(resolve, 2_000));
   }
   throw new Error(`snapshot ${snapshot.id} was not uploaded within ${timeoutMs}ms`);
 }
 
-export async function bakeTemplate(client: SandboxClient, definition: SandboxTemplate, options: { onLog?: (line: string) => void; publishLatest?: boolean } = {}): Promise<BakeResult> {
+export async function bakeTemplate(
+  client: SandboxClient,
+  definition: SandboxTemplate,
+  options: { onLog?: (line: string) => void; publishLatest?: boolean; systemClient?: SandboxClient } = {},
+): Promise<BakeResult> {
   const log = options.onLog ?? (() => {});
-  const versionRef = templateVersionRef(definition);
   const sandbox = await client.create({ ports: [...(definition.ports ?? [])], skipAppProcesses: true, projectSlug: definition.id });
   let snapshotted = false;
   try {
     await applyTemplate(sandbox, definition, log);
     const snapshot = await sandbox.snapshot();
     snapshotted = true;
-    await waitForSnapshotUpload(client, snapshot);
+    const uploaded = await waitForSnapshotUpload(client, snapshot);
+    // The immutable version ref is content-addressed: definition hash + the
+    // base rootfs the bake actually ran on (recorded on the snapshot). See
+    // templateContentVersionRef — this is what lets a rootfs/agent-triggered
+    // rebake mint a NEW version instead of 409ing against the previous one.
+    // Fail loud if the API did not report a rootfs sha; falling back to the
+    // static <id>-v<version> ref would reintroduce the collision.
+    const rootfsSha = uploaded.rootfsSha?.trim();
+    if (!rootfsSha) throw new Error(`snapshot ${snapshot.id} has no rootfsSha — cannot derive an immutable template version identity`);
+    const versionRef = templateContentVersionRef(definition, rootfsSha);
     // A client with ownerId acts on behalf of a user and publishes into that
     // user's private namespace. Only the direct service client may mark a
-    // global system version immutable.
-    const runtime = templateRuntimeContract(definition, client.ownerId ? undefined : versionRef);
-    await client.publishTemplate(versionRef, snapshot.id, runtime);
-    if (options.publishLatest !== false) await client.publishTemplate(definition.id, snapshot.id, runtime);
-    return { templateId: definition.id, versionRef, definitionHash: templateDefinitionHash(definition), snapshotId: snapshot.id };
+    // global system version immutable. `client` may need an ownerId just to
+    // pass the sandbox-ownership check on create/exec/snapshot (a bare
+    // service-token call with no owner has caller="" and 403s there) — that
+    // is orthogonal to whether THIS bake should publish globally. Callers
+    // baking an official, system-wide catalog template (not a private/scoped
+    // one) pass options.systemClient (no ownerId) so the registry publish
+    // itself lands in the global namespace regardless of what identity was
+    // needed upstream for the sandbox lifecycle calls.
+    const publishClient = options.systemClient ?? client;
+    const runtime = templateRuntimeContract(definition, publishClient.ownerId ? undefined : versionRef);
+    // Same content identity already published (an unchanged re-run, or a
+    // partially-failed run being re-executed after some templates landed):
+    // registry versions are immutable, so NEVER republish the ref. Reuse the
+    // existing version's snapshot — repoint only the mutable latest pointer
+    // at it, and drop this run's redundant duplicate snapshot (best-effort;
+    // an orphan is only storage, never correctness).
+    const existing = await resolveTemplateVersion(publishClient, versionRef);
+    if (existing) {
+      log(`version ${versionRef} already published (snapshot ${existing.snapshotId}) — reusing, this bake's snapshot is redundant`);
+      if (options.publishLatest !== false) await publishClient.publishTemplate(definition.id, existing.snapshotId, runtime);
+      await client.deleteSnapshot(snapshot.id).catch(() => {});
+      return { templateId: definition.id, versionRef, definitionHash: templateDefinitionHash(definition), snapshotId: existing.snapshotId, reusedExisting: true };
+    }
+    await publishClient.publishTemplate(versionRef, snapshot.id, runtime);
+    if (options.publishLatest !== false) await publishClient.publishTemplate(definition.id, snapshot.id, runtime);
+    return { templateId: definition.id, versionRef, definitionHash: templateDefinitionHash(definition), snapshotId: snapshot.id, reusedExisting: false };
   } finally {
     if (!snapshotted) await sandbox.stop().catch(() => {});
   }
 }
+
+async function resolveTemplateVersion(client: SandboxClient, versionRef: string): Promise<{ snapshotId: string } | undefined> {
+  try {
+    return await client.resolveTemplate(versionRef);
+  } catch (err) {
+    if (err instanceof SandboxApiError && err.status === 404) return undefined;
+    throw err;
+  }
+}