@forgezero/agent 0.1.41 → 0.1.42

package/dist/deploy-file.js

@@ -1,7 +1,22 @@
 // src/software.ts
-import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import {
+  accessSync,
+  chmodSync,
+  copyFileSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } 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 = [
@@ -12,41 +27,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 (createHash("sha256").update(bytes).digest("hex") !== sha256)
+    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) => {
+  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(join(tmpdir(), "forgezero-software-"));
+  try {
+    if (software === "cloudflare-warp") {
+      const key = join(directory, "cloudflare-warp-key.gpg");
+      await download("https://pkg.cloudflareclient.com/pubkey.gpg", key, "0f37fc298c98e88ee3c0ee68c95b69f1dba9eb477abe3167e13982105911264d");
+      mkdirSync("/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;
+      mkdirSync("/etc/apt/sources.list.d", { recursive: true, mode: 493 });
+      writeFileSync("/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 = join(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 = join(directory, "unpacked");
+      mkdirSync(unpacked, { mode: 448 });
+      const unzipped = await run(["/usr/bin/unzip", "-q", archive, "-d", unpacked]);
+      if (unzipped.exitCode !== 0)
+        return unzipped;
+      mkdirSync("/usr/local/lib/forgezero/runtime", { recursive: true, mode: 493 });
+      copyFileSync(join(unpacked, "bun-linux-x64", "bun"), "/usr/local/lib/forgezero/runtime/bun.next");
+      chmodSync("/usr/local/lib/forgezero/runtime/bun.next", 493);
+      renameSync("/usr/local/lib/forgezero/runtime/bun.next", "/usr/local/lib/forgezero/runtime/bun");
+      try {
+        unlinkSync("/usr/local/bin/bun");
+      } catch {}
+      symlinkSync("/usr/local/lib/forgezero/runtime/bun", "/usr/local/bin/bun");
+      return { exitCode: 0, output: "" };
+    }
+    if (software === "cloudflared") {
+      const binary = join(directory, "cloudflared");
+      await download("https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64", binary, CLOUDFLARED_SHA256);
+      chmodSync(binary, 493);
+      copyFileSync(binary, "/usr/local/bin/cloudflared");
+      chmodSync("/usr/local/bin/cloudflared", 493);
+      return { exitCode: 0, output: "" };
+    }
+    const deb = join(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 {
+    rmSync(directory, { recursive: true, force: true });
+  }
+}
 function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
@@ -69,7 +194,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 };
@@ -95,15 +220,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 });
@@ -227,8 +352,8 @@ async function calibrateHttpConcurrency(options, fetcher = fetch) {
 }
 
 // src/definition.ts
-var PIPELINE_VERSION = 2;
-var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
+var PIPELINE_VERSION = 3;
+var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v3.json";
 
 class DefinitionError extends Error {
   constructor(message) {
@@ -248,6 +373,29 @@ var text = (value, where) => {
   }
   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)
@@ -313,6 +461,76 @@ function capacityCalibration(value, where) {
   }
   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 command = argv(service.command, `${where}.command`);
+  for (const argument of command) {
+    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,
+    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");
@@ -330,20 +548,28 @@ function parseDeployDefinition(value, options = {}) {
   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) {
-    throw new DefinitionError("pipeline.steps must contain at least one step.");
+  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", "capacityCalibration"], `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: validateSoftwareRequirements(profile.software, options),
+      software,
+      ...profile.service === undefined ? {} : {
+        service
+      },
       ...profile.capacityCalibration === undefined ? {} : {
         capacityCalibration: capacityCalibration(profile.capacityCalibration, `profiles.${name2}.capacityCalibration`)
       }
@@ -352,7 +578,7 @@ function parseDeployDefinition(value, options = {}) {
   const phases = new Set(["build", "release", "migrate", "health"]);
   const steps = root.steps.map((raw, index) => {
     const step = record(raw, `steps[${index}]`);
-    exactKeys(step, ["name", "run", "phase", "scope", "profiles", "secrets", "always", "timeoutMs", "when"], `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.`);
@@ -400,7 +626,7 @@ function parseDeployDefinition(value, options = {}) {
     }
     return {
       name: text(step.name, `steps[${index}].name`),
-      run: text(step.run, `steps[${index}].run`),
+      exec: argv(step.exec, `steps[${index}].exec`),
       phase,
       scope: step.scope,
       profiles: selectedProfiles,
@@ -441,9 +667,9 @@ function phasePipeline(definition, phase, profile, executeRelease = false) {
 }
 
 // src/deploy-file.ts
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { basename, join as join2 } from "node:path";
 var DEPLOY_FILE = ".fz/deploy.json";
 var DEPLOY_TODO_PREFIX = "ForgeZero pipeline TODO:";
 var stable = (value) => {
@@ -455,28 +681,28 @@ var stable = (value) => {
   return JSON.stringify(value);
 };
 function deployDefinitionDigest(definition) {
-  return `sha256:${createHash("sha256").update(stable(definition)).digest("hex")}`;
+  return `sha256:${createHash2("sha256").update(stable(definition)).digest("hex")}`;
 }
 var safeName = (value) => {
   const normalized = value.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63);
   return /^[a-z]/.test(normalized) ? normalized : `app-${normalized || "service"}`.slice(0, 63);
 };
 function packageHints(root) {
-  const packagePath = join(root, "package.json");
+  const packagePath = join2(root, "package.json");
   if (!existsSync(packagePath))
-    return { bun: existsSync(join(root, "bun.lock")) };
+    return { bun: existsSync(join2(root, "bun.lock")) };
   try {
     const manifest = JSON.parse(readFileSync2(packagePath, "utf8"));
     return {
       name: typeof manifest.name === "string" ? manifest.name : undefined,
-      build: typeof manifest.scripts?.build === "string" ? "bun run build" : undefined,
-      bun: existsSync(join(root, "bun.lock")) || existsSync(join(root, "bun.lockb"))
+      build: typeof manifest.scripts?.build === "string" ? ["bun", "run", "build"] : undefined,
+      bun: existsSync(join2(root, "bun.lock")) || existsSync(join2(root, "bun.lockb"))
     };
   } catch {
-    return { bun: existsSync(join(root, "bun.lock")) };
+    return { bun: existsSync(join2(root, "bun.lock")) };
   }
 }
-var blocker = (instruction) => `printf '%s\\n' '${DEPLOY_TODO_PREFIX} ${instruction}' >&2; exit 78`;
+var blocker = (instruction) => ["fz-agent", "pipeline-todo", `${DEPLOY_TODO_PREFIX} ${instruction}`];
 function defaultDeployFile(root, options = {}) {
   const hints = packageHints(root);
   const software = options.software ?? (hints.bun ? SOFTWARE_CATALOG.filter((entry) => entry.id === "bun" && entry.status === "active").map(({ id, version }) => ({ id, version })) : []);
@@ -485,42 +711,42 @@ function defaultDeployFile(root, options = {}) {
   const build = hints.build ?? blocker("replace the build step with the project build command");
   return {
     $schema: DEPLOY_SCHEMA_URL,
-    version: 2,
+    version: 3,
     name: safeName(options.name ?? hints.name ?? basename(root)),
     ...options.requireAttestation ? { requireAttestation: true } : {},
     profiles: { [profile]: { software } },
     steps: [
-      { name: "build", phase: "build", scope: "target", run: build, timeoutMs: 600000 },
+      { name: "build", phase: "build", scope: "target", exec: build, timeoutMs: 600000 },
       {
         name: "promote release",
         phase: "release",
         scope: "target",
-        run: blocker("replace the release step with an atomic promotion command"),
+        exec: blocker("replace the release step with an atomic promotion command"),
         timeoutMs: 120000
       },
       {
         name: "health check",
         phase: "health",
         scope: "target",
-        run: blocker("replace the health step with a bounded local health check"),
+        exec: blocker("replace the health step with a bounded local health check"),
         timeoutMs: 30000
       }
     ]
   };
 }
 function inspectDeployFile(root, options = {}) {
-  const path = join(root, DEPLOY_FILE);
-  if (!existsSync(path))
+  const path2 = join2(root, DEPLOY_FILE);
+  if (!existsSync(path2))
     throw new Error(`${DEPLOY_FILE} does not exist; run \`fz deploy init\`.`);
-  const raw = JSON.parse(readFileSync2(path, "utf8"));
+  const raw = JSON.parse(readFileSync2(path2, "utf8"));
   const definition = parseDeployDefinition(raw, options);
-  const problems = definition.steps.filter((step) => step.run.includes(DEPLOY_TODO_PREFIX)).map((step) => `${step.name} still contains the safe initialization blocker`);
+  const problems = definition.steps.filter((step) => step.exec.some((argument) => argument.includes(DEPLOY_TODO_PREFIX))).map((step) => `${step.name} still contains the safe initialization blocker`);
   const profiles = Object.keys(definition.profiles).sort();
   return {
-    path,
+    path: path2,
     definition,
     summary: {
-      path,
+      path: path2,
       digest: deployDefinitionDigest(definition),
       version: definition.version,
       name: definition.name,
@@ -535,14 +761,14 @@ function inspectDeployFile(root, options = {}) {
   };
 }
 function initializeDeployFile(root, options = {}) {
-  const path = join(root, DEPLOY_FILE);
-  if (existsSync(path) && !options.force) {
+  const path2 = join2(root, DEPLOY_FILE);
+  if (existsSync(path2) && !options.force) {
     throw new Error(`${DEPLOY_FILE} already exists; use --force only when replacing it deliberately.`);
   }
   const raw = defaultDeployFile(root, options);
   parseDeployDefinition(raw, { channel: options.channel });
-  mkdirSync(join(root, ".fz"), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(raw, null, 2)}
+  mkdirSync2(join2(root, ".fz"), { recursive: true });
+  writeFileSync2(path2, `${JSON.stringify(raw, null, 2)}
 `, { mode: 420 });
   return inspectDeployFile(root, { channel: options.channel });
 }

package/dist/deployment-runner.js

@@ -12,8 +12,21 @@ function within(root, candidate) {
   return candidate === root || candidate.startsWith(`${root}${sep}`);
 }
 function validate(root, input) {
-  if (!input || typeof input.command !== "string" || input.command.length < 1 || input.command.length > 64 * 1024) {
-    throw new Error("invalid deployment command");
+  if (!input || !Array.isArray(input.argv) || input.argv.length < 1 || input.argv.length > 256) {
+    throw new Error("invalid deployment argv");
+  }
+  let argvBytes = 0;
+  const argv = input.argv.map((argument) => {
+    if (typeof argument !== "string" || argument.length < 1 || argument.length > 16384 || argument.includes("\x00")) {
+      throw new Error("invalid deployment argument");
+    }
+    argvBytes += Buffer.byteLength(argument);
+    if (argvBytes > 64 * 1024)
+      throw new Error("deployment argv is too large");
+    return argument;
+  });
+  if (argv[0].includes("/../") || argv[0].endsWith("/..")) {
+    throw new Error("deployment executable path is invalid");
   }
   if (!input.cwd || !isAbsolute(input.cwd))
     throw new Error("deployment command needs an absolute working directory");
@@ -35,7 +48,7 @@ function validate(root, input) {
       throw new Error("deployment environment is too large");
     env[name] = value;
   }
-  return { command: input.command, cwd: realCwd, env, timeoutMs };
+  return { argv, cwd: realCwd, env, timeoutMs };
 }
 async function limited(stream) {
   const reader = stream.getReader();
@@ -57,7 +70,7 @@ async function limited(stream) {
 [output truncated at ${MAX_OUTPUT_BYTES} bytes]` : output;
 }
 async function execute(input, home) {
-  const child = Bun.spawn(["bash", "-Eeuo", "pipefail", "-c", input.command], {
+  const child = Bun.spawn([...input.argv], {
     cwd: input.cwd,
     detached: true,
     stdout: "pipe",
@@ -96,7 +109,7 @@ async function execute(input, home) {
   return {
     exitCode: timedOut ? 124 : exitCode,
     output: `${stdout}${stderr}${timedOut ? `
-command exceeded ${input.timeoutMs}ms` : ""}`
+process exceeded ${input.timeoutMs}ms` : ""}`
   };
 }
 function startDeploymentRunner(options) {

package/dist/deployment.d.ts

@@ -1,12 +1,14 @@
 import { type DrainReport, type QueueTask } from '@forgezero/runtime/queue';
 import { type GitHostResolver } from './git-egress';
 import type { SoftwareRequirement } from './software';
+import type { DeploymentService } from './definition';
+import type { ServiceActivationState } from './service-supervisor';
 import { type RunResult } from './pipeline';
 import type { SecretCache } from './cache';
 import type { AttestationSource } from './socket';
 import { type CapacityCalibration, type CapacityCalibrationOptions } from './capacity-calibration';
 export interface CommandInput {
-    command: string;
+    argv: readonly string[];
     cwd?: string;
     env?: Record<string, string>;
     timeoutMs?: number;
@@ -63,6 +65,8 @@ export interface DeploymentOptions {
     publicApiUrl?: string;
     sourceAuth?: GitSourceAuth;
     gitCredentialPath?: string;
+    /** Fixed typed SSH adapter installed beside fz-agent; Git invokes it directly. */
+    gitSshPath?: string;
     knownHostsPath?: string;
     /** Server-owned, operator-pinned host keys for a dynamically assigned source. */
     knownHostsContent?: string;
@@ -77,6 +81,14 @@ export interface DeploymentOptions {
     projectExec?: (input: CommandInput) => Promise<CommandResult>;
     /** Root-owned fixed strategy helper; repository data contains coordinates only. */
     ensureSoftware?: (requirements: readonly SoftwareRequirement[]) => Promise<unknown>;
+    /** Fixed root helper that owns systemd/nginx promotion; repository code never receives it. */
+    activateService?: (request: {
+        key: string;
+        revision: string;
+        release: string;
+        root: string;
+        service: DeploymentService;
+    }) => Promise<ServiceActivationState>;
     /** Agent-owned directory; definitions cannot choose or overwrite this path. */
     capacityEvidenceDirectory?: string;
     /** Test/embedding seam. Production runs the bounded loopback GET calibrator. */