@forgezero/agent 0.1.41 → 0.1.42

package/dist/provision.js

@@ -33,6 +33,7 @@ var syncReleaseDirectory = (directory) => {
     join(directory, "package.json"),
     join(directory, "dist", "fz-agent.js"),
     join(directory, "dist", "fz.js"),
+    join(directory, "dist", "fz-git-ssh.js"),
     join(directory, "dist"),
     directory,
     dirname(directory)
@@ -101,7 +102,8 @@ async function validateReleaseDirectory(directory, release, run) {
   }
   const agent = join(directory, "dist", "fz-agent.js");
   const cli = join(directory, "dist", "fz.js");
-  for (const binary of [agent, cli]) {
+  const gitSsh = join(directory, "dist", "fz-git-ssh.js");
+  for (const binary of [agent, cli, gitSsh]) {
     if (!readFileSync(binary, "utf8").startsWith(`#!/usr/bin/env bun
 `)) {
       throw new Error("agent update artifact is not a self-contained Bun executable");
@@ -148,7 +150,8 @@ async function stageAgentRelease(releaseInput, options) {
     for (const [member, relative] of [
       ["package/package.json", "package.json"],
       ["package/dist/fz-agent.js", "dist/fz-agent.js"],
-      ["package/dist/fz.js", "dist/fz.js"]
+      ["package/dist/fz.js", "dist/fz.js"],
+      ["package/dist/fz-git-ssh.js", "dist/fz-git-ssh.js"]
     ]) {
       const extracted = await checked(run, {
         command: "/usr/bin/tar",
@@ -674,9 +677,24 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 }
 
 // src/software.ts
-import { readFileSync as readFileSync3 } from "node:fs";
+import { createHash as createHash2 } from "node:crypto";
+import {
+  accessSync,
+  chmodSync as chmodSync3,
+  copyFileSync,
+  mkdtempSync,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync3,
+  renameSync as renameSync3,
+  rmSync as rmSync3,
+  symlinkSync as symlinkSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join as join3 } from "node:path";
 var PINNED_BUN_VERSION = "1.3.14";
-var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
+var BUN_RELEASE_SHA256 = "951ee2aee855f08595aeec6225226a298d3fea83a3dcd6465c09cbccdf7e848f";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
 var OS_CATALOG = [
@@ -687,41 +705,151 @@ var SOFTWARE_CATALOG = [
   { 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" },
+  { id: "cloudflare-warp", version: "2026.6.822.0-min", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
-  {
-    requirement: { id: "bun", version: "1.3.14" },
-    check: 'test "$(/usr/local/bin/bun --version 2>/dev/null)" = 1.3.14',
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL https://bun.sh/install -o "$tmp/install"; ` + `echo "${BUN_INSTALLER_SHA256}  $tmp/install" | sha256sum -c -; ` + `BUN_INSTALL="$tmp/bun" BUN_VERSION=1.3.14 bash "$tmp/install" >/dev/null; ` + `install -d -m 0755 /usr/local/lib/forgezero/runtime; ` + `install -m 0755 "$tmp/bun/bin/bun" /usr/local/lib/forgezero/runtime/bun.next; ` + `mv -Tf /usr/local/lib/forgezero/runtime/bun.next /usr/local/lib/forgezero/runtime/bun; ` + `ln -sfn /usr/local/lib/forgezero/runtime/bun /usr/local/bin/bun`
-  },
-  {
-    requirement: { id: "nginx", version: "ubuntu-26.04" },
-    check: "command -v nginx >/dev/null && systemctl is-active --quiet nginx",
-    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y nginx && systemctl enable --now nginx"
-  },
-  {
-    requirement: { id: "arangodb", version: "3.11.14" },
-    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14' && ` + `! systemctl is-active --quiet arangodb3.service && ` + `! systemctl is-enabled --quiet arangodb3.service`,
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install; ` + `systemctl disable --now arangodb3.service`
-  },
-  {
-    requirement: { id: "cloudflared", version: "2026.7.3" },
-    check: `cloudflared --version 2>/dev/null | grep -q '2026.7.3'`,
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64' -o "$tmp/cloudflared"; ` + `echo "${CLOUDFLARED_SHA256}  $tmp/cloudflared" | sha256sum -c -; ` + `install -m 0755 "$tmp/cloudflared" /usr/local/bin/cloudflared`
-  },
-  {
-    requirement: { id: "ufw", version: "ubuntu-26.04" },
-    check: "command -v ufw >/dev/null",
-    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
-  },
-  {
-    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
-    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
-    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
-  }
+  { requirement: { id: "bun", version: "1.3.14" } },
+  { requirement: { id: "nginx", version: "ubuntu-26.04" } },
+  { requirement: { id: "arangodb", version: "3.11.14" } },
+  { requirement: { id: "cloudflared", version: "2026.7.3" } },
+  { requirement: { id: "cloudflare-warp", version: "2026.6.822.0-min" } },
+  { requirement: { id: "ufw", version: "ubuntu-26.04" } },
+  { requirement: { id: "openssh-client", version: "ubuntu-26.04" } }
 ];
+var path = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+var run = async (argv, env = {}) => {
+  const child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  return { exitCode, output: `${stdout}${stderr}` };
+};
+var download = async (url, destination, sha256) => {
+  const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
+  if (!response.ok)
+    throw new Error(`download failed with HTTP ${response.status}`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (createHash2("sha256").update(bytes).digest("hex") !== sha256)
+    throw new Error("download checksum mismatch");
+  writeFileSync3(destination, bytes, { mode: 384, flag: "wx" });
+};
+var successful = (result, pattern) => result.exitCode === 0 && (!pattern || pattern.test(result.output));
+var aptInstall = async (name) => {
+  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", name], environment) : update;
+};
+async function executeSoftwareOperation(operation) {
+  const { software, version } = operation;
+  if (!UBUNTU_2604_X64.some(({ requirement }) => requirement.id === software && requirement.version === version)) {
+    return { exitCode: 2, output: "unsupported software operation" };
+  }
+  if (operation.kind === "check") {
+    if (software === "bun")
+      return run(["/usr/local/bin/bun", "--version"]).then((r) => ({ ...r, exitCode: successful(r, /^1\.3\.14\s*$/m) ? 0 : 1 }));
+    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;
+    }
+    if (software === "arangodb") {
+      const binary = await run(["/usr/bin/arangod", "--version"]);
+      if (!successful(binary, /3\.11\.14/))
+        return { ...binary, exitCode: 1 };
+      const [active, enabled] = await Promise.all([
+        run(["/usr/bin/systemctl", "is-active", "--quiet", "arangodb3.service"]),
+        run(["/usr/bin/systemctl", "is-enabled", "--quiet", "arangodb3.service"])
+      ]);
+      return active.exitCode !== 0 && enabled.exitCode !== 0 ? { exitCode: 0, output: binary.output } : { exitCode: 1, output: "vendor standalone unit remains active or enabled" };
+    }
+    if (software === "cloudflared")
+      return run(["/usr/local/bin/cloudflared", "--version"]).then((r) => ({ ...r, exitCode: successful(r, /2026\.7\.3/) ? 0 : 1 }));
+    if (software === "cloudflare-warp")
+      return run(["/usr/bin/warp-cli", "--version"]).then((result) => {
+        const match = result.output.match(/(\d{4})\.(\d+)\.(\d+)\.(\d+)/);
+        const observed = match?.slice(1).map(Number);
+        const minimum = [2026, 6, 822, 0];
+        const supported = observed && observed.some((part, index) => part > minimum[index] && observed.slice(0, index).every((prior, priorIndex) => prior === minimum[priorIndex])) || observed?.every((part, index) => part === minimum[index]);
+        return { ...result, exitCode: result.exitCode === 0 && supported ? 0 : 1 };
+      });
+    const binaries = software === "ufw" ? ["/usr/sbin/ufw"] : ["/usr/bin/ssh", "/usr/bin/scp", "/usr/bin/ssh-keyscan", "/usr/bin/ssh-keygen"];
+    try {
+      binaries.forEach((binary) => accessSync(binary));
+      return { exitCode: 0, output: "" };
+    } catch (cause) {
+      return { exitCode: 1, output: cause instanceof Error ? cause.message : String(cause) };
+    }
+  }
+  if (software === "nginx" || software === "ufw" || software === "openssh-client") {
+    const installed = await aptInstall(software === "openssh-client" ? "openssh-client" : software);
+    if (installed.exitCode !== 0 || software !== "nginx")
+      return installed;
+    return run(["/usr/bin/systemctl", "enable", "--now", "nginx.service"]);
+  }
+  const directory = mkdtempSync(join3(tmpdir(), "forgezero-software-"));
+  try {
+    if (software === "cloudflare-warp") {
+      const key = join3(directory, "cloudflare-warp-key.gpg");
+      await download("https://pkg.cloudflareclient.com/pubkey.gpg", key, "0f37fc298c98e88ee3c0ee68c95b69f1dba9eb477abe3167e13982105911264d");
+      mkdirSync3("/usr/share/keyrings", { recursive: true, mode: 493 });
+      const dearmored = await run([
+        "/usr/bin/gpg",
+        "--batch",
+        "--yes",
+        "--dearmor",
+        "-o",
+        "/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg",
+        key
+      ]);
+      if (dearmored.exitCode !== 0)
+        return dearmored;
+      mkdirSync3("/etc/apt/sources.list.d", { recursive: true, mode: 493 });
+      writeFileSync3("/etc/apt/sources.list.d/cloudflare-client.list", `deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ resolute main
+`, { mode: 420 });
+      return aptInstall("cloudflare-warp");
+    }
+    if (software === "bun") {
+      const archive = join3(directory, "bun.zip");
+      await download("https://github.com/oven-sh/bun/releases/download/bun-v1.3.14/bun-linux-x64.zip", archive, BUN_RELEASE_SHA256);
+      const unpacked = join3(directory, "unpacked");
+      mkdirSync3(unpacked, { mode: 448 });
+      const unzipped = await run(["/usr/bin/unzip", "-q", archive, "-d", unpacked]);
+      if (unzipped.exitCode !== 0)
+        return unzipped;
+      mkdirSync3("/usr/local/lib/forgezero/runtime", { recursive: true, mode: 493 });
+      copyFileSync(join3(unpacked, "bun-linux-x64", "bun"), "/usr/local/lib/forgezero/runtime/bun.next");
+      chmodSync3("/usr/local/lib/forgezero/runtime/bun.next", 493);
+      renameSync3("/usr/local/lib/forgezero/runtime/bun.next", "/usr/local/lib/forgezero/runtime/bun");
+      try {
+        unlinkSync2("/usr/local/bin/bun");
+      } catch {}
+      symlinkSync2("/usr/local/lib/forgezero/runtime/bun", "/usr/local/bin/bun");
+      return { exitCode: 0, output: "" };
+    }
+    if (software === "cloudflared") {
+      const binary = join3(directory, "cloudflared");
+      await download("https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64", binary, CLOUDFLARED_SHA256);
+      chmodSync3(binary, 493);
+      copyFileSync(binary, "/usr/local/bin/cloudflared");
+      chmodSync3("/usr/local/bin/cloudflared", 493);
+      return { exitCode: 0, output: "" };
+    }
+    const deb = join3(directory, "arangodb.deb");
+    await download("https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb", deb, ARANGO_SHA256);
+    let installed = await run(["/usr/bin/dpkg", "-i", deb], { DEBIAN_FRONTEND: "noninteractive" });
+    if (installed.exitCode !== 0)
+      installed = await run(["/usr/bin/apt-get", "-y", "-f", "install"], { DEBIAN_FRONTEND: "noninteractive" });
+    if (installed.exitCode !== 0)
+      return installed;
+    await run(["/usr/bin/systemctl", "disable", "--now", "arangodb3.service"]);
+    return { exitCode: 0, output: "" };
+  } finally {
+    rmSync3(directory, { recursive: true, force: true });
+  }
+}
 function observeSoftwareHost(osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
@@ -744,7 +872,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", "nginx", "arangodb", "cloudflared", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].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 };
@@ -770,15 +898,15 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
     const strategy = UBUNTU_2604_X64.find(({ requirement: candidate }) => candidate.id === requirement.id && candidate.version === requirement.version);
     if (!strategy)
       throw new Error(`unsupported software requirement: ${requirement.id}@${requirement.version}`);
-    const before = await options.exec(strategy.check);
+    const before = await options.exec({ kind: "check", software: requirement.id, version: requirement.version });
     if (before.exitCode === 0) {
       results.push({ ...requirement, changed: false });
       continue;
     }
-    const installed = await options.exec(strategy.install);
+    const installed = await options.exec({ kind: "install", software: requirement.id, version: requirement.version });
     if (installed.exitCode !== 0)
       throw new Error(`could not install ${requirement.id}@${requirement.version}: ${installed.output.trim()}`);
-    const after = await options.exec(strategy.check);
+    const after = await options.exec({ kind: "check", software: requirement.id, version: requirement.version });
     if (after.exitCode !== 0)
       throw new Error(`${requirement.id}@${requirement.version} did not pass its post-install check`);
     results.push({ ...requirement, changed: true });
@@ -786,34 +914,671 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
   return results;
 }
 
+// src/capacity-calibration.ts
+var percentile95 = (values) => {
+  if (values.length === 0)
+    return Number.POSITIVE_INFINITY;
+  const sorted = values.toSorted((left, right) => left - right);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)];
+};
+function localCalibrationEndpoint(value) {
+  const endpoint = new URL(value);
+  if (endpoint.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname) || !endpoint.port || endpoint.username || endpoint.password || endpoint.hash) {
+    throw new Error("Capacity calibration requires an explicit loopback HTTP endpoint and port.");
+  }
+  return endpoint;
+}
+function validateCapacityCalibrationOptions(options) {
+  const endpoint = localCalibrationEndpoint(options.endpoint);
+  const maxConcurrency = options.maxConcurrency ?? 256;
+  const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maxP95Ms = options.maxP95Ms ?? 250;
+  const maxErrorRate = options.maxErrorRate ?? 0.01;
+  const headroomRatio = options.headroomRatio ?? 0.8;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(headroomRatio) || headroomRatio < 0.25 || headroomRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000) {
+    throw new Error("Capacity calibration bounds are invalid.");
+  }
+  return {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    headroomRatio,
+    requestTimeoutMs
+  };
+}
+async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher) {
+  const latencies = [];
+  let succeeded = 0;
+  let failed = 0;
+  let overloaded = 0;
+  const started = performance.now();
+  await Promise.all(Array.from({ length: concurrency }, async () => {
+    for (let request = 0;request < requestsPerWorker; request += 1) {
+      const requestStarted = performance.now();
+      try {
+        const response = await fetcher(endpoint, {
+          method: "GET",
+          headers: { accept: "application/json", "user-agent": "forgezero-capacity-calibration/1" },
+          signal: AbortSignal.timeout(timeoutMs),
+          redirect: "error"
+        });
+        await response.body?.cancel();
+        if (response.ok)
+          succeeded += 1;
+        else {
+          failed += 1;
+          if (response.status === 503)
+            overloaded += 1;
+        }
+      } catch {
+        failed += 1;
+      } finally {
+        latencies.push(performance.now() - requestStarted);
+      }
+    }
+  }));
+  const elapsedSeconds = Math.max((performance.now() - started) / 1000, 0.001);
+  return {
+    concurrency,
+    requests: concurrency * requestsPerWorker,
+    succeeded,
+    failed,
+    overloaded,
+    throughputPerSecond: Number(((succeeded + failed) / elapsedSeconds).toFixed(2)),
+    p95Ms: Number(percentile95(latencies).toFixed(2))
+  };
+}
+async function calibrateHttpConcurrency(options, fetcher = fetch) {
+  const {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    headroomRatio,
+    requestTimeoutMs: timeoutMs
+  } = validateCapacityCalibrationOptions(options);
+  const stages = [];
+  let lastSafe = 1;
+  let stopReason = "maximum-tested";
+  for (let concurrency = 1;; concurrency = Math.min(maxConcurrency, concurrency * 2)) {
+    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher);
+    stages.push(measured);
+    const errorRate = measured.failed / measured.requests;
+    const previous = stages.at(-2);
+    const throughputRegressed = Boolean(previous && concurrency > 1 && measured.throughputPerSecond < previous.throughputPerSecond * 0.9);
+    if (measured.overloaded > 0 || errorRate > maxErrorRate)
+      stopReason = "errors";
+    else if (measured.p95Ms > maxP95Ms)
+      stopReason = "latency";
+    else if (throughputRegressed)
+      stopReason = "throughput-regression";
+    else
+      lastSafe = concurrency;
+    if (stopReason !== "maximum-tested" || concurrency === maxConcurrency)
+      break;
+  }
+  return {
+    endpoint: endpoint.toString(),
+    recommendedConcurrency: Math.max(1, Math.floor(lastSafe * headroomRatio)),
+    stopReason,
+    stages
+  };
+}
+
+// src/definition.ts
+var PIPELINE_VERSION = 3;
+var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v3.json";
+
+class DefinitionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DefinitionError";
+  }
+}
+var record = (value, where) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new DefinitionError(`${where} must be an object.`);
+  }
+  return value;
+};
+var text = (value, where) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new DefinitionError(`${where} must be a non-empty string.`);
+  }
+  return value;
+};
+var argv = (value, where) => {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 256) {
+    throw new DefinitionError(`${where} must contain from 1 to 256 arguments.`);
+  }
+  let bytes = 0;
+  const parsed = value.map((argument, index) => {
+    if (typeof argument !== "string" || argument.length === 0 || argument.length > 16384 || argument.includes("\x00")) {
+      throw new DefinitionError(`${where}[${index}] must be a non-empty bounded string without NUL.`);
+    }
+    if (argument.includes("${") && !/^\$\{FZ_[A-Z0-9_]+\}$/.test(argument)) {
+      throw new DefinitionError(`${where}[${index}] contains unsupported interpolation; only one exact FZ coordinate is allowed.`);
+    }
+    bytes += Buffer.byteLength(argument);
+    if (bytes > 64 * 1024)
+      throw new DefinitionError(`${where} is larger than 64 KiB.`);
+    return argument;
+  });
+  const executable = parsed[0].split("/").at(-1).toLowerCase();
+  if (new Set(["sh", "bash", "dash", "zsh", "ksh", "fish", "busybox", "env"]).has(executable)) {
+    throw new DefinitionError(`${where}[0] may not invoke a shell or command dispatcher.`);
+  }
+  return parsed;
+};
+var exactKeys = (value, allowed, where) => {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0)
+    throw new DefinitionError(`${where} contains unknown field(s): ${unknown.join(", ")}.`);
+};
+var NAME = /^[a-z][a-z0-9-]{0,62}$/;
+var RESERVED_STEP_ENV = new Set([
+  "PATH",
+  "HOME",
+  "SHELL",
+  "PWD",
+  "BUN_INSTALL",
+  "NODE_OPTIONS",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "GIT_SSH",
+  "GIT_SSH_COMMAND"
+]);
+function capacityCalibration(value, where) {
+  const calibration = record(value, where);
+  exactKeys(calibration, [
+    "endpoint",
+    "maxConcurrency",
+    "requestsPerWorker",
+    "maxP95Ms",
+    "maxErrorRate",
+    "headroomRatio",
+    "requestTimeoutMs"
+  ], where);
+  const endpoint = text(calibration.endpoint, `${where}.endpoint`);
+  try {
+    localCalibrationEndpoint(endpoint);
+  } catch (cause) {
+    throw new DefinitionError(cause instanceof Error ? cause.message : `${where}.endpoint is invalid.`);
+  }
+  const optionalNumber = (name) => {
+    const raw = calibration[name];
+    if (raw === undefined)
+      return;
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      throw new DefinitionError(`${where}.${name} must be a finite number.`);
+    }
+    return raw;
+  };
+  const parsed = {
+    endpoint,
+    ...Object.fromEntries([
+      "maxConcurrency",
+      "requestsPerWorker",
+      "maxP95Ms",
+      "maxErrorRate",
+      "headroomRatio",
+      "requestTimeoutMs"
+    ].flatMap((name) => {
+      const found = optionalNumber(name);
+      return found === undefined ? [] : [[name, found]];
+    }))
+  };
+  try {
+    validateCapacityCalibrationOptions(parsed);
+  } catch (cause) {
+    throw new DefinitionError(cause instanceof Error ? cause.message : `${where} bounds are invalid.`);
+  }
+  return parsed;
+}
+function validateDeploymentService(value, where = "service") {
+  const service = record(value, where);
+  exactKeys(service, [
+    "strategy",
+    "publicPort",
+    "applicationPorts",
+    "command",
+    "healthPath",
+    "maxConnections",
+    "websocket",
+    "drainMs"
+  ], where);
+  if (service.strategy !== "direct" && service.strategy !== "blue-green") {
+    throw new DefinitionError(`${where}.strategy must be direct or blue-green.`);
+  }
+  const publicPort = Number(service.publicPort);
+  if (!Number.isSafeInteger(publicPort) || publicPort < 1024 || publicPort > 65535) {
+    throw new DefinitionError(`${where}.publicPort must be an unprivileged TCP port.`);
+  }
+  const allocation = record(service.applicationPorts, `${where}.applicationPorts`);
+  let applicationPorts;
+  const required = service.strategy === "blue-green" ? 2 : 1;
+  if (allocation.mode === "fixed") {
+    exactKeys(allocation, ["mode", "ports"], `${where}.applicationPorts`);
+    if (!Array.isArray(allocation.ports) || allocation.ports.length !== required || allocation.ports.some((port) => !Number.isSafeInteger(port) || Number(port) < 1024 || Number(port) > 65535) || new Set(allocation.ports).size !== allocation.ports.length || allocation.ports.includes(publicPort)) {
+      throw new DefinitionError(`${where}.applicationPorts needs ${required} distinct unprivileged port(s), disjoint from publicPort.`);
+    }
+    applicationPorts = { mode: "fixed", ports: allocation.ports };
+  } else if (allocation.mode === "dynamic") {
+    exactKeys(allocation, ["mode", "from", "to"], `${where}.applicationPorts`);
+    const from = Number(allocation.from);
+    const to = Number(allocation.to);
+    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 1024 || to > 65535 || to - from + 1 < required || publicPort >= from && publicPort <= to) {
+      throw new DefinitionError(`${where}.applicationPorts dynamic range is invalid or includes publicPort.`);
+    }
+    applicationPorts = { mode: "dynamic", from, to };
+  } else
+    throw new DefinitionError(`${where}.applicationPorts.mode must be fixed or dynamic.`);
+  const command2 = argv(service.command, `${where}.command`);
+  for (const argument of command2) {
+    const coordinate = argument.match(/^\$\{(FZ_[A-Z0-9_]+)\}$/)?.[1];
+    if (coordinate && !["FZ_APP_PORT", "FZ_RELEASE"].includes(coordinate)) {
+      throw new DefinitionError(`${where}.command uses unsupported coordinate ${coordinate}.`);
+    }
+  }
+  if (typeof service.healthPath !== "string" || !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{0,255}$/.test(service.healthPath) || service.healthPath.includes("..") || service.healthPath.includes("//")) {
+    throw new DefinitionError(`${where}.healthPath must be one bounded absolute path.`);
+  }
+  if (service.websocket !== undefined && typeof service.websocket !== "boolean") {
+    throw new DefinitionError(`${where}.websocket must be a boolean.`);
+  }
+  const maxConnections = service.maxConnections === undefined ? undefined : Number(service.maxConnections);
+  if (maxConnections !== undefined && (!Number.isSafeInteger(maxConnections) || maxConnections < 1 || maxConnections > 1e6)) {
+    throw new DefinitionError(`${where}.maxConnections must be from 1 to 1000000.`);
+  }
+  const drainMs = service.drainMs === undefined ? 30000 : Number(service.drainMs);
+  if (!Number.isSafeInteger(drainMs) || drainMs < 0 || drainMs > 300000) {
+    throw new DefinitionError(`${where}.drainMs must be from 0 to 300000.`);
+  }
+  return {
+    strategy: service.strategy,
+    publicPort,
+    applicationPorts,
+    command: command2,
+    healthPath: service.healthPath,
+    ...maxConnections === undefined ? {} : { maxConnections },
+    websocket: service.websocket === true,
+    drainMs
+  };
+}
+function parseDeployDefinition(value, options = {}) {
+  const root = record(value, "pipeline");
+  exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
+  if (root.$schema !== undefined && root.$schema !== DEPLOY_SCHEMA_URL) {
+    throw new DefinitionError(`pipeline.$schema must be ${DEPLOY_SCHEMA_URL}.`);
+  }
+  if (root.version !== PIPELINE_VERSION) {
+    throw new DefinitionError(`pipeline.version must be ${PIPELINE_VERSION}.`);
+  }
+  if (root.requireAttestation !== undefined && typeof root.requireAttestation !== "boolean") {
+    throw new DefinitionError("pipeline.requireAttestation must be a boolean.");
+  }
+  const rawProfiles = record(root.profiles, "pipeline.profiles");
+  const profileEntries = Object.entries(rawProfiles);
+  if (profileEntries.length === 0 || profileEntries.length > 32) {
+    throw new DefinitionError("pipeline.profiles must contain from 1 to 32 named profiles.");
+  }
+  if (!Array.isArray(root.steps) || root.steps.length === 0 || root.steps.length > 256) {
+    throw new DefinitionError("pipeline.steps must contain from 1 to 256 steps.");
+  }
+  const profiles = {};
+  for (const [name2, raw] of profileEntries) {
+    if (!NAME.test(name2))
+      throw new DefinitionError(`pipeline profile name is invalid: ${name2}.`);
+    const profile = record(raw, `profiles.${name2}`);
+    exactKeys(profile, ["software", "service", "capacityCalibration"], `profiles.${name2}`);
+    if (!Array.isArray(profile.software)) {
+      throw new DefinitionError(`profiles.${name2}.software must be an array.`);
+    }
+    const software = validateSoftwareRequirements(profile.software, options);
+    const service = profile.service === undefined ? undefined : validateDeploymentService(profile.service, `profiles.${name2}.service`);
+    if (service && !software.some(({ id }) => id === "nginx")) {
+      throw new DefinitionError(`profiles.${name2}.service requires the reviewed nginx software strategy.`);
+    }
+    profiles[name2] = {
+      software,
+      ...profile.service === undefined ? {} : {
+        service
+      },
+      ...profile.capacityCalibration === undefined ? {} : {
+        capacityCalibration: capacityCalibration(profile.capacityCalibration, `profiles.${name2}.capacityCalibration`)
+      }
+    };
+  }
+  const phases = new Set(["build", "release", "migrate", "health"]);
+  const steps = root.steps.map((raw, index) => {
+    const step = record(raw, `steps[${index}]`);
+    exactKeys(step, ["name", "exec", "phase", "scope", "profiles", "secrets", "always", "timeoutMs", "when"], `steps[${index}]`);
+    const phase = text(step.phase, `steps[${index}].phase`);
+    if (!phases.has(phase))
+      throw new DefinitionError(`steps[${index}].phase is not supported.`);
+    if (step.scope !== "target" && step.scope !== "release") {
+      throw new DefinitionError(`steps[${index}].scope must be target or release.`);
+    }
+    if (step.always !== undefined && typeof step.always !== "boolean") {
+      throw new DefinitionError(`steps[${index}].always must be a boolean.`);
+    }
+    let selectedProfiles;
+    if (step.profiles !== undefined) {
+      if (!Array.isArray(step.profiles) || step.profiles.length === 0 || step.profiles.some((name2) => typeof name2 !== "string" || !Object.hasOwn(profiles, name2))) {
+        throw new DefinitionError(`steps[${index}].profiles must name existing profiles.`);
+      }
+      selectedProfiles = [...step.profiles];
+      if (new Set(selectedProfiles).size !== selectedProfiles.length) {
+        throw new DefinitionError(`steps[${index}].profiles must not contain duplicates.`);
+      }
+    }
+    if (step.secrets !== undefined && (!Array.isArray(step.secrets) || step.secrets.some((name2) => typeof name2 !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name2)))) {
+      throw new DefinitionError(`steps[${index}].secrets must contain names only.`);
+    }
+    if (Array.isArray(step.secrets) && new Set(step.secrets).size !== step.secrets.length) {
+      throw new DefinitionError(`steps[${index}].secrets must not contain duplicates.`);
+    }
+    if (Array.isArray(step.secrets) && step.secrets.some((name2) => RESERVED_STEP_ENV.has(String(name2)))) {
+      throw new DefinitionError(`steps[${index}].secrets may not replace process-control environment variables.`);
+    }
+    const timeoutMs = step.timeoutMs === undefined ? undefined : Number(step.timeoutMs);
+    if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 86400000)) {
+      throw new DefinitionError(`steps[${index}].timeoutMs must be an integer from 1 to 86400000.`);
+    }
+    let when;
+    if (step.when !== undefined) {
+      const conditions = record(step.when, `steps[${index}].when`);
+      when = {};
+      for (const [name2, expected] of Object.entries(conditions)) {
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name2) || typeof expected !== "string" || expected.length === 0) {
+          throw new DefinitionError(`steps[${index}].when must map environment names to non-empty strings.`);
+        }
+        when[name2] = expected;
+      }
+      if (Object.keys(when).length === 0)
+        throw new DefinitionError(`steps[${index}].when must not be empty.`);
+    }
+    return {
+      name: text(step.name, `steps[${index}].name`),
+      exec: argv(step.exec, `steps[${index}].exec`),
+      phase,
+      scope: step.scope,
+      profiles: selectedProfiles,
+      secrets: step.secrets,
+      always: step.always === true,
+      timeoutMs,
+      when
+    };
+  });
+  if (new Set(steps.map((step) => step.name)).size !== steps.length) {
+    throw new DefinitionError("pipeline.steps must have unique names.");
+  }
+  for (const [profile, selected] of Object.entries(profiles)) {
+    if (selected.capacityCalibration && !steps.some((step) => step.phase === "health" && step.scope === "target" && (!step.profiles || step.profiles.includes(profile)))) {
+      throw new DefinitionError(`profiles.${profile}.capacityCalibration requires a target-scoped health step.`);
+    }
+  }
+  const name = text(root.name, "pipeline.name");
+  if (name.length > 120)
+    throw new DefinitionError("pipeline.name must be at most 120 characters.");
+  return {
+    version: PIPELINE_VERSION,
+    name,
+    requireAttestation: root.requireAttestation === true,
+    profiles,
+    steps
+  };
+}
+function phasePipeline(definition, phase, profile, executeRelease = false) {
+  if (!Object.hasOwn(definition.profiles, profile)) {
+    throw new DefinitionError(`pipeline profile does not exist: ${profile}.`);
+  }
+  return {
+    name: `${definition.name}:${phase}`,
+    requireAttestation: definition.requireAttestation,
+    steps: definition.steps.filter((step) => step.phase === phase && (!step.profiles || step.profiles.includes(profile)) && (step.scope === "target" || executeRelease))
+  };
+}
+
 // src/software-helper.ts
-import { chmodSync as chmodSync3, existsSync as existsSync3, mkdirSync as mkdirSync3, unlinkSync as unlinkSync2 } from "node:fs";
+import { chmodSync as chmodSync4, existsSync as existsSync4, mkdirSync as mkdirSync5, unlinkSync as unlinkSync3 } from "node:fs";
 import { connect as connect2, createServer as createServer2 } from "node:net";
-import { dirname as dirname3 } from "node:path";
+import { dirname as dirname4 } from "node:path";
+
+// src/service-supervisor.ts
+import { createHash as createHash3 } from "node:crypto";
+import { existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync4, readdirSync, realpathSync, renameSync as renameSync4, rmSync as rmSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname3, join as join4, resolve as resolve3, sep } from "node:path";
+var SERVICE_STATE_DIRECTORY = "/var/lib/forgezero/services";
+var SERVICE_CONFIG_DIRECTORY = "/etc/forgezero/services";
+var SERVICE_UNIT_DIRECTORY = "/etc/systemd/system";
+var SERVICE_NGINX_DIRECTORY = "/etc/nginx/conf.d";
+var idFor = (key) => createHash3("sha256").update(key).digest("hex").slice(0, 24);
+var statePath = (id) => `${SERVICE_STATE_DIRECTORY}/${id}.json`;
+var within = (root, path2) => path2 === root || path2.startsWith(`${root}${sep}`);
+var defaultHost = {
+  write(path2, content, mode) {
+    mkdirSync4(dirname3(path2), { recursive: true, mode: 493 });
+    const next = `${path2}.next`;
+    writeFileSync4(next, content, { mode });
+    renameSync4(next, path2);
+  },
+  read: (path2) => readFileSync4(path2, "utf8"),
+  exists: existsSync3,
+  list: (path2) => existsSync3(path2) ? readdirSync(path2) : [],
+  realpath: realpathSync,
+  mkdir: (path2, mode) => mkdirSync4(path2, { recursive: true, mode }),
+  remove: (path2) => rmSync4(path2, { force: true }),
+  async exec(argv2) {
+    const child = Bun.spawn([...argv2], { stdout: "pipe", stderr: "pipe", env: {
+      PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+      LANG: "C",
+      LC_ALL: "C"
+    } });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited
+    ]);
+    return { exitCode, output: `${stdout}${stderr}` };
+  },
+  async health(port, path2) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}${path2}`, {
+        signal: AbortSignal.timeout(2000),
+        redirect: "manual"
+      });
+      return response.status >= 200 && response.status < 300;
+    } catch {
+      return false;
+    }
+  },
+  sleep: (ms) => Bun.sleep(ms),
+  now: Date.now
+};
+function readState(host, path2) {
+  if (!host.exists(path2))
+    return null;
+  try {
+    const value = JSON.parse(host.read(path2));
+    return value?.format === 1 && Array.isArray(value.applicationPorts) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function allStates(host) {
+  return host.list(SERVICE_STATE_DIRECTORY).filter((name) => /^[a-f0-9]{24}\.json$/.test(name)).flatMap((name) => {
+    const state = readState(host, join4(SERVICE_STATE_DIRECTORY, name));
+    return state ? [state] : [];
+  });
+}
+function allocatedPorts(request, id, previous, states) {
+  const required = request.service.strategy === "blue-green" ? 2 : 1;
+  const occupied = new Set(states.filter((state) => state.id !== id).flatMap((state) => [state.publicPort, ...state.applicationPorts]));
+  if (occupied.has(request.service.publicPort))
+    throw new Error("SERVICE_PUBLIC_PORT_CONFLICT");
+  const allocation = request.service.applicationPorts;
+  if (allocation.mode === "fixed") {
+    if (allocation.ports.some((port) => occupied.has(port)))
+      throw new Error("SERVICE_APPLICATION_PORT_CONFLICT");
+    return [...allocation.ports];
+  }
+  if (previous && previous.applicationPorts.length === required && previous.applicationPorts.every((port) => port >= allocation.from && port <= allocation.to && !occupied.has(port)))
+    return [...previous.applicationPorts];
+  const width = allocation.to - allocation.from + 1;
+  const start = Number.parseInt(createHash3("sha256").update(request.key).digest("hex").slice(0, 8), 16) % width;
+  for (let offset = 0;offset < width; offset += 1) {
+    const first = allocation.from + (start + offset) % width;
+    const candidate = Array.from({ length: required }, (_, index) => first + index);
+    if (candidate.at(-1) <= allocation.to && candidate.every((port) => !occupied.has(port) && port !== request.service.publicPort)) {
+      return candidate;
+    }
+  }
+  throw new Error("SERVICE_DYNAMIC_PORTS_EXHAUSTED");
+}
+var appConfig = (request, port) => `${JSON.stringify({
+  format: 1,
+  root: request.root,
+  release: request.release,
+  home: `${request.root}/app-home`,
+  argv: request.service.command.map((argument) => argument === "${FZ_APP_PORT}" ? String(port) : argument === "${FZ_RELEASE}" ? request.release : argument),
+  environment: { FZ_APP_PORT: String(port), FZ_RELEASE: request.release }
+}, null, 2)}
+`;
+var unit = (id, slot) => `[Unit]
+Description=ForgeZero supervised tenant application ${id} slot ${slot}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=forgezero-app
+Group=forgezero-vault
+ExecStart=/usr/local/lib/forgezero/agent/fz-agent supervised-app --config=${SERVICE_CONFIG_DIRECTORY}/${id}-slot${slot}.json
+Restart=always
+RestartSec=2
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+LimitCORE=0
+
+[Install]
+WantedBy=multi-user.target
+`;
+var nginx = (request, id, port) => `# ForgeZero ${id}
+${request.service.maxConnections ? `limit_conn_zone $server_name zone=fz_${id}:64k;
+` : ""}server {
+  listen 127.0.0.1:${request.service.publicPort};
+  server_name _;
+${request.service.maxConnections ? `  limit_conn fz_${id} ${request.service.maxConnections};
+  limit_conn_status 503;
+` : ""}  location / {
+    proxy_pass http://127.0.0.1:${port};
+    proxy_http_version 1.1;
+${request.service.websocket ? `    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+` : ""}    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+}
+`;
+async function checked2(host, argv2, code) {
+  const result = await host.exec(argv2);
+  if (result.exitCode !== 0)
+    throw new Error(`${code}: ${result.output.slice(0, 512)}`);
+}
+async function activateSupervisedService(request, host = defaultHost) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/.test(request.key) || !/^[a-f0-9]{40}$/.test(request.revision)) {
+    throw new Error("SERVICE_IDENTITY_INVALID");
+  }
+  const root = host.realpath(resolve3(request.root));
+  const release = host.realpath(resolve3(request.release));
+  if (!within(root, release))
+    throw new Error("SERVICE_RELEASE_OUTSIDE_ROOT");
+  request = { ...request, root, release, service: validateDeploymentService(request.service) };
+  const id = idFor(request.key);
+  host.mkdir(SERVICE_STATE_DIRECTORY, 448);
+  host.mkdir(SERVICE_CONFIG_DIRECTORY, 457);
+  const previous = readState(host, statePath(id));
+  const ports = allocatedPorts(request, id, previous, allStates(host));
+  const nextSlot = request.service.strategy === "blue-green" ? previous?.activeSlot === 0 ? 1 : 0 : 0;
+  const port = ports[nextSlot] ?? ports[0];
+  const configPath = `${SERVICE_CONFIG_DIRECTORY}/${id}-slot${nextSlot}.json`;
+  const unitName = `forgezero-app-${id}-slot${nextSlot}.service`;
+  host.write(configPath, appConfig({ ...request, release }, port), 292);
+  host.write(`${SERVICE_UNIT_DIRECTORY}/${unitName}`, unit(id, nextSlot), 420);
+  await checked2(host, ["/usr/bin/systemctl", "daemon-reload"], "SERVICE_UNIT_RELOAD_FAILED");
+  if (request.service.strategy === "direct" && previous) {
+    await host.exec(["/usr/bin/systemctl", "stop", `forgezero-app-${id}-slot${previous.activeSlot}.service`]);
+  }
+  await checked2(host, ["/usr/bin/systemctl", "restart", unitName], "SERVICE_START_FAILED");
+  let healthy = false;
+  for (let attempt = 0;attempt < 30; attempt += 1) {
+    const active = await host.exec(["/usr/bin/systemctl", "is-active", "--quiet", unitName]);
+    if (active.exitCode === 0 && await host.health(port, request.service.healthPath)) {
+      healthy = true;
+      break;
+    }
+    await host.sleep(1000);
+  }
+  if (!healthy) {
+    await host.exec(["/usr/bin/systemctl", "stop", unitName]);
+    throw new Error("SERVICE_HEALTH_FAILED");
+  }
+  const nginxPath = `${SERVICE_NGINX_DIRECTORY}/forgezero-${id}.conf`;
+  const oldNginx = host.exists(nginxPath) ? host.read(nginxPath) : null;
+  try {
+    host.write(nginxPath, nginx(request, id, port), 420);
+    await checked2(host, ["/usr/sbin/nginx", "-t"], "SERVICE_NGINX_INVALID");
+    await checked2(host, ["/usr/bin/systemctl", "reload", "nginx.service"], "SERVICE_NGINX_RELOAD_FAILED");
+  } catch (cause) {
+    if (oldNginx === null)
+      host.remove(nginxPath);
+    else
+      host.write(nginxPath, oldNginx, 420);
+    await host.exec(["/usr/bin/systemctl", "stop", unitName]);
+    throw cause;
+  }
+  const state = {
+    format: 1,
+    id,
+    key: request.key,
+    revision: request.revision,
+    strategy: request.service.strategy,
+    publicPort: request.service.publicPort,
+    applicationPorts: ports,
+    activeSlot: nextSlot,
+    healthPath: request.service.healthPath,
+    updatedAtTs: host.now()
+  };
+  host.write(statePath(id), `${JSON.stringify(state, null, 2)}
+`, 384);
+  if (request.service.strategy === "blue-green" && previous && previous.activeSlot !== nextSlot) {
+    await host.sleep(request.service.drainMs ?? 30000);
+    await host.exec(["/usr/bin/systemctl", "stop", `forgezero-app-${id}-slot${previous.activeSlot}.service`]);
+  }
+  return state;
+}
+
+// src/software-helper.ts
 var DEFAULT_SOFTWARE_HELPER_SOCKET = "/run/forgezero-software/helper.sock";
 var SOFTWARE_HELPER_GROUP = "forgezero-software";
 var SOFTWARE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-software-helper.service";
-var MAX_REQUEST_BYTES2 = 8 * 1024;
+var MAX_REQUEST_BYTES2 = 128 * 1024;
 var MAX_PENDING_REQUESTS = 128;
-var execute = async (command2) => {
-  const child = Bun.spawn(["/bin/bash", "-Eeuo", "pipefail", "-c", command2], {
-    stdout: "pipe",
-    stderr: "pipe",
-    env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }
-  });
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-    child.exited
-  ]);
-  return { exitCode, output: `${stdout}${stderr}` };
-};
 function startSoftwareHelper(options = {}) {
   const socketPath = options.socketPath ?? DEFAULT_SOFTWARE_HELPER_SOCKET;
-  if (existsSync3(socketPath))
-    unlinkSync2(socketPath);
-  mkdirSync3(dirname3(socketPath), { recursive: true, mode: 488 });
+  if (existsSync4(socketPath))
+    unlinkSync3(socketPath);
+  mkdirSync5(dirname4(socketPath), { recursive: true, mode: 488 });
   const ensure = options.ensure ?? ensureSoftwareRequirements;
+  const activate = options.activate ?? activateSupervisedService;
   let tail = Promise.resolve();
   let pending = 0;
   const server = createServer2((socket) => {
@@ -838,12 +1603,23 @@ function startSoftwareHelper(options = {}) {
       }
       pending += 1;
       const work = tail.then(() => Promise.resolve().then(() => JSON.parse(line)).then(async (request) => {
-        if (request.op !== "ensure")
-          throw new Error("unknown software helper operation");
-        const requirements = validateSoftwareRequirements(request.requirements);
-        const results = await ensure(requirements, { exec: execute });
-        socket.end(`${JSON.stringify({ ok: true, results })}
+        if (request.op === "ensure") {
+          const requirements = validateSoftwareRequirements(request.requirements);
+          const results = await ensure(requirements, { exec: executeSoftwareOperation });
+          socket.end(`${JSON.stringify({ ok: true, results })}
+`);
+          return;
+        }
+        if (request.op === "activate-service" && request.request) {
+          if (!options.allowedRoot || request.request.root !== options.allowedRoot) {
+            throw new Error("service deployment root is not owned by this helper");
+          }
+          const state = await activate(request.request);
+          socket.end(`${JSON.stringify({ ok: true, state })}
 `);
+          return;
+        }
+        throw new Error("unknown software helper operation");
       }).catch((cause) => socket.end(`${JSON.stringify({
         ok: false,
         error: { code: "SOFTWARE_REFUSED", message: cause instanceof Error ? cause.message : String(cause) }
@@ -859,12 +1635,40 @@ function startSoftwareHelper(options = {}) {
     });
     socket.on("error", () => socket.destroy());
   });
-  server.listen(socketPath, () => chmodSync3(socketPath, 432));
+  server.listen(socketPath, () => chmodSync4(socketPath, 432));
   return server;
 }
+function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 10 * 60000) {
+  return new Promise((resolve4, reject) => {
+    const socket = connect2(socketPath, () => socket.write(`${JSON.stringify({ op: "activate-service", request })}
+`));
+    let buffer = "";
+    socket.setTimeout(timeoutMs, () => {
+      socket.destroy();
+      reject(new Error("service helper timed out"));
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.end();
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        if (!response.ok || !response.state)
+          throw new Error(response.error?.message ?? "service helper refused activation");
+        resolve4(response.state);
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
 function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
   validateSoftwareRequirements(requirements);
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const socket = connect2(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
 `));
     let buffer = "";
@@ -883,7 +1687,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
         const response = JSON.parse(buffer.slice(0, newline));
         if (!response.ok || !response.results)
           throw new Error(response.error?.message ?? "software helper refused the request");
-        resolve3(response.results);
+        resolve4(response.results);
       } catch (cause) {
         reject(cause);
       }
@@ -893,11 +1697,10 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.41";
+var VERSION3 = "0.1.42";
 
 // src/egress-policy.ts
-import { realpathSync } from "node:fs";
-var AGENT_EGRESS_TABLE = "forgezero_agent_egress";
+import { realpathSync as realpathSync2 } from "node:fs";
 var SYSTEMD_RESOLVED_ADDRESS = "127.0.0.53";
 var BLOCKED_IPV4 = [
   "0.0.0.0/8",
@@ -976,22 +1779,26 @@ function atLeast(version, floor) {
 }
 var CAPABILITY_CHECKS = {
   snpGuest: {
-    command: "test -e /dev/sev-guest && echo yes || echo no",
+    command: "fz host check-device /dev/sev-guest",
+    operation: { kind: "path-exists", path: "/dev/sev-guest", nodeType: "file" },
     satisfied: (stdout) => stdout.trim() === "yes",
     remedy: "Not a confidential guest. The agent will run in `enrolled` mode, which is still stronger than an API key in the application."
   },
   systemd: {
-    command: "test -d /run/systemd/system && echo yes || echo no",
+    command: "fz host check-directory /run/systemd/system",
+    operation: { kind: "path-exists", path: "/run/systemd/system", nodeType: "directory" },
     satisfied: (stdout) => stdout.trim() === "yes",
     remedy: "systemd is what supervises the agent. On a non-systemd host, run `fz-agent` under whatever supervises services there."
   },
   bun: {
-    command: "bun --version 2>/dev/null || echo missing",
+    command: "fz host check-version bun",
+    operation: { kind: "version", argv: ["/usr/local/bin/bun", "--version"] },
     satisfied: (stdout) => atLeast(stdout, "1.1.0"),
-    remedy: "Install bun: curl -fsSL https://bun.sh/install | bash"
+    remedy: "Install the pinned Bun release with `fz bootstrap`."
   },
   python: {
-    command: "python3 --version 2>/dev/null || echo missing",
+    command: "fz host check-version python3",
+    operation: { kind: "version", argv: ["/usr/bin/python3", "--version"] },
     satisfied: (stdout, exitCode) => exitCode === 0 && /^Python 3\./.test(stdout.trim()),
     remedy: "Install Python 3. It supplies the standard-library ioctl boundary for SNP reports."
   }
@@ -999,6 +1806,7 @@ var CAPABILITY_CHECKS = {
 var modeFor = (capabilities) => capabilities.snpGuest ? "attested" : "enrolled";
 var reasonFor = (mode) => mode === "attested" ? "SEV-SNP guest device present, so the agent can prove what it is running and the platform can refuse it if the measurement is wrong." : "No SEV-SNP guest device. The agent authenticates with its enrolment token and hybrid Ed25519 + ML-DSA signature — weaker than attestation, stronger than an API key in the application.";
 var DEPLOYMENT_RUNNER_USER = "forgezero-runner";
+var APPLICATION_RUNTIME_USER = "forgezero-app";
 var DEPLOYMENT_GROUP = "forgezero-deploy";
 var VAULT_GROUP = "forgezero-vault";
 var LIFECYCLE_GROUP = "forgezero-lifecycle";
@@ -1028,11 +1836,7 @@ function agentEgressUnit(options) {
     systemdAgentEgressDirectives(runnerLoopbackPorts);
   const users = [user, ...deploymentEnabled ? [DEPLOYMENT_RUNNER_USER] : []];
   const runnerGrant = deploymentEnabled ? ` --loopback-user=${DEPLOYMENT_RUNNER_USER}` + runnerLoopbackPorts.map((port) => ` --loopback-tcp-port=${port}`).join("") + runnerPublicTcpPorts.map((port) => ` --public-tcp-port=${port}`).join("") : "";
-  const policyProofs = deploymentEnabled ? [
-    ...runnerLoopbackPorts.length > 0 ? [`loopback=.*:${runnerLoopbackPorts.join(",")}`] : [],
-    `public-tcp=${runnerPublicTcpPorts.join(",")}`
-  ].map((pattern) => `ExecStartPost=/bin/sh -c '/usr/sbin/nft --numeric list table inet ${AGENT_EGRESS_TABLE} | /usr/bin/grep -q "${pattern}"'`).join(`
-`) : "";
+  const policyProof = `ExecStartPost=${bin} egress-policy-check ${users.map((name) => `--user=${name}`).join(" ")}${runnerGrant}`;
   return `[Unit]
 Description=ForgeZero Agent host egress policy
 Documentation=https://www.forgezero.net/docs/agent
@@ -1046,7 +1850,7 @@ NotifyAccess=all
 User=root
 Group=root
 ExecStart=${bin} egress-policy ${users.map((name) => `--user=${name}`).join(" ")}${runnerGrant}
-${policyProofs}
+${policyProof}
 Restart=on-failure
 RestartSec=2
 LimitCORE=0
@@ -1070,6 +1874,7 @@ WantedBy=multi-user.target
 }
 function softwareHelperUnit(options) {
   const bin = options.binPath ?? "fz-agent";
+  const root = options.deployRoot ?? "/opt/forgezero";
   return `[Unit]
 Description=ForgeZero declarative software strategy helper
 Documentation=https://www.forgezero.net/docs/agent
@@ -1081,6 +1886,7 @@ Type=simple
 User=root
 Group=${SOFTWARE_HELPER_GROUP}
 Environment=FZ_SOFTWARE_HELPER_SOCKET=${DEFAULT_SOFTWARE_HELPER_SOCKET}
+Environment=FZ_DEPLOY_ROOT=${root}
 ExecStart=${bin} software-helper
 Restart=always
 RestartSec=2
@@ -1196,10 +2002,6 @@ var systemdPath = (value, label) => {
     throw new Error(`invalid ${label} path`);
   return value;
 };
-var awaitSocketCommand = (path) => {
-  const socket = systemdPath(path, "readiness socket");
-  return `for attempt in $(seq 1 100); do test -S ${socket} && exit 0; sleep 0.1; done; exit 1`;
-};
 var validNodeHostname = (value) => !value || value.length <= 253 && value === value.toLowerCase() && value.split(".").length >= 3 && value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
 function warpConfigUnit(options) {
   if (!options.warpOrganization || !/^[a-z0-9][a-z0-9-]{0,62}$/i.test(options.warpOrganization)) {
@@ -1300,6 +2102,8 @@ function agentEnrolmentUnit(options) {
   const hostname = options.nodeHostname ? `Environment=FZ_NODE_HOSTNAME=${options.nodeHostname}
 ` : "";
   const gitPublicKey = options.gitPublicKeyPath ? `Environment=FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}
+` : "";
+  const bootstrapSshPublicKey = options.bootstrapSshPublicKeyPath ? `Environment=FZ_BOOTSTRAP_SSH_PUBLIC_KEY_FILE=${options.bootstrapSshPublicKeyPath}
 ` : "";
   const networkAttachment = [
     options.cloudflareAccountId ? `Environment=FZ_CF_ACCOUNT_ID=${options.cloudflareAccountId}
@@ -1334,7 +2138,7 @@ Environment=FZ_SEED_CREDENTIAL=agent-seed
 Environment=FZ_ENROL_TOKEN_CREDENTIAL=enrol-token
 Environment=FZ_ENROL_STATE_FILE=${options.enrolStatePath}
 Environment=FZ_API=${options.apiUrl}
-${label}${hostname}${gitPublicKey}${networkAttachment}ExecStart=${bin} enrol
+${label}${hostname}${gitPublicKey}${bootstrapSshPublicKey}${networkAttachment}ExecStart=${bin} enrol
 # A '+' fixed command runs as root solely to remove the host-bound one-time
 # ciphertext. Tenant code and the agent never receive a privilege boundary.
 ExecStartPost=+/usr/bin/rm -f ${options.enrolTokenCredentialPath}
@@ -1428,9 +2232,14 @@ function agentUnit(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
-  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapTargetTelemetryEndpoint);
-  if ([options.pullBootstrap, options.bootstrapSshCredentialPath, options.bootstrapTargetTelemetryEndpoint].some(Boolean) && !bootstrapEnabled) {
-    throw new Error("bootstrap pull, SSH credential and target telemetry endpoint must be supplied together");
+  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapSshPublicKeyPath && options.bootstrapTargetTelemetryEndpoint);
+  if ([
+    options.pullBootstrap,
+    options.bootstrapSshCredentialPath,
+    options.bootstrapSshPublicKeyPath,
+    options.bootstrapTargetTelemetryEndpoint
+  ].some(Boolean) && !bootstrapEnabled) {
+    throw new Error("bootstrap pull, SSH credential, public key and target telemetry endpoint must be supplied together");
   }
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
   const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
@@ -1465,8 +2274,8 @@ function agentUnit(options) {
       throw new Error(`invalid deployment environment entry: ${name}`);
     }
   }
-  for (const [name, path] of Object.entries(deploymentCredentials)) {
-    if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || !path.startsWith("/") || /[\r\n:]/.test(path)) {
+  for (const [name, path2] of Object.entries(deploymentCredentials)) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || !path2.startsWith("/") || /[\r\n:]/.test(path2)) {
       throw new Error(`invalid deployment credential entry: ${name}`);
     }
   }
@@ -1501,6 +2310,7 @@ function agentUnit(options) {
     options.pullMigrations ? "FZ_MIGRATION_PULL=true" : null,
     options.pullBootstrap ? "FZ_BOOTSTRAP_PULL=true" : null,
     options.pullBootstrap ? "FZ_BOOTSTRAP_SSH_KEY_CREDENTIAL=bootstrap-ssh-key" : null,
+    options.pullBootstrap && options.bootstrapSshPublicKeyPath ? `FZ_BOOTSTRAP_SSH_PUBLIC_KEY_FILE=${options.bootstrapSshPublicKeyPath}` : null,
     options.pullBootstrap ? `FZ_BOOTSTRAP_TARGET_OTLP_ENDPOINT=${options.bootstrapTargetTelemetryEndpoint}` : null,
     `FZ_AGENT_UPDATE_SOCKET=${DEFAULT_AGENT_UPDATE_SOCKET}`,
     options.pullMigrations ? `FZ_LIFECYCLE_HELPER_SOCKET=${lifecycleHelperSocketPath}` : null
@@ -1512,7 +2322,7 @@ function agentUnit(options) {
 ` : "";
   const bootstrapCredential = bootstrapEnabled ? `LoadCredentialEncrypted=bootstrap-ssh-key:${bootstrapSshCredentialPath}
 ` : "";
-  const projectCredentials = Object.entries(deploymentCredentials).map(([name, path]) => `LoadCredentialEncrypted=${name}:${path}`).join(`
+  const projectCredentials = Object.entries(deploymentCredentials).map(([name, path2]) => `LoadCredentialEncrypted=${name}:${path2}`).join(`
 `);
   const deploymentWrites = deploymentEnabled ? `ReadWritePaths=${deployRoot}/releases ${deployRoot}/agent-home ${deployRoot}/cache ${deployRoot}/capacity` : "";
   const supplementaryGroups = [
@@ -1606,6 +2416,55 @@ ${deploymentWrites}
 WantedBy=multi-user.target
 `;
 }
+var renderOperation = (operation) => {
+  if (operation.kind === "commands")
+    return operation.commands.map(({ argv: argv2 }) => argv2.join(" ")).join(`
+`);
+  if (operation.kind === "directories")
+    return operation.directories.map((directory) => [
+      "/usr/bin/install",
+      "-d",
+      ...directory.owner ? ["-o", directory.owner] : [],
+      ...directory.group ? ["-g", directory.group] : [],
+      "-m",
+      directory.mode.toString(8).padStart(4, "0"),
+      directory.path
+    ].join(" ")).join(`
+`);
+  if (operation.kind === "install-runtime")
+    return `/usr/bin/install -m 0755 ${operation.source} /opt/forgezero/agent/versions/${operation.version}/dist/fz-agent.js`;
+  if (operation.kind === "ensure-seed")
+    return `/usr/bin/systemd-creds encrypt --name=agent-seed - ${operation.credential}`;
+  if (operation.kind === "ensure-git-identity")
+    return `/usr/bin/ssh-keygen -t ed25519
+/usr/bin/systemd-creds encrypt --name=git-deploy-key <private> ${operation.credential}
+fz host write-public-key ${operation.publicKey}`;
+  if (operation.kind === "ensure-bootstrap-ssh-identity")
+    return `/usr/bin/ssh-keygen -t ed25519
+/usr/bin/systemd-creds encrypt --name=bootstrap-ssh-key <private> ${operation.credential}
+fz host write-public-key ${operation.publicKey}`;
+  if (operation.kind === "ensure-enrolment")
+    return `/usr/bin/systemd-creds encrypt --name=enrol-token ${operation.source} ${operation.credential}
+/usr/bin/rm -f ${operation.source}`;
+  if (operation.kind === "wait-socket")
+    return `fz host wait-socket ${operation.path}`;
+  if (operation.kind === "verify-file")
+    return `fz host verify-file ${operation.path}`;
+  if (operation.kind === "verify-egress")
+    return `/usr/sbin/nft --numeric list table inet forgezero_agent_egress
+fz-agent egress-policy-check`;
+  if (operation.kind === "verify-resolved-stub")
+    return "fz host verify-resolved-stub /run/systemd/resolve/stub-resolv.conf";
+  if (operation.kind === "install-warp")
+    return "/usr/bin/apt-get install -y cloudflare-warp";
+  return "/usr/bin/warp-cli --accept-tos status";
+};
+var step = (label, operation, optional = false) => ({
+  label,
+  operation,
+  optional: optional || undefined,
+  command: renderOperation(operation)
+});
 var UNIT_PATH = "/etc/systemd/system/forgezero-agent.service";
 function planProvision(options) {
   const mode = options.mode;
@@ -1620,9 +2479,15 @@ function planProvision(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
-  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapTargetTelemetryEndpoint);
-  if ([options.pullBootstrap, options.bootstrapSshCredentialPath, options.bootstrapTargetTelemetryEndpoint].some(Boolean) && !bootstrapEnabled) {
-    throw new Error("bootstrap pull, SSH credential and target telemetry endpoint must be supplied together");
+  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapSshPublicKeyPath && options.bootstrapTargetTelemetryEndpoint);
+  if ([
+    options.pullBootstrap,
+    options.bootstrapSshCredentialPath,
+    options.bootstrapSshPublicKeyPath,
+    options.bootstrapSshSourcePath,
+    options.bootstrapTargetTelemetryEndpoint
+  ].some(Boolean) && !bootstrapEnabled) {
+    throw new Error("bootstrap pull, SSH credential, public key and target telemetry endpoint must be supplied together");
   }
   const warpValues = [
     options.warpOrganization,
@@ -1650,8 +2515,29 @@ function planProvision(options) {
   const lifecycleProfilePath = lifecycleEnabled ? systemdPath(options.lifecycleProfilePath, "lifecycle profile") : undefined;
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
   const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
+  const bootstrapSshPublicKeyPath = bootstrapEnabled ? systemdPath(options.bootstrapSshPublicKeyPath, "bootstrap SSH public key") : undefined;
+  const bootstrapSshSourcePath = options.bootstrapSshSourcePath ? systemdPath(options.bootstrapSshSourcePath, "bootstrap SSH private-key source") : undefined;
+  const bootstrapSshPublicKeyDir = bootstrapSshPublicKeyPath?.replace(/\/[^/]+$/, "");
   const warpClientIdCredentialPath = warpEnabled ? systemdPath(options.warpClientIdCredentialPath, "WARP client-id credential") : undefined;
   const warpClientSecretCredentialPath = warpEnabled ? systemdPath(options.warpClientSecretCredentialPath, "WARP client-secret credential") : undefined;
+  const enabledUnits = [
+    "forgezero-agent.socket",
+    "forgezero-agent-update-helper.service",
+    ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
+    ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
+    ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
+    ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
+    ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : [],
+    "forgezero-agent.service"
+  ];
+  const restartedUnits = [
+    "forgezero-agent-update-helper.service",
+    ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
+    ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
+    ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
+    ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
+    ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : []
+  ];
   return {
     mode,
     reason: reasonFor(mode),
@@ -1696,146 +2582,91 @@ function planProvision(options) {
     socketPath: options.socketPath,
     user,
     steps: [
-      ...options.enforceEgress ? [{
-        label: "Ubuntu Agent egress prerequisites",
-        command: `. /etc/os-release; test "$ID" = ubuntu; ` + `DEBIAN_FRONTEND=noninteractive apt-get update -qq; ` + `DEBIAN_FRONTEND=noninteractive apt-get install -y nftables; ` + `systemctl enable --now systemd-resolved.service; ` + `test "$(readlink -f /etc/resolv.conf)" = /run/systemd/resolve/stub-resolv.conf; ` + `test -s /run/systemd/resolve/stub-resolv.conf`
-      }] : [],
-      {
-        label: "vault socket access group",
-        command: `groupadd --system ${VAULT_GROUP} || true`
-      },
-      {
-        label: "Agent update helper access group",
-        command: `groupadd --system ${AGENT_UPDATE_GROUP} || true`
-      },
-      ...sourceBinPath && binPath ? [{
-        label: "root-owned agent runtime",
-        command: `install -d -o root -g root -m 0755 ${binPath.replace(/\/[^/]+$/, "")} ` + `${DEFAULT_AGENT_RELEASE_ROOT}/versions/${VERSION3}/dist; ` + `install -o root -g root -m 0755 ${sourceBinPath} ` + `${DEFAULT_AGENT_RELEASE_ROOT}/versions/${VERSION3}/dist/fz-agent.js; ` + `ln -sfn versions/${VERSION3} ${DEFAULT_AGENT_RELEASE_ROOT}/current.next; ` + `mv -Tf ${DEFAULT_AGENT_RELEASE_ROOT}/current.next ${DEFAULT_AGENT_RELEASE_ROOT}/current; ` + `rm -f ${binPath}; ln -s ${DEFAULT_AGENT_RELEASE_ROOT}/current/dist/fz-agent.js ${binPath}`
-      }] : [],
-      ...warpEnabled ? [{
-        label: "Cloudflare One client for Ubuntu 26.04",
-        command: `. /etc/os-release; test "$ID" = ubuntu && test "$VERSION_ID" = 26.04; ` + `install -d -m 0755 /usr/share/keyrings /etc/apt/sources.list.d /etc/systemd/system/warp-svc.service.d; ` + `curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg -o /run/cloudflare-warp-key.gpg; ` + `gpg --batch --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg /run/cloudflare-warp-key.gpg; ` + `rm -f /run/cloudflare-warp-key.gpg; ` + `printf 'deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ %s main\\n' "$VERSION_CODENAME" > /etc/apt/sources.list.d/cloudflare-client.list; ` + `apt-get update -qq; DEBIAN_FRONTEND=noninteractive apt-get install -y cloudflare-warp`
-      }] : [],
-      ...deploymentEnabled ? [{
-        label: "deployment isolation group",
-        command: `groupadd --system ${DEPLOYMENT_GROUP} || true; groupadd --system ${SOFTWARE_HELPER_GROUP} || true`
-      }] : [],
-      ...lifecycleEnabled ? [{
-        label: "lifecycle helper access group",
-        command: `groupadd --system ${LIFECYCLE_GROUP} || true`
-      }] : [],
-      {
-        label: "service account",
-        command: `useradd --system --no-create-home --shell /usr/sbin/nologin ${user} || true`
-      },
-      {
-        label: "bind service account to vault group",
-        command: `usermod -g ${VAULT_GROUP} ${user}`
-      },
-      {
-        label: "grant verified Agent update access",
-        command: `usermod -a -G ${AGENT_UPDATE_GROUP} ${user}`
-      },
-      ...lifecycleEnabled ? [{
-        label: "grant lifecycle helper socket access",
-        command: `usermod -a -G ${LIFECYCLE_GROUP} ${user}`
-      }] : [],
-      ...deploymentEnabled ? [{
-        label: "credential-free deployment account",
-        command: `useradd --system --no-create-home --shell /usr/sbin/nologin --gid ${DEPLOYMENT_GROUP} ${DEPLOYMENT_RUNNER_USER} || true; ` + `usermod -a -G ${DEPLOYMENT_GROUP},${SOFTWARE_HELPER_GROUP} ${user}`
-      }] : [],
-      {
-        label: "credential directory",
-        command: `install -d -o root -g root -m 0700 ${credentialDir}`
-      },
-      {
-        label: "Agent state directory",
-        command: "install -d -o root -g root -m 0750 /var/lib/forgezero"
-      },
-      {
-        label: "encrypted node identity",
-        command: `test -s ${seedCredentialPath} || { ` + `openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\\n' | ` + `systemd-creds encrypt --name=agent-seed - ${seedCredentialPath}; ` + `chmod 0400 ${seedCredentialPath}; }`
-      },
+      ...options.enforceEgress ? [step("Ubuntu Agent egress prerequisites", { kind: "commands", commands: [
+        { argv: ["/usr/bin/apt-get", "update", "-qq"] },
+        { argv: ["/usr/bin/apt-get", "install", "-y", "nftables"] },
+        { argv: ["/usr/bin/systemctl", "enable", "--now", "systemd-resolved.service"] }
+      ] }), step("prove systemd-resolved stub ownership", { kind: "verify-resolved-stub" })] : [],
+      step("vault socket access group", { kind: "commands", commands: [{ argv: ["/usr/sbin/groupadd", "--system", VAULT_GROUP], acceptedExitCodes: [0, 9] }] }),
+      step("Agent update helper access group", { kind: "commands", commands: [{ argv: ["/usr/sbin/groupadd", "--system", AGENT_UPDATE_GROUP], acceptedExitCodes: [0, 9] }] }),
+      ...sourceBinPath && binPath ? [step("root-owned agent runtime", { kind: "install-runtime", source: sourceBinPath, binary: binPath, version: VERSION3 })] : [],
+      ...warpEnabled ? [step("Cloudflare One client for Ubuntu 26.04", { kind: "install-warp" })] : [],
+      ...deploymentEnabled ? [step("deployment isolation group", { kind: "commands", commands: [
+        { argv: ["/usr/sbin/groupadd", "--system", DEPLOYMENT_GROUP], acceptedExitCodes: [0, 9] },
+        { argv: ["/usr/sbin/groupadd", "--system", SOFTWARE_HELPER_GROUP], acceptedExitCodes: [0, 9] }
+      ] })] : [],
+      ...lifecycleEnabled ? [step("lifecycle helper access group", { kind: "commands", commands: [{ argv: ["/usr/sbin/groupadd", "--system", LIFECYCLE_GROUP], acceptedExitCodes: [0, 9] }] })] : [],
+      step("service account", { kind: "commands", commands: [{ argv: ["/usr/sbin/useradd", "--system", "--no-create-home", "--shell", "/usr/sbin/nologin", user], acceptedExitCodes: [0, 9] }] }),
+      step("bind service account to vault group", { kind: "commands", commands: [{ argv: ["/usr/sbin/usermod", "-g", VAULT_GROUP, user] }] }),
+      step("grant verified Agent update access", { kind: "commands", commands: [{ argv: ["/usr/sbin/usermod", "-a", "-G", AGENT_UPDATE_GROUP, user] }] }),
+      ...lifecycleEnabled ? [step("grant lifecycle helper socket access", { kind: "commands", commands: [{ argv: ["/usr/sbin/usermod", "-a", "-G", LIFECYCLE_GROUP, user] }] })] : [],
+      ...deploymentEnabled ? [step("credential-free deployment account", { kind: "commands", commands: [
+        { argv: ["/usr/sbin/useradd", "--system", "--no-create-home", "--shell", "/usr/sbin/nologin", "--gid", DEPLOYMENT_GROUP, DEPLOYMENT_RUNNER_USER], acceptedExitCodes: [0, 9] },
+        { argv: ["/usr/sbin/useradd", "--system", "--no-create-home", "--shell", "/usr/sbin/nologin", "--gid", VAULT_GROUP, APPLICATION_RUNTIME_USER], acceptedExitCodes: [0, 9] },
+        { argv: ["/usr/sbin/usermod", "-a", "-G", DEPLOYMENT_GROUP, APPLICATION_RUNTIME_USER] },
+        { argv: ["/usr/sbin/usermod", "-a", "-G", `${DEPLOYMENT_GROUP},${SOFTWARE_HELPER_GROUP}`, user] }
+      ] })] : [],
+      step("credential and state directories", { kind: "directories", directories: [
+        { path: credentialDir, mode: 448, owner: "root", group: "root" },
+        { path: "/var/lib/forgezero", mode: 488, owner: "root", group: "root" }
+      ] }),
+      step("encrypted node identity", { kind: "ensure-seed", credential: seedCredentialPath }),
       ...options.generateGitIdentity && gitCredentialPath && gitPublicKeyPath ? [
-        {
-          label: "Git deploy identity directory",
-          command: `install -d -o root -g root -m 0755 ${gitPublicKeyDir}`
-        },
-        {
-          label: "unique encrypted Git deploy identity",
-          command: `test -s ${gitCredentialPath} || { ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; ` + `ssh-keygen -q -t ed25519 -N '' -C forgezero-compute -f /run/forgezero-git-deploy-key; ` + `systemd-creds encrypt --name=git-deploy-key /run/forgezero-git-deploy-key ${gitCredentialPath}; ` + `install -o root -g root -m 0444 /run/forgezero-git-deploy-key.pub ${gitPublicKeyPath}; ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; ` + `chmod 0400 ${gitCredentialPath}; }; ` + `test -s ${gitPublicKeyPath} || { ` + `systemd-creds decrypt --name=git-deploy-key ${gitCredentialPath} /run/forgezero-git-deploy-key; ` + `ssh-keygen -y -f /run/forgezero-git-deploy-key | ` + `sed 's/$/ forgezero-compute/' > /run/forgezero-git-deploy-key.pub; ` + `install -o root -g root -m 0444 /run/forgezero-git-deploy-key.pub ${gitPublicKeyPath}; ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; }; ` + `test -s ${gitCredentialPath} && test -s ${gitPublicKeyPath}`
-        }
+        step("Git deploy identity directory", { kind: "directories", directories: [{ path: gitPublicKeyDir, mode: 493, owner: "root", group: "root" }] }),
+        step("unique encrypted Git deploy identity", { kind: "ensure-git-identity", credential: gitCredentialPath, publicKey: gitPublicKeyPath })
+      ] : [],
+      ...bootstrapEnabled ? [
+        step("bootstrap SSH public identity directory", { kind: "directories", directories: [
+          { path: bootstrapSshPublicKeyDir, mode: 493, owner: "root", group: "root" }
+        ] }),
+        step("unique encrypted bootstrap SSH identity", {
+          kind: "ensure-bootstrap-ssh-identity",
+          credential: bootstrapSshCredentialPath,
+          publicKey: bootstrapSshPublicKeyPath,
+          ...bootstrapSshSourcePath ? { source: bootstrapSshSourcePath } : {}
+        })
       ] : [],
       ...enrolmentEnabled ? [
-        {
-          label: "enrolment state directory",
-          command: `install -d -o ${user} -g ${user} -m 0700 ${enrolStateDir}`
-        },
-        {
-          label: "encrypted one-time enrolment capability",
-          command: `test -s ${enrolStatePath} || test -s ${enrolTokenCredentialPath} || { test -r ${enrolTokenSourcePath}; ` + `systemd-creds encrypt --name=enrol-token ${enrolTokenSourcePath} ${enrolTokenCredentialPath}; ` + `chmod 0400 ${enrolTokenCredentialPath}; rm -f ${enrolTokenSourcePath}; }`
-        }
+        step("enrolment state directory", { kind: "directories", directories: [{ path: enrolStateDir, mode: 448, owner: user, group: user }] }),
+        step("encrypted one-time enrolment capability", { kind: "ensure-enrolment", state: enrolStatePath, source: enrolTokenSourcePath, credential: enrolTokenCredentialPath })
       ] : [],
-      ...deploymentEnabled ? [{
-        label: "deployment directories",
-        command: `install -d -o root -g root -m 0755 ${deployRoot} && ` + `install -d -o root -g ${DEPLOYMENT_GROUP} -m 3770 ${deployRoot}/releases && ` + `install -d -o ${user} -g ${user} -m 0750 ${deployRoot}/cache && ` + `install -d -o ${user} -g ${user} -m 0700 ${deployRoot}/capacity && ` + `install -d -o ${user} -g ${user} -m 0700 ${deployRoot}/agent-home && ` + `install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0700 ${deployRoot}/runner-home ${deployRoot}/runner-home/cache`
-      }] : [],
-      { label: "reload units", command: "systemctl daemon-reload" },
-      ...deploymentEnabled ? [{
-        label: "remove unsupported deployment socket activation",
-        command: "systemctl disable --now forgezero-deploy-runner.socket 2>/dev/null || true; rm -f /etc/systemd/system/forgezero-deploy-runner.socket; systemctl daemon-reload"
-      }] : [],
-      {
-        label: "enable and converge services",
-        command: `systemctl enable ${[
-          "forgezero-agent.socket",
-          "forgezero-agent-update-helper.service",
-          ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
-          ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
-          ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
-          ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
-          ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : [],
-          "forgezero-agent.service"
-        ].join(" ")}; systemctl reset-failed forgezero-agent.service || true; systemctl restart ${[
-          "forgezero-agent-update-helper.service",
-          ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
-          ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
-          ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
-          ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
-          ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : []
-        ].join(" ")}; systemctl restart forgezero-agent.socket; systemctl reset-failed forgezero-agent.service || true; systemctl restart forgezero-agent.service`
-      },
-      ...enrolmentEnabled ? [{
-        label: "prove the compute binding is durable",
-        command: `test -s ${enrolStatePath}`
-      }] : [],
-      ...options.enforceEgress ? [{
-        label: "prove the Agent egress policy is active",
-        command: "systemctl is-active forgezero-agent-egress.service && " + "nft --numeric list table inet forgezero_agent_egress | grep -q forgezero-agent-egress-v1" + (deploymentEnabled ? ` && nft --numeric list table inet forgezero_agent_egress | grep -q 'public-tcp=${runnerPublicTcpPorts.join(",")}'` + (runnerLoopbackPorts.length > 0 ? ` && nft --numeric list table inet forgezero_agent_egress | grep -Eq 'loopback=[0-9]+:${runnerLoopbackPorts.join(",")}( |")'` : "") : "")
-      }] : [],
-      { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
-      { label: "prove the public Vault socket exists", command: awaitSocketCommand(options.socketPath) },
-      { label: "prove the Agent Vault backend exists", command: awaitSocketCommand(agentBackendSocketPath(options.socketPath)) },
-      { label: "prove the Agent update helper exists", command: awaitSocketCommand(DEFAULT_AGENT_UPDATE_SOCKET) },
-      ...deploymentEnabled ? [{
-        label: "prove the deployment runner socket exists",
-        command: awaitSocketCommand(DEPLOYMENT_RUNNER_SOCKET)
-      }, {
-        label: "prove the software strategy helper socket exists",
-        command: awaitSocketCommand(DEFAULT_SOFTWARE_HELPER_SOCKET)
-      }] : [],
-      ...lifecycleEnabled ? [{
-        label: "prove the lifecycle helper socket exists",
-        command: awaitSocketCommand(lifecycleHelperSocketPath)
-      }] : [],
-      ...warpEnabled ? [{
-        label: "prove Cloudflare WARP is connected",
-        command: `warp-cli --accept-tos status | grep -Eiq '(^|[[:space:]])Connected([[:space:]]|$)'`
-      }] : [],
-      ...options.repository ? [{
-        label: "prove the deployment control socket exists",
-        command: awaitSocketCommand(options.controlSocketPath ?? "/run/forgezero/control.sock")
-      }] : []
+      ...deploymentEnabled ? [step("deployment directories", { kind: "directories", directories: [
+        { path: deployRoot, mode: 493, owner: "root", group: "root" },
+        { path: `${deployRoot}/releases`, mode: 2040, owner: "root", group: DEPLOYMENT_GROUP },
+        { path: `${deployRoot}/cache`, mode: 488, owner: user, group: user },
+        { path: `${deployRoot}/capacity`, mode: 448, owner: user, group: user },
+        { path: `${deployRoot}/agent-home`, mode: 448, owner: user, group: user },
+        { path: `${deployRoot}/runner-home`, mode: 448, owner: DEPLOYMENT_RUNNER_USER, group: DEPLOYMENT_GROUP },
+        { path: `${deployRoot}/runner-home/cache`, mode: 448, owner: DEPLOYMENT_RUNNER_USER, group: DEPLOYMENT_GROUP },
+        { path: `${deployRoot}/app-home`, mode: 448, owner: APPLICATION_RUNTIME_USER, group: VAULT_GROUP }
+      ] })] : [],
+      step("reload units", { kind: "commands", commands: [{ argv: ["/usr/bin/systemctl", "daemon-reload"] }] }),
+      ...deploymentEnabled ? [step("remove unsupported deployment socket activation", { kind: "commands", commands: [
+        { argv: ["/usr/bin/systemctl", "disable", "--now", "forgezero-deploy-runner.socket"], acceptedExitCodes: [0, 1, 5] },
+        { argv: ["/usr/bin/rm", "-f", "/etc/systemd/system/forgezero-deploy-runner.socket"] },
+        { argv: ["/usr/bin/systemctl", "daemon-reload"] }
+      ] })] : [],
+      step("enable and converge services", { kind: "commands", commands: [
+        { argv: ["/usr/bin/systemctl", "enable", ...enabledUnits] },
+        { argv: ["/usr/bin/systemctl", "reset-failed", "forgezero-agent.service"], acceptedExitCodes: [0, 1] },
+        ...restartedUnits.length ? [{ argv: ["/usr/bin/systemctl", "restart", ...restartedUnits] }] : [],
+        { argv: ["/usr/bin/systemctl", "restart", "forgezero-agent.socket"] },
+        { argv: ["/usr/bin/systemctl", "reset-failed", "forgezero-agent.service"], acceptedExitCodes: [0, 1] },
+        { argv: ["/usr/bin/systemctl", "restart", "forgezero-agent.service"] }
+      ] }),
+      ...enrolmentEnabled ? [step("prove the compute binding is durable", { kind: "verify-file", path: enrolStatePath })] : [],
+      ...options.enforceEgress ? [step("prove the Agent egress policy is active", { kind: "verify-egress", runnerPublicTcpPorts, runnerLoopbackPorts })] : [],
+      step("prove it is running", { kind: "commands", commands: [{ argv: ["/usr/bin/systemctl", "is-active", "forgezero-agent.service"] }] }),
+      step("prove the public Vault socket exists", { kind: "wait-socket", path: options.socketPath, attempts: 100, intervalMs: 100 }),
+      step("prove the Agent Vault backend exists", { kind: "wait-socket", path: agentBackendSocketPath(options.socketPath), attempts: 100, intervalMs: 100 }),
+      step("prove the Agent update helper exists", { kind: "wait-socket", path: DEFAULT_AGENT_UPDATE_SOCKET, attempts: 100, intervalMs: 100 }),
+      ...deploymentEnabled ? [
+        step("prove the deployment runner socket exists", { kind: "wait-socket", path: DEPLOYMENT_RUNNER_SOCKET, attempts: 100, intervalMs: 100 }),
+        step("prove the software strategy helper socket exists", { kind: "wait-socket", path: DEFAULT_SOFTWARE_HELPER_SOCKET, attempts: 100, intervalMs: 100 })
+      ] : [],
+      ...lifecycleEnabled ? [step("prove the lifecycle helper socket exists", { kind: "wait-socket", path: lifecycleHelperSocketPath, attempts: 100, intervalMs: 100 })] : [],
+      ...warpEnabled ? [step("prove Cloudflare WARP is connected", { kind: "verify-warp" })] : [],
+      ...options.repository ? [step("prove the deployment control socket exists", { kind: "wait-socket", path: options.controlSocketPath ?? "/run/forgezero/control.sock", attempts: 100, intervalMs: 100 })] : []
     ]
   };
 }
@@ -1870,6 +2701,7 @@ export {
   DEPLOYMENT_GROUP,
   DEFAULT_RUNNER_PUBLIC_TCP_PORTS,
   CAPABILITY_CHECKS,
+  APPLICATION_RUNTIME_USER,
   AGENT_SOCKET_UNIT_PATH,
   AGENT_SOCKET_PROXY_UNIT_PATH,
   AGENT_EGRESS_UNIT_PATH