@forgezero/agent 0.1.73 → 0.1.75

package/dist/agent-heartbeat.d.ts

@@ -10,6 +10,22 @@ export interface AgentObservation {
     };
     architecture: string;
     mode: 'attested' | 'enrolled';
+    runtimeCapabilities?: {
+        native: true;
+        ociRunc: boolean;
+        kataQemuSnp: boolean;
+    };
+    /** Signed host evidence. Placement still reserves declared capacity; it never chases transient utilization. */
+    capacity?: {
+        logicalCpu: number;
+        memoryMiB: number;
+        storageGiB: number;
+    };
+    utilization?: {
+        load1mMilli: number;
+        memoryUsedMiB: number;
+        storageUsedGiB: number;
+    };
     update?: AgentUpdateReceipt;
     deploymentIntake?: {
         generation: number;
@@ -32,6 +48,14 @@ export interface AgentHeartbeatResponse {
         state: 'running' | 'paused';
     };
 }
+export interface AgentHostMetrics {
+    logicalCpu: number;
+    memoryBytes: number;
+    memoryFreeBytes: number;
+    storageBytes: number;
+    storageFreeBytes: number;
+    load1m: number;
+}
 export interface AgentHeartbeatOptions {
     apiUrl: string;
     nodeKey: string;
@@ -58,7 +82,7 @@ export interface AgentHeartbeatOptions {
     onEvent?: (event: string, detail?: unknown) => void;
     telemetry?: AgentOperationTelemetry;
 }
-export declare function observeAgentHost(version?: string, mode?: AgentObservation['mode'], osRelease?: string, architecture?: NodeJS.Architecture): AgentObservation;
+export declare function observeAgentHost(version?: string, mode?: AgentObservation['mode'], osRelease?: string, architecture?: NodeJS.Architecture, metrics?: AgentHostMetrics): AgentObservation;
 /** One PQ-authenticated observation and optional supervised update decision. */
 export declare function heartbeatAgentOnce(options: AgentHeartbeatOptions): Promise<AgentHeartbeatResponse>;
 /** Server-paced heartbeat; stopping waits for the active PQ request/update handoff. */

package/dist/agent-heartbeat.js

@@ -677,7 +677,8 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 }
 
 // src/agent-heartbeat.ts
-import { readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, statfsSync } from "node:fs";
+import { cpus, freemem, loadavg, totalmem } from "node:os";
 
 // src/signed-node-http.ts
 import {
@@ -749,25 +750,64 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.73";
+var VERSION3 = "0.1.75";
 
 // src/agent-heartbeat.ts
+function readAgentHostMetrics() {
+  const filesystem = statfsSync("/");
+  return {
+    logicalCpu: cpus().length,
+    memoryBytes: totalmem(),
+    memoryFreeBytes: freemem(),
+    storageBytes: Number(filesystem.blocks) * Number(filesystem.bsize),
+    storageFreeBytes: Number(filesystem.bavail) * Number(filesystem.bsize),
+    load1m: loadavg()[0]
+  };
+}
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");
 var remoteOutcome = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : cause instanceof SignedNodeHttpError ? "retryable" : "failed";
 
 class AgentUpdateRefusedError extends Error {
 }
-function observeAgentHost(version = VERSION3, mode = "enrolled", osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch) {
+function observeAgentHost(version = VERSION3, mode = "enrolled", osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch, metrics = readAgentHostMetrics()) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
     const separator = line.indexOf("=");
     return separator > 0 ? [[line.slice(0, separator), unquote(line.slice(separator + 1))]] : [];
   }));
+  const osId = (values.ID ?? "unknown").toLowerCase();
+  const osVersion = values.VERSION_ID ?? "unknown";
+  const ubuntuX64 = osId === "ubuntu" && ["24.04", "26.04"].includes(osVersion) && architecture === "x64";
+  const enabled = (path) => {
+    try {
+      return /^(?:1|y)$/i.test(readFileSync3(path, "utf8").trim());
+    } catch {
+      return false;
+    }
+  };
+  const gib = 1024 ** 3;
+  const mib = 1024 ** 2;
+  const storageGiB = Math.max(1, Math.floor(metrics.storageBytes / gib));
   return {
     version,
-    os: { id: (values.ID ?? "unknown").toLowerCase(), versionId: values.VERSION_ID ?? "unknown" },
+    os: { id: osId, versionId: osVersion },
     architecture,
-    mode
+    mode,
+    runtimeCapabilities: {
+      native: true,
+      ociRunc: ubuntuX64,
+      kataQemuSnp: ubuntuX64 && osVersion === "26.04" && existsSync3("/dev/kvm") && existsSync3("/dev/sev") && enabled("/sys/module/kvm_amd/parameters/sev") && enabled("/sys/module/kvm_amd/parameters/sev_snp")
+    },
+    capacity: {
+      logicalCpu: Math.max(1, metrics.logicalCpu),
+      memoryMiB: Math.max(1, Math.floor(metrics.memoryBytes / mib)),
+      storageGiB
+    },
+    utilization: {
+      load1mMilli: Math.max(0, Math.round(metrics.load1m * 1000)),
+      memoryUsedMiB: Math.max(0, Math.floor((metrics.memoryBytes - metrics.memoryFreeBytes) / mib)),
+      storageUsedGiB: Math.max(0, Math.min(storageGiB, Math.ceil((metrics.storageBytes - metrics.storageFreeBytes) / gib)))
+    }
   };
 }
 async function heartbeatAgentOnce(options) {

package/dist/bootstrap.d.ts

@@ -35,6 +35,8 @@ export interface PlatformBootstrapConfig {
         role: DatabaseBootstrapRole;
         /** Genesis master/joiners are Agency members; elastic joiners normally use `none`. */
         agency: DatabaseAgencyParticipation;
+        /** Prefer this normal writable Coordinator only for explicitly read-safe operations. */
+        readPreferred?: boolean;
         /** Cluster mode must remain default. Bootstrap verifies it and never mutates it. */
         serverMode: 'default';
         address?: string;

package/dist/bootstrap.js

@@ -1416,7 +1416,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.73";
+var VERSION = "0.1.75";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -3060,6 +3060,10 @@ function validatePlatformSharedEnvironment(input) {
   const coordinators = input.databaseCoordinators.map(privateCoordinator);
   if (new Set(coordinators).size !== coordinators.length)
     throw new Error("databaseCoordinators must be unique.");
+  const readPreferred = (input.databaseReadPreferredCoordinators ?? []).map(privateCoordinator);
+  if (new Set(readPreferred).size !== readPreferred.length || readPreferred.some((url) => !coordinators.includes(url))) {
+    throw new Error("databaseReadPreferredCoordinators must be a unique subset of databaseCoordinators.");
+  }
   if (input.databaseNetworkMode !== "private-lan") {
     throw new Error("Attended platform bootstrap supports only private-lan database networking.");
   }
@@ -3133,6 +3137,7 @@ function validatePlatformSharedEnvironment(input) {
   return {
     ...input,
     databaseCoordinators: coordinators,
+    databaseReadPreferredCoordinators: readPreferred,
     appOrigin: httpsOrigin("appOrigin", input.appOrigin),
     apiOrigin: httpsOrigin("apiOrigin", input.apiOrigin),
     agentOtlpEndpoint: httpsOrigin("agentOtlpEndpoint", input.agentOtlpEndpoint),
@@ -3146,6 +3151,8 @@ function renderPlatformSharedEnvironment(input) {
   const entries = {
     ARANGO_URL: value.databaseCoordinators[0],
     ARANGO_URLS: value.databaseCoordinators.join(","),
+    ARANGO_READ_PREFERRED_URLS: (value.databaseReadPreferredCoordinators ?? []).join(","),
+    ARANGO_READ_PREFERRED_FALLBACK: "balanced",
     ARANGO_DB: "fz",
     FZ_DATABASE_MODE: "platform",
     ARANGO_USER: value.databaseUser,
@@ -3769,6 +3776,10 @@ function validateBootstrapConfig(value) {
   if (!["member", "none"].includes(value.database.agency) || value.database.role === "master" && value.database.agency !== "member" || value.database.role === "none" && value.database.agency !== "none") {
     throw new Error("database role and Agency participation disagree");
   }
+  value.database.readPreferred ??= false;
+  if (value.database.readPreferred && (value.database.role !== "joiner" || value.database.agency !== "none")) {
+    throw new Error("read-preferred database routing requires an extra non-Agency joiner");
+  }
   if (value.database.role !== "none" && !value.database.address)
     throw new Error("database nodes require a private address");
   if (value.database.role === "joiner" && !value.database.master)
@@ -3788,6 +3799,10 @@ function validateBootstrapConfig(value) {
   if (runtime.softwareProfile !== value.profile || runtime.databaseRole !== value.database.role || runtime.nodeHostname !== value.nodeHostname || runtime.apiOrigin !== api.origin || runtime.databaseCoordinators.join(",") !== write.join(",")) {
     throw new Error("platform runtime coordinates disagree with immutable bootstrap coordinates");
   }
+  const ownCoordinator = value.database.address ? `http://${value.database.address}:8529` : undefined;
+  if (Boolean(ownCoordinator && (runtime.databaseReadPreferredCoordinators ?? []).includes(ownCoordinator)) !== value.database.readPreferred) {
+    throw new Error("runtime read-preferred coordinator set disagrees with this node database routing intent");
+  }
   if (runtime.deployProfile !== value.environment)
     throw new Error("runtime deployment profile disagrees with bootstrap environment");
   if (value.database.address !== runtime.databaseAddress || value.database.master !== runtime.databaseMaster) {
@@ -4099,6 +4114,7 @@ function bootstrapIdentity(config) {
       role: config.database.role,
       serverMode: config.database.serverMode,
       agency: config.database.agency,
+      readPreferred: config.database.readPreferred,
       address: config.database.address ?? null,
       master: config.database.master ?? null,
       coordinators: config.database.coordinators
@@ -4134,7 +4150,7 @@ function parseStoredState(raw) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error("bootstrap state is malformed");
   const state = value;
-  if (state.format !== 2 || !["platform", "enrolled-compute"].includes(state.kind ?? "") || !/^[a-f0-9]{64}$/.test(state.identityDigest ?? "") || typeof state.profile !== "string" || typeof state.nodeHostname !== "string" || typeof state.apiUrl !== "string" || state.kind === "platform" && !["member", "none"].includes(state.databaseAgency ?? "")) {
+  if (state.format !== 2 || !["platform", "enrolled-compute"].includes(state.kind ?? "") || !/^[a-f0-9]{64}$/.test(state.identityDigest ?? "") || typeof state.profile !== "string" || typeof state.nodeHostname !== "string" || typeof state.apiUrl !== "string" || state.kind === "platform" && (!["member", "none"].includes(state.databaseAgency ?? "") || typeof state.databaseReadPreferred !== "boolean")) {
     throw new Error("bootstrap state is legacy or incomplete; refusing an unbound repair");
   }
   return state;
@@ -4184,6 +4200,7 @@ function stateFor(config, cloudflare, previousCloudflareTunnelId) {
       environment: config.environment,
       databaseRole: config.database.role,
       databaseAgency: config.database.agency,
+      databaseReadPreferred: config.database.readPreferred,
       databaseServerMode: config.database.serverMode,
       databaseAddress: config.database.address,
       databaseCoordinators: config.database.coordinators,
@@ -4688,7 +4705,7 @@ function strictBootstrapDocument(value) {
     exactKeys(root.firewall, ["enabled", "sshPort", "privateCidrs"], "firewall config");
     if (root.cloudflareHandoff !== undefined)
       exactKeys(root.cloudflareHandoff, ["handoffFile", "nodeName"], "Cloudflare handoff");
-    exactKeys(root.database, ["role", "agency", "serverMode", "address", "master", "coordinators"], "database config");
+    exactKeys(root.database, ["role", "agency", "readPreferred", "serverMode", "address", "master", "coordinators"], "database config");
     exactKeys(root.enrolment, ["source"], "platform enrolment config");
     const runtime = exactKeys(root.runtime, [
       "environment",
@@ -4732,7 +4749,8 @@ function strictBootstrapDocument(value) {
       "backup",
       "cloudflare",
       "realtime",
-      "initialInventory"
+      "initialInventory",
+      "databaseReadPreferredCoordinators"
     ], "runtime environment");
     const environment = runtime.environment;
     if (environment.initialInventory !== undefined) {

package/dist/community-rehearsal-host.js

@@ -4,22 +4,30 @@ import {
   accessSync,
   chmodSync,
   copyFileSync,
+  createReadStream,
   existsSync,
   mkdtempSync,
   mkdirSync,
   readFileSync,
   renameSync,
   rmSync,
+  statSync,
   symlinkSync,
   unlinkSync,
   writeFileSync
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 var PINNED_BUN_VERSION = "1.3.14";
 var BUN_RELEASE_SHA256 = "951ee2aee855f08595aeec6225226a298d3fea83a3dcd6465c09cbccdf7e848f";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+var NERDCTL_VERSION = "2.3.5";
+var BUILDKIT_VERSION = "0.32.2";
+var KATA_CONTAINERS_VERSION = "4.0.0";
+var NERDCTL_SHA256 = "de3206aeb7cbd5f20f5fb1f55c1e3bf2db1be567812a8a3f5e65eba2488347ee";
+var BUILDKIT_SHA256 = "2975d0f651ad96ba8b80b9992ae1f9a964f4408569af5b6dc36544165c3926af";
+var KATA_SHA256 = "2c3b9dfeba355582b40aee462b12916c9740654d0230f696adf719d67b063a8c";
 var OS_CATALOG = [
   {
     id: "ubuntu",
@@ -49,6 +57,8 @@ var OS_CATALOG = [
 var SOFTWARE_CATALOG = [
   { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "docker", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "containerd", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "kata-containers", version: "4.0.0", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
@@ -57,6 +67,7 @@ var SOFTWARE_CATALOG = [
   { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "git", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "docker", version: "ubuntu-24.04", status: "active", os: "ubuntu", osVersion: "24.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "containerd", version: "ubuntu-24.04", status: "active", os: "ubuntu", osVersion: "24.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "nginx", version: "ubuntu-24.04", status: "active", os: "ubuntu", osVersion: "24.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "ufw", version: "ubuntu-24.04", status: "active", os: "ubuntu", osVersion: "24.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "openssh-client", version: "ubuntu-24.04", status: "active", os: "ubuntu", osVersion: "24.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
@@ -65,6 +76,8 @@ var SOFTWARE_CATALOG = [
 var UBUNTU_2604_X64 = [
   { requirement: { id: "bun", version: "1.3.14" } },
   { requirement: { id: "docker", version: "ubuntu-26.04" } },
+  { requirement: { id: "containerd", version: "ubuntu-26.04" } },
+  { requirement: { id: "kata-containers", version: "4.0.0" } },
   { requirement: { id: "nginx", version: "ubuntu-26.04" } },
   { requirement: { id: "arangodb", version: "3.11.14" } },
   { requirement: { id: "cloudflared", version: "2026.7.3" } },
@@ -76,6 +89,7 @@ var UBUNTU_2604_X64 = [
 var UBUNTU_2404_X64 = [
   { requirement: { id: "bun", version: "1.3.14" } },
   { requirement: { id: "docker", version: "ubuntu-24.04" } },
+  { requirement: { id: "containerd", version: "ubuntu-24.04" } },
   { requirement: { id: "nginx", version: "ubuntu-24.04" } },
   { requirement: { id: "ufw", version: "ubuntu-24.04" } },
   { requirement: { id: "openssh-client", version: "ubuntu-24.04" } },
@@ -92,6 +106,46 @@ var DOCKER_DAEMON_CONFIG = `${JSON.stringify({
   "log-opts": { "max-size": "10m", "max-file": "3" }
 }, null, 2)}
 `;
+var CONTAINERD_CONFIG_PATH = "/etc/containerd/config.toml";
+var KATA_SNP_CONFIG_PATH = "/opt/kata/share/defaults/kata-containers/configuration-qemu-snp.toml";
+var KATA_ACTIVE_CONFIG_PATH = "/etc/kata-containers/configuration.toml";
+var CONTAINERD_CONFIG = (kata) => `version = 2
+root = "/var/lib/forgezero/containerd"
+state = "/run/forgezero/containerd"
+
+[grpc]
+  address = "/run/containerd/containerd.sock"
+
+[plugins."io.containerd.grpc.v1.cri".containerd]
+  snapshotter = "overlayfs"
+  default_runtime_name = "runc"
+
+[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
+  runtime_type = "io.containerd.runc.v2"
+${kata ? `
+[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata-qemu-snp]
+  runtime_type = "io.containerd.kata.v2"
+  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata-qemu-snp.options]
+    ConfigPath = "${KATA_ACTIVE_CONFIG_PATH}"
+` : ""}`;
+var BUILDKIT_UNIT = `[Unit]
+Description=ForgeZero BuildKit daemon
+After=network-online.target containerd.service
+Wants=network-online.target
+Requires=containerd.service
+
+[Service]
+Type=notify
+ExecStart=/usr/local/bin/buildkitd --addr unix:///run/buildkit/buildkitd.sock --root /var/lib/forgezero/buildkit
+Restart=on-failure
+RestartSec=2
+NoNewPrivileges=yes
+ProtectSystem=strict
+ReadWritePaths=/var/lib/forgezero/buildkit /run/buildkit
+
+[Install]
+WantedBy=multi-user.target
+`;
 var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
 var runSoftwareCommand = async (argv, env = {}) => {
   let child;
@@ -111,14 +165,28 @@ var runSoftwareCommand = async (argv, env = {}) => {
   return { exitCode, output: `${stdout}${stderr}` };
 };
 var run = runSoftwareCommand;
-var download = async (url, destination, sha256) => {
-  const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
+var download = async (url, destination, sha256, maximumBytes = 512 * 1024 * 1024) => {
+  const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(30 * 60000) });
   if (!response.ok)
     throw new Error(`download failed with HTTP ${response.status}`);
-  const bytes = new Uint8Array(await response.arrayBuffer());
-  if (createHash("sha256").update(bytes).digest("hex") !== sha256)
+  const declared = Number(response.headers.get("content-length") ?? 0);
+  if (declared > maximumBytes)
+    throw new Error("download exceeds reviewed size bound");
+  if (existsSync(destination))
+    throw new Error("download destination already exists");
+  await Bun.write(destination, response);
+  chmodSync(destination, 384);
+  if (statSync(destination).size > maximumBytes) {
+    rmSync(destination, { force: true });
+    throw new Error("download exceeds reviewed size bound");
+  }
+  const digest = createHash("sha256");
+  for await (const chunk of createReadStream(destination))
+    digest.update(chunk);
+  if (digest.digest("hex") !== sha256) {
+    rmSync(destination, { force: true });
     throw new Error("download checksum mismatch");
-  writeFileSync(destination, bytes, { mode: 384, flag: "wx" });
+  }
 };
 var successful = (result, pattern) => result.exitCode === 0 && (!pattern || pattern.test(result.output));
 var aptInstall = async (name) => {
@@ -126,6 +194,106 @@ var aptInstall = async (name) => {
   const update = await run(["/usr/bin/apt-get", "update", "-qq"], environment);
   return update.exitCode === 0 ? run(["/usr/bin/apt-get", "install", "-y", name], environment) : update;
 };
+var aptInstallMany = async (names) => {
+  const environment = { DEBIAN_FRONTEND: "noninteractive" };
+  const update = await run(["/usr/bin/apt-get", "update", "-qq"], environment);
+  return update.exitCode === 0 ? run(["/usr/bin/apt-get", "install", "-y", ...names], environment) : update;
+};
+var writeOwnedPolicy = (pathValue, content, mode = 420) => {
+  if (existsSync(pathValue)) {
+    if (readFileSync(pathValue, "utf8") !== content)
+      throw new Error(`refusing to overwrite non-ForgeZero policy at ${pathValue}`);
+    return;
+  }
+  mkdirSync(dirname(pathValue), { recursive: true, mode: 493 });
+  writeFileSync(pathValue, content, { mode, flag: "wx" });
+};
+var installContainerdRuntime = async (directory, osVersion) => {
+  const installed = await aptInstallMany(["containerd", "runc", "containernetworking-plugins"]);
+  if (installed.exitCode !== 0)
+    return installed;
+  const nerdctl = join(directory, "nerdctl.tar.gz");
+  await download(`https://github.com/containerd/nerdctl/releases/download/v${NERDCTL_VERSION}/nerdctl-${NERDCTL_VERSION}-linux-amd64.tar.gz`, nerdctl, NERDCTL_SHA256);
+  const nerdctlExtract = await run(["/usr/bin/tar", "-xzf", nerdctl, "-C", "/usr/local/bin", "nerdctl"]);
+  if (nerdctlExtract.exitCode !== 0)
+    return nerdctlExtract;
+  chmodSync("/usr/local/bin/nerdctl", 493);
+  const buildkit = join(directory, "buildkit.tar.gz");
+  await download(`https://github.com/moby/buildkit/releases/download/v${BUILDKIT_VERSION}/buildkit-v${BUILDKIT_VERSION}.linux-amd64.tar.gz`, buildkit, BUILDKIT_SHA256);
+  const unpacked = join(directory, "buildkit");
+  mkdirSync(unpacked, { mode: 448 });
+  const buildkitExtract = await run(["/usr/bin/tar", "-xzf", buildkit, "-C", unpacked]);
+  if (buildkitExtract.exitCode !== 0)
+    return buildkitExtract;
+  for (const binary of ["buildctl", "buildkitd"]) {
+    copyFileSync(join(unpacked, "bin", binary), `/usr/local/bin/${binary}`);
+    chmodSync(`/usr/local/bin/${binary}`, 493);
+  }
+  mkdirSync("/etc/containerd", { recursive: true, mode: 493 });
+  const expected = CONTAINERD_CONFIG(false);
+  const kataExpected = CONTAINERD_CONFIG(true);
+  if (existsSync(CONTAINERD_CONFIG_PATH) && ![expected, kataExpected].includes(readFileSync(CONTAINERD_CONFIG_PATH, "utf8"))) {
+    return { exitCode: 2, output: "refusing to overwrite an existing containerd configuration that differs from the reviewed ForgeZero policy" };
+  }
+  if (!existsSync(CONTAINERD_CONFIG_PATH))
+    writeFileSync(CONTAINERD_CONFIG_PATH, expected, { mode: 420, flag: "wx" });
+  writeOwnedPolicy("/etc/systemd/system/forgezero-buildkit.service", BUILDKIT_UNIT);
+  mkdirSync("/var/lib/forgezero/containerd", { recursive: true, mode: 448 });
+  mkdirSync("/var/lib/forgezero/buildkit", { recursive: true, mode: 448 });
+  const reload = await run(["/usr/bin/systemctl", "daemon-reload"]);
+  if (reload.exitCode !== 0)
+    return reload;
+  const enabled = await run(["/usr/bin/systemctl", "enable", "--now", "containerd.service", "forgezero-buildkit.service"]);
+  return enabled.exitCode === 0 ? { exitCode: 0, output: `containerd ${osVersion} with nerdctl ${NERDCTL_VERSION} and BuildKit ${BUILDKIT_VERSION}` } : enabled;
+};
+var installKataRuntime = async (directory) => {
+  for (const pathValue of ["/dev/kvm", "/dev/sev"])
+    if (!existsSync(pathValue))
+      return { exitCode: 2, output: `${pathValue} is required for Kata SEV-SNP` };
+  for (const parameter of ["/sys/module/kvm_amd/parameters/sev", "/sys/module/kvm_amd/parameters/sev_snp"]) {
+    if (!existsSync(parameter) || !/^(1|Y)$/i.test(readFileSync(parameter, "utf8").trim()))
+      return { exitCode: 2, output: `${parameter} does not enable SEV-SNP` };
+  }
+  const dependencies = await aptInstallMany(["zstd"]);
+  if (dependencies.exitCode !== 0)
+    return dependencies;
+  const archive = join(directory, "kata.tar.zst");
+  await download(`https://github.com/kata-containers/kata-containers/releases/download/${KATA_CONTAINERS_VERSION}/kata-static-${KATA_CONTAINERS_VERSION}-amd64.tar.zst`, archive, KATA_SHA256, 2200000000);
+  const tar = join(directory, "kata.tar");
+  const expanded = await run(["/usr/bin/unzstd", "--quiet", archive, "--output", tar]);
+  if (expanded.exitCode !== 0)
+    return expanded;
+  const extracted = await run(["/usr/bin/tar", "-xf", tar, "-C", "/"]);
+  if (extracted.exitCode !== 0)
+    return extracted;
+  if (!existsSync("/opt/kata/bin/containerd-shim-kata-v2") || !existsSync(KATA_SNP_CONFIG_PATH)) {
+    return { exitCode: 2, output: "Kata archive does not contain the reviewed QEMU SNP runtime and configuration" };
+  }
+  const snpConfig = readFileSync(KATA_SNP_CONFIG_PATH, "utf8");
+  if (!/^\s*confidential_guest\s*=\s*true\s*$/m.test(snpConfig) || !/^\s*sev_snp_guest\s*=\s*true\s*$/m.test(snpConfig)) {
+    return { exitCode: 2, output: "Kata QEMU configuration does not enable confidential SEV-SNP guests" };
+  }
+  mkdirSync("/etc/kata-containers", { recursive: true, mode: 493 });
+  if (existsSync(KATA_ACTIVE_CONFIG_PATH) && readFileSync(KATA_ACTIVE_CONFIG_PATH, "utf8") !== snpConfig) {
+    return { exitCode: 2, output: "refusing to overwrite a non-ForgeZero Kata runtime configuration" };
+  }
+  if (!existsSync(KATA_ACTIVE_CONFIG_PATH))
+    copyFileSync(KATA_SNP_CONFIG_PATH, KATA_ACTIVE_CONFIG_PATH);
+  chmodSync(KATA_ACTIVE_CONFIG_PATH, 420);
+  try {
+    unlinkSync("/usr/local/bin/containerd-shim-kata-v2");
+  } catch {}
+  symlinkSync("/opt/kata/bin/containerd-shim-kata-v2", "/usr/local/bin/containerd-shim-kata-v2");
+  const base = CONTAINERD_CONFIG(false);
+  const kata = CONTAINERD_CONFIG(true);
+  if (!existsSync(CONTAINERD_CONFIG_PATH) || ![base, kata].includes(readFileSync(CONTAINERD_CONFIG_PATH, "utf8"))) {
+    return { exitCode: 2, output: "containerd must use the reviewed ForgeZero policy before Kata is installed" };
+  }
+  if (readFileSync(CONTAINERD_CONFIG_PATH, "utf8") !== kata)
+    writeFileSync(CONTAINERD_CONFIG_PATH, kata, { mode: 420 });
+  const restarted = await run(["/usr/bin/systemctl", "restart", "containerd.service"]);
+  return restarted.exitCode === 0 ? { exitCode: 0, output: `Kata Containers ${KATA_CONTAINERS_VERSION} QEMU SNP` } : restarted;
+};
 async function executeSoftwareOperation(operation) {
   const { software, version } = operation;
   if (![...UBUNTU_2604_X64, ...UBUNTU_2404_X64].some(({ requirement }) => requirement.id === software && requirement.version === version)) {
@@ -143,6 +311,26 @@ async function executeSoftwareOperation(operation) {
       const active = await run(["/usr/bin/systemctl", "is-active", "--quiet", "docker.service"]);
       return active.exitCode === 0 ? { exitCode: 0, output: binary.output } : active;
     }
+    if (software === "containerd") {
+      const [containerd, nerdctl, buildkit, active, builder] = await Promise.all([
+        run(["/usr/bin/containerd", "--version"]),
+        run(["/usr/local/bin/nerdctl", "--version"]),
+        run(["/usr/local/bin/buildkitd", "--version"]),
+        run(["/usr/bin/systemctl", "is-active", "--quiet", "containerd.service"]),
+        run(["/usr/bin/systemctl", "is-active", "--quiet", "forgezero-buildkit.service"])
+      ]);
+      const policy = existsSync(CONTAINERD_CONFIG_PATH) ? readFileSync(CONTAINERD_CONFIG_PATH, "utf8") : "";
+      const validPolicy = policy === CONTAINERD_CONFIG(false) || policy === CONTAINERD_CONFIG(true);
+      return successful(containerd, /containerd/) && successful(nerdctl, new RegExp(NERDCTL_VERSION.replaceAll(".", "\\."))) && successful(buildkit, new RegExp(BUILDKIT_VERSION.replaceAll(".", "\\."))) && active.exitCode === 0 && builder.exitCode === 0 && validPolicy ? { exitCode: 0, output: `${containerd.output}${nerdctl.output}${buildkit.output}` } : { exitCode: 1, output: "containerd, nerdctl, BuildKit, or ForgeZero storage/runtime policy is unavailable" };
+    }
+    if (software === "kata-containers") {
+      const shim = await run(["/opt/kata/bin/containerd-shim-kata-v2", "--version"]);
+      const policy = existsSync(CONTAINERD_CONFIG_PATH) ? readFileSync(CONTAINERD_CONFIG_PATH, "utf8") : "";
+      const activeConfig = existsSync(KATA_ACTIVE_CONFIG_PATH) ? readFileSync(KATA_ACTIVE_CONFIG_PATH, "utf8") : "";
+      const host = ["/dev/kvm", "/dev/sev", KATA_SNP_CONFIG_PATH, KATA_ACTIVE_CONFIG_PATH].every(existsSync) && ["/sys/module/kvm_amd/parameters/sev", "/sys/module/kvm_amd/parameters/sev_snp"].every((parameter) => existsSync(parameter) && /^(1|Y)$/i.test(readFileSync(parameter, "utf8").trim()));
+      const active = await run(["/usr/bin/systemctl", "is-active", "--quiet", "containerd.service"]);
+      return successful(shim, /kata.*4\.0\.0/i) && policy === CONTAINERD_CONFIG(true) && activeConfig === (existsSync(KATA_SNP_CONFIG_PATH) ? readFileSync(KATA_SNP_CONFIG_PATH, "utf8") : "") && host && active.exitCode === 0 ? { exitCode: 0, output: shim.output } : { exitCode: 1, output: "Kata QEMU SNP runtime, host capability, or containerd policy is unavailable" };
+    }
     if (software === "nginx") {
       const binary = await run(["/usr/sbin/nginx", "-v"]);
       return binary.exitCode === 0 ? run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]) : binary;
@@ -194,6 +382,17 @@ async function executeSoftwareOperation(operation) {
   }
   const directory = mkdtempSync(join(tmpdir(), "forgezero-software-"));
   try {
+    if (software === "containerd")
+      return installContainerdRuntime(directory, version === "ubuntu-24.04" ? "24.04" : "26.04");
+    if (software === "kata-containers") {
+      const containerd = await executeSoftwareOperation({ kind: "check", software: "containerd", version: "ubuntu-26.04" });
+      if (containerd.exitCode !== 0) {
+        const installed2 = await installContainerdRuntime(directory, "26.04");
+        if (installed2.exitCode !== 0)
+          return installed2;
+      }
+      return installKataRuntime(directory);
+    }
     if (software === "cloudflare-warp") {
       const key = join(directory, "cloudflare-warp-key.gpg");
       await download("https://pkg.cloudflareclient.com/pubkey.gpg", key, "0f37fc298c98e88ee3c0ee68c95b69f1dba9eb477abe3167e13982105911264d");
@@ -275,7 +474,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "docker", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client", "git"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "docker", "containerd", "kata-containers", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client", "git"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };
@@ -321,7 +520,7 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
 import { createHash as createHash2 } from "node:crypto";
 import { lstatSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, symlinkSync as symlinkSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { isIP } from "node:net";
-import { dirname } from "node:path";
+import { dirname as dirname2 } from "node:path";
 var COMMUNITY_REHEARSAL_VERSION = "3.11.14";
 var COMMUNITY_REHEARSAL_ROOT = "/opt/forgezero-rehearsals/community-cluster-api";
 var COMMUNITY_DATABASE_ROOT = "/var/lib/forgezero-rehearsal-cluster";
@@ -539,7 +738,7 @@ async function applyOperations(operations) {
     if (operation.kind === "remove-tree")
       rmSync2(operation.path, { recursive: true, force: true });
     else if (operation.kind === "write") {
-      mkdirSync2(dirname(operation.path), { recursive: true });
+      mkdirSync2(dirname2(operation.path), { recursive: true });
       writeFileSync2(operation.path, operation.content, { mode: operation.mode });
     } else if (operation.kind === "unlink") {
       try {

package/dist/credential-schema.d.ts

@@ -86,7 +86,7 @@ export declare const AGENT_CREDENTIAL_POLICY: {
     };
 };
 export interface DeploymentCredentialBinding {
-    /** Exact environment variable requested by a checked-in pipeline step. */
+    /** Exact Vault/systemd logical name requested by a checked-in pipeline step. */
     name: string;
     /** Exact RAM-replica cache key; never a secret value. */
     vaultCacheKey: string;

package/dist/credential-schema.js

@@ -335,7 +335,7 @@ var AGENT_CREDENTIAL_POLICY = {
   "platform-compute": { vault: true, systemdFallback: true, hiddenInput: false },
   "tenant-compute": { vault: true, systemdFallback: true, hiddenInput: false }
 };
-var CREDENTIAL_NAME = /^[A-Z_][A-Z0-9_]*$/;
+var CREDENTIAL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
 var SCOPE_PART2 = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
 function deploymentCredentialSchema(input) {
   if (!SCOPE_PART2.test(input.projectKey) || !SCOPE_PART2.test(input.environmentKey)) {