@forgezero/agent 0.1.41 → 0.1.43

package/dist/software-helper.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 });
@@ -111,34 +236,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 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");
+  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, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync as mkdirSync3, unlinkSync as unlinkSync2 } from "node:fs";
 import { connect, createServer } from "node:net";
-import { dirname } from "node:path";
+import { dirname as dirname2 } from "node:path";
+
+// src/service-supervisor.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, realpathSync, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname, join as join2, resolve, 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) => createHash2("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) {
+    mkdirSync2(dirname(path2), { recursive: true, mode: 493 });
+    const next = `${path2}.next`;
+    writeFileSync2(next, content, { mode });
+    renameSync2(next, path2);
+  },
+  read: (path2) => readFileSync2(path2, "utf8"),
+  exists: existsSync,
+  list: (path2) => existsSync(path2) ? readdirSync(path2) : [],
+  realpath: realpathSync,
+  mkdir: (path2, mode) => mkdirSync2(path2, { recursive: true, mode }),
+  remove: (path2) => rmSync2(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, join2(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(createHash2("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 checked(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(resolve(request.root));
+  const release = host.realpath(resolve(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 checked(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 checked(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 checked(host, ["/usr/sbin/nginx", "-t"], "SERVICE_NGINX_INVALID");
+    await checked(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_BYTES = 8 * 1024;
+var MAX_REQUEST_BYTES = 128 * 1024;
 var MAX_PENDING_REQUESTS = 128;
-var execute = async (command) => {
-  const child = Bun.spawn(["/bin/bash", "-Eeuo", "pipefail", "-c", command], {
-    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 (existsSync(socketPath))
-    unlinkSync(socketPath);
-  mkdirSync(dirname(socketPath), { recursive: true, mode: 488 });
+  if (existsSync2(socketPath))
+    unlinkSync2(socketPath);
+  mkdirSync3(dirname2(socketPath), { recursive: true, mode: 488 });
   const ensure = options.ensure ?? ensureSoftwareRequirements;
+  const activate = options.activate ?? activateSupervisedService;
   let tail = Promise.resolve();
   let pending = 0;
   const server = createServer((socket) => {
@@ -163,12 +925,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) }
@@ -184,12 +957,40 @@ function startSoftwareHelper(options = {}) {
     });
     socket.on("error", () => socket.destroy());
   });
-  server.listen(socketPath, () => chmodSync(socketPath, 432));
+  server.listen(socketPath, () => chmodSync2(socketPath, 432));
   return server;
 }
+function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 10 * 60000) {
+  return new Promise((resolve2, reject) => {
+    const socket = connect(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");
+        resolve2(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((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const socket = connect(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
 `));
     let buffer = "";
@@ -208,7 +1009,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");
-        resolve(response.results);
+        resolve2(response.results);
       } catch (cause) {
         reject(cause);
       }
@@ -219,6 +1020,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 export {
   startSoftwareHelper,
   requestSoftware,
+  requestServiceActivation,
   SOFTWARE_HELPER_UNIT_PATH,
   SOFTWARE_HELPER_GROUP,
   DEFAULT_SOFTWARE_HELPER_SOCKET