@forgezero/agent 0.1.26 → 0.1.28

package/dist/provision.js

@@ -1,3 +1,561 @@
+// src/agent-update.ts
+import { createHash, timingSafeEqual, randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+var DEFAULT_AGENT_RELEASE_ROOT = "/opt/forgezero/agent";
+var DEFAULT_AGENT_UPDATE_SOCKET = "/run/forgezero-update/helper.sock";
+var MAX_AGENT_TARBALL_BYTES = 32 * 1024 * 1024;
+var VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+var REGISTRY = "registry.npmjs.org";
+function validateAgentRelease(release) {
+  if (release?.package !== "@forgezero/agent")
+    throw new Error("agent update package is fixed");
+  if (!VERSION.test(release.version))
+    throw new Error("agent update version must be exact semver");
+  const expectedTarball = `/@forgezero/agent/-/agent-${release.version}.tgz`;
+  let url;
+  try {
+    url = new URL(release.tarball);
+  } catch {
+    throw new Error("agent update tarball URL is malformed");
+  }
+  if (url.protocol !== "https:" || url.hostname !== REGISTRY || url.port || url.username || url.password || url.search || url.hash || url.pathname !== expectedTarball)
+    throw new Error("agent update tarball must be the exact official npm artifact");
+  const match = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(release.integrity);
+  if (!match || Buffer.from(match[1], "base64").length !== 64) {
+    throw new Error("agent update requires one sha512 npm integrity");
+  }
+  return release;
+}
+function compareVersions(left, right) {
+  if (!VERSION.test(left) || !VERSION.test(right))
+    throw new Error("agent version must be exact semver");
+  const a = left.split(".").map(Number);
+  const b = right.split(".").map(Number);
+  for (let index = 0;index < 3; index += 1) {
+    if (a[index] > b[index])
+      return 1;
+    if (a[index] < b[index])
+      return -1;
+  }
+  return 0;
+}
+var command = async (input) => {
+  const child = Bun.spawn([input.command, ...input.args], {
+    cwd: input.cwd,
+    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}` };
+};
+var checked = async (run, input, label) => {
+  const result = await run(input);
+  if (result.exitCode !== 0)
+    throw new Error(`${label} failed: ${result.output.trim()}`);
+  return result;
+};
+async function validateReleaseDirectory(directory, release, run) {
+  const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+  if (manifest.name !== release.package || manifest.version !== release.version) {
+    throw new Error("agent update manifest does not match the selected release");
+  }
+  const agent = join(directory, "dist", "fz-agent.js");
+  const cli = join(directory, "dist", "fz.js");
+  for (const binary of [agent, cli]) {
+    if (!readFileSync(binary, "utf8").startsWith(`#!/usr/bin/env bun
+`)) {
+      throw new Error("agent update artifact is not a self-contained Bun executable");
+    }
+    chmodSync(binary, 493);
+  }
+  const version = (await checked(run, { command: agent, args: ["--version"] }, "agent update smoke test")).output.trim();
+  if (version !== release.version)
+    throw new Error(`agent update binary reports ${version}`);
+}
+async function stageAgentRelease(releaseInput, options) {
+  const release = validateAgentRelease(releaseInput);
+  if (compareVersions(release.version, options.currentVersion) <= 0) {
+    throw new Error(`agent update ${release.version} is not newer than ${options.currentVersion}`);
+  }
+  const root = resolve(options.root ?? DEFAULT_AGENT_RELEASE_ROOT);
+  const versions = join(root, "versions");
+  const finalDirectory = join(versions, release.version);
+  const currentLink = join(root, "current");
+  const stage = join(versions, `.${release.version}.${randomUUID()}.staging`);
+  const archive = join(stage, "agent.tgz");
+  const unpacked = join(stage, "unpacked");
+  const run = options.run ?? command;
+  mkdirSync(unpacked, { recursive: true, mode: 448 });
+  try {
+    const response = await (options.fetch ?? globalThis.fetch)(release.tarball, {
+      redirect: "error",
+      signal: AbortSignal.timeout(30000)
+    });
+    if (!response.ok)
+      throw new Error(`npm returned HTTP ${response.status}`);
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (declared > MAX_AGENT_TARBALL_BYTES)
+      throw new Error("agent update tarball exceeds the size limit");
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length === 0 || bytes.length > MAX_AGENT_TARBALL_BYTES) {
+      throw new Error("agent update tarball is empty or exceeds the size limit");
+    }
+    const expected = Buffer.from(release.integrity.slice("sha512-".length), "base64");
+    const actual = createHash("sha512").update(bytes).digest();
+    if (!timingSafeEqual(actual, expected))
+      throw new Error("agent update integrity mismatch");
+    writeFileSync(archive, bytes, { mode: 384, flag: "wx" });
+    await checked(run, {
+      command: "/usr/bin/tar",
+      args: [
+        "-xzf",
+        archive,
+        "-C",
+        unpacked,
+        "--strip-components=1",
+        "package/package.json",
+        "package/dist/fz-agent.js",
+        "package/dist/fz.js"
+      ]
+    }, "agent update extraction");
+    await validateReleaseDirectory(unpacked, release, run);
+    if (!existsSync(finalDirectory))
+      renameSync(unpacked, finalDirectory);
+    else
+      await validateReleaseDirectory(finalDirectory, release, run);
+    if (!existsSync(currentLink)) {
+      throw new Error("agent update requires an active immutable release to roll back to");
+    }
+    const previousTarget = readlinkSync(currentLink);
+    return {
+      version: release.version,
+      directory: finalDirectory,
+      previousTarget,
+      nextTarget: join("versions", release.version),
+      currentLink
+    };
+  } finally {
+    rmSync(stage, { recursive: true, force: true });
+  }
+}
+function selectAgentRelease(staged) {
+  const next = join(dirname(staged.currentLink), `.current.${randomUUID()}.next`);
+  try {
+    symlinkSync(staged.nextTarget, next);
+    renameSync(next, staged.currentLink);
+  } finally {
+    rmSync(next, { force: true });
+  }
+}
+function restoreAgentRelease(staged) {
+  const next = join(dirname(staged.currentLink), `.current.${randomUUID()}.rollback`);
+  try {
+    symlinkSync(staged.previousTarget, next);
+    renameSync(next, staged.currentLink);
+  } finally {
+    rmSync(next, { force: true });
+  }
+}
+
+// src/agent-update-helper.ts
+import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, renameSync as renameSync2, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { connect, createServer } from "node:net";
+import { dirname as dirname2 } from "node:path";
+import { DEFAULT_SOCKET } from "@forgezero/vault";
+var AGENT_UPDATE_GROUP = "forgezero-update";
+var AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-helper.service";
+var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update.json";
+var MAX_REQUEST_BYTES = 8 * 1024;
+var COMPUTE_HELPER_UNITS = [
+  "forgezero-deploy-runner.service",
+  "forgezero-lifecycle-helper.service",
+  "forgezero-software-helper.service"
+];
+var runCommand = async (input) => {
+  const child = Bun.spawn([input.command, ...input.args], {
+    cwd: input.cwd,
+    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}` };
+};
+var runOk = async (run, command2, args) => (await run({ command: command2, args })).exitCode === 0;
+function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
+  return new Promise((resolve2) => {
+    const socket = connect(socketPath);
+    let settled = false;
+    let buffer = "";
+    const finish = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve2(value);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    socket.on("connect", () => socket.write(`{"op":"identity"}
+`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        finish(response.ok === false && response.error?.code === "APP_OPERATION_REFUSED");
+      } catch {
+        finish(false);
+      }
+    });
+    socket.on("error", () => finish(false));
+  });
+}
+async function activateAgentRelease(staged, options = {}) {
+  const run = options.run ?? runCommand;
+  const target = options.target ?? "compute";
+  const probe = options.probe ?? (target === "compute" ? () => probeAgentSocket() : async () => await runOk(run, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-agent.service"]) && await runOk(run, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-helper.service"]));
+  const restart = async () => {
+    const helpers = target === "compute" ? COMPUTE_HELPER_UNITS : ["forgezero-metal-helper.service"];
+    for (const unit of helpers) {
+      await run({ command: "/usr/bin/systemctl", args: ["try-restart", unit] });
+    }
+    const service = target === "compute" ? "forgezero-agent.service" : "forgezero-metal-agent.service";
+    const restarted = await runOk(run, "/usr/bin/systemctl", ["restart", service]);
+    if (!restarted)
+      throw new Error(`systemd could not restart ${service}`);
+  };
+  let selected = false;
+  try {
+    selectAgentRelease(staged);
+    selected = true;
+    await restart();
+    if (!await probe())
+      throw new Error("the replacement Agent did not answer its retained Vault socket");
+    const receipt = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
+    mkdirSync2(dirname2(receipt), { recursive: true, mode: 493 });
+    const next = `${receipt}.next`;
+    writeFileSync2(next, JSON.stringify({
+      version: staged.version,
+      outcome: "active",
+      updatedAtTs: (options.now ?? Date.now)()
+    }) + `
+`, { mode: 420 });
+    renameSync2(next, receipt);
+    run({
+      command: "/usr/bin/systemctl",
+      args: ["try-restart", "--no-block", "forgezero-agent-update-helper.service"]
+    });
+    return { ok: true, version: staged.version };
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    if (selected) {
+      restoreAgentRelease(staged);
+      await restart();
+    }
+    return { ok: false, rolledBack: selected, reason };
+  }
+}
+function startAgentUpdateHelper(options = {}) {
+  const socketPath = options.socketPath ?? DEFAULT_AGENT_UPDATE_SOCKET;
+  if (existsSync2(socketPath))
+    unlinkSync(socketPath);
+  mkdirSync2(dirname2(socketPath), { recursive: true, mode: 488 });
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const activate = options.activate ?? ((staged, target) => activateAgentRelease(staged, { target }));
+  const server = createServer((socket) => {
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES) {
+        socket.end(`${JSON.stringify({ ok: false, error: { code: "TOO_LARGE", message: "update request too large" } })}
+`);
+        return;
+      }
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      Promise.resolve().then(() => JSON.parse(line)).then(async (request) => {
+        if (request.op !== "apply")
+          throw new Error("unknown update operation");
+        if (request.target !== "compute" && request.target !== "metal") {
+          throw new Error("agent update target is invalid");
+        }
+        const staged = await stageAgentRelease(request.release, {
+          currentVersion: request.currentVersion,
+          root: options.root ?? DEFAULT_AGENT_RELEASE_ROOT
+        });
+        const response = { ok: true, status: "staged", version: staged.version };
+        socket.end(`${JSON.stringify(response)}
+`, () => {
+          setTimer(() => void activate(staged, request.target), 100);
+        });
+      }).catch((cause) => {
+        const response = {
+          ok: false,
+          error: { code: "UPDATE_REFUSED", message: cause instanceof Error ? cause.message : String(cause) }
+        };
+        socket.end(`${JSON.stringify(response)}
+`);
+      });
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(socketPath, () => chmodSync2(socketPath, 432));
+  return server;
+}
+function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, timeoutMs = 90000) {
+  return new Promise((resolve2, reject) => {
+    const socket = connect(socketPath, () => socket.write(`${JSON.stringify(request)}
+`));
+    let buffer = "";
+    socket.setTimeout(timeoutMs, () => {
+      socket.destroy();
+      reject(new Error("agent update helper did not answer before its deadline"));
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.end();
+      try {
+        resolve2(JSON.parse(buffer.slice(0, newline)));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+
+// src/software.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
+var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
+var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+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'`,
+    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`
+  },
+  {
+    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"
+  }
+];
+function observeSoftwareHost(osRelease = readFileSync2("/etc/os-release", "utf8"), architecture = process.arch) {
+  const values = Object.fromEntries(osRelease.split(`
+`).flatMap((line) => {
+    const separator = line.indexOf("=");
+    return separator > 0 ? [[line.slice(0, separator), line.slice(separator + 1).replace(/^['"]|['"]$/g, "")]] : [];
+  }));
+  return {
+    os: { id: (values.ID ?? "unknown").toLowerCase(), versionId: values.VERSION_ID ?? "unknown" },
+    architecture
+  };
+}
+function validateSoftwareRequirements(value) {
+  if (!Array.isArray(value) || value.length > 32)
+    throw new Error("software requirements must be an array of at most 32 entries");
+  const seen = new Set;
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      throw new Error("software requirement must be an object");
+    const row = item;
+    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"].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 };
+    if (seen.has(requirement.id))
+      throw new Error(`duplicate software requirement: ${requirement.id}`);
+    seen.add(requirement.id);
+    return requirement;
+  });
+}
+async function ensureSoftwareRequirements(requirementsInput, options) {
+  const requirements = validateSoftwareRequirements(requirementsInput);
+  const observation = options.observation ?? observeSoftwareHost();
+  if (observation.os.id !== "ubuntu" || observation.os.versionId !== "26.04" || observation.architecture !== "x64") {
+    throw new Error(`unsupported software strategy: ${observation.os.id} ${observation.os.versionId} ${observation.architecture}`);
+  }
+  const results = [];
+  for (const requirement of requirements) {
+    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);
+    if (before.exitCode === 0) {
+      results.push({ ...requirement, changed: false });
+      continue;
+    }
+    const installed = await options.exec(strategy.install);
+    if (installed.exitCode !== 0)
+      throw new Error(`could not install ${requirement.id}@${requirement.version}: ${installed.output.trim()}`);
+    const after = await options.exec(strategy.check);
+    if (after.exitCode !== 0)
+      throw new Error(`${requirement.id}@${requirement.version} did not pass its post-install check`);
+    results.push({ ...requirement, changed: true });
+  }
+  return results;
+}
+
+// src/software-helper.ts
+import { chmodSync as chmodSync3, existsSync as existsSync3, mkdirSync as mkdirSync3, unlinkSync as unlinkSync2 } from "node:fs";
+import { connect as connect2, createServer as createServer2 } from "node:net";
+import { dirname as dirname3 } from "node:path";
+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_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 });
+  const ensure = options.ensure ?? ensureSoftwareRequirements;
+  let tail = Promise.resolve();
+  let pending = 0;
+  const server = createServer2((socket) => {
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES2)
+        return socket.destroy();
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      if (pending >= MAX_PENDING_REQUESTS) {
+        socket.end(`${JSON.stringify({
+          ok: false,
+          error: { code: "SOFTWARE_BUSY", message: "software helper queue is full" }
+        })}
+`);
+        return;
+      }
+      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 })}
+`);
+      }).catch((cause) => socket.end(`${JSON.stringify({
+        ok: false,
+        error: { code: "SOFTWARE_REFUSED", message: cause instanceof Error ? cause.message : String(cause) }
+      })}
+`)).finally(() => {
+        pending -= 1;
+      }));
+      tail = work.then(() => {
+        return;
+      }, () => {
+        return;
+      });
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(socketPath, () => chmodSync3(socketPath, 432));
+  return server;
+}
+function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
+  validateSoftwareRequirements(requirements);
+  return new Promise((resolve2, reject) => {
+    const socket = connect2(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
+`));
+    let buffer = "";
+    socket.setTimeout(timeoutMs, () => {
+      socket.destroy();
+      reject(new Error("software helper did not answer before its deadline"));
+    });
+    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.results)
+          throw new Error(response.error?.message ?? "software helper refused the request");
+        resolve2(response.results);
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+
+// src/version.ts
+var VERSION2 = "0.1.28";
+
 // src/provision.ts
 function atLeast(version, floor) {
   const parse = (value) => (value.trim().replace(/^v/, "").match(/\d+/g) ?? []).slice(0, 3).map(Number);
@@ -44,12 +602,102 @@ var DEPLOYMENT_GROUP = "forgezero-deploy";
 var VAULT_GROUP = "forgezero-vault";
 var LIFECYCLE_GROUP = "forgezero-lifecycle";
 var DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
+var AGENT_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-agent.socket";
 var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
 var ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
 var LIFECYCLE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-lifecycle-helper.service";
 var LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
 var WARP_CONFIG_UNIT_PATH = "/etc/systemd/system/forgezero-warp-config.service";
 var WARP_SERVICE_DROP_IN_PATH = "/etc/systemd/system/warp-svc.service.d/forgezero.conf";
+function softwareHelperUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  return `[Unit]
+Description=ForgeZero declarative software strategy helper
+Documentation=https://www.forgezero.net/docs/agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=root
+Group=${SOFTWARE_HELPER_GROUP}
+Environment=FZ_SOFTWARE_HELPER_SOCKET=${DEFAULT_SOFTWARE_HELPER_SOCKET}
+ExecStart=${bin} software-helper
+Restart=always
+RestartSec=2
+RuntimeDirectory=forgezero-software
+RuntimeDirectoryMode=0750
+UMask=0007
+LimitCORE=0
+PrivateTmp=true
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictRealtime=true
+LockPersonality=true
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function agentUpdateHelperUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  return `[Unit]
+Description=ForgeZero verified Agent update helper
+Documentation=https://www.forgezero.net/docs/agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=root
+Group=${AGENT_UPDATE_GROUP}
+Environment=FZ_AGENT_UPDATE_SOCKET=${DEFAULT_AGENT_UPDATE_SOCKET}
+ExecStart=${bin} update-helper
+Restart=always
+RestartSec=2
+RuntimeDirectory=forgezero-update
+RuntimeDirectoryMode=0750
+UMask=0007
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+LockPersonality=true
+ReadWritePaths=${DEFAULT_AGENT_RELEASE_ROOT} /var/lib/forgezero
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function agentSocketUnit(options) {
+  const socket = systemdPath(options.socketPath, "agent socket");
+  return `[Unit]
+Description=ForgeZero application Vault socket
+Documentation=https://www.forgezero.net/docs/agent
+
+[Socket]
+ListenStream=${socket}
+SocketUser=root
+SocketGroup=${VAULT_GROUP}
+SocketMode=0660
+DirectoryMode=0750
+RemoveOnStop=true
+Service=forgezero-agent.service
+
+[Install]
+WantedBy=sockets.target
+`;
+}
 var systemdPath = (value, label) => {
   if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
     throw new Error(`invalid ${label} path`);
@@ -310,12 +958,14 @@ function agentUnit(options) {
     options.repository && options.branch ? `FZ_DEPLOY_KEY=${options.project ?? "platform"}:${options.environment ?? "production"}` : null,
     deploymentEnabled ? `FZ_DEPLOY_ROOT=${deployRoot}` : null,
     deploymentEnabled ? `FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}` : null,
+    deploymentEnabled ? `FZ_SOFTWARE_HELPER_SOCKET=${DEFAULT_SOFTWARE_HELPER_SOCKET}` : null,
     Object.keys(deploymentCredentials).length > 0 ? `FZ_DEPLOY_SYSTEMD_SECRETS=${Object.keys(deploymentCredentials).join(",")}` : null,
     Object.keys(deploymentEnvironment).length > 0 ? `FZ_DEPLOY_ENV_NAMES=${Object.keys(deploymentEnvironment).join(",")}` : null,
     ...Object.entries(deploymentEnvironment).map(([name, value]) => `${name}=${value}`),
     options.publicApiUrl ? `FZ_PUBLIC_API_URL=${options.publicApiUrl}` : null,
     options.pullDeployments ? "FZ_DEPLOY_PULL=true" : null,
     options.pullMigrations ? "FZ_MIGRATION_PULL=true" : null,
+    `FZ_AGENT_UPDATE_SOCKET=${DEFAULT_AGENT_UPDATE_SOCKET}`,
     options.pullMigrations ? `FZ_LIFECYCLE_HELPER_SOCKET=${lifecycleHelperSocketPath}` : null
   ].filter((line) => line !== null);
   if (deploymentEnabled) {
@@ -327,19 +977,25 @@ function agentUnit(options) {
 `);
   const deploymentWrites = deploymentEnabled ? `ReadWritePaths=${deployRoot}/releases ${deployRoot}/agent-home ${deployRoot}/cache` : "";
   const supplementaryGroups = [
+    AGENT_UPDATE_GROUP,
     deploymentEnabled ? DEPLOYMENT_GROUP : null,
+    deploymentEnabled ? SOFTWARE_HELPER_GROUP : null,
     lifecycleEnabled ? LIFECYCLE_GROUP : null
   ].filter((value) => value !== null);
   const deploymentGroup = supplementaryGroups.length > 0 ? `SupplementaryGroups=${supplementaryGroups.join(" ")}` : "";
   const after = [
     "network-online.target",
+    "forgezero-agent-update-helper.service",
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
+    deploymentEnabled ? "forgezero-software-helper.service" : null,
     lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
     warpEnabled ? "warp-svc.service" : null,
     enrolmentEnabled ? "forgezero-agent-enrol.service" : null
   ].filter((value) => value !== null);
   const requires = [
+    "forgezero-agent-update-helper.service",
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
+    deploymentEnabled ? "forgezero-software-helper.service" : null,
     lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
     warpEnabled ? "warp-svc.service" : null,
     enrolmentEnabled ? "forgezero-agent-enrol.service" : null
@@ -365,6 +1021,7 @@ Type=simple
 User=${user}
 Group=${VAULT_GROUP}
 ${deploymentGroup}
+Sockets=forgezero-agent.socket
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
 ${gitCredential}${projectCredentials}${projectCredentials ? `
 ` : ""}${snpPrepare}ExecStart=${bin}
@@ -383,6 +1040,7 @@ LimitCORE=0
 # than wherever the process happened to have write access.
 RuntimeDirectory=forgezero
 RuntimeDirectoryMode=0750
+RuntimeDirectoryPreserve=yes
 UMask=0007
 
 # Tenant-controlled commands execute in forgezero-deploy-runner.service. This
@@ -450,8 +1108,11 @@ function planProvision(options) {
     unitPath: UNIT_PATH,
     unit: agentUnit({ ...options, mode, lifecycleProfilePath, lifecycleHelperSocketPath }),
     auxiliaryUnits: [
+      { path: AGENT_SOCKET_UNIT_PATH, unit: agentSocketUnit(options) },
+      { path: AGENT_UPDATE_HELPER_UNIT_PATH, unit: agentUpdateHelperUnit(options) },
       ...deploymentEnabled ? [
-        { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) }
+        { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) },
+        { path: SOFTWARE_HELPER_UNIT_PATH, unit: softwareHelperUnit(options) }
       ] : [],
       ...enrolmentEnabled ? [
         { path: ENROLMENT_UNIT_PATH, unit: agentEnrolmentUnit(options) }
@@ -479,9 +1140,13 @@ function planProvision(options) {
         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(/\/[^/]+$/, "")}; ` + `install -o root -g root -m 0755 ${sourceBinPath} ${binPath}`
+        command: `install -d -o root -g root -m 0755 ${binPath.replace(/\/[^/]+$/, "")} ` + `${DEFAULT_AGENT_RELEASE_ROOT}/versions/${VERSION2}/dist; ` + `install -o root -g root -m 0755 ${sourceBinPath} ` + `${DEFAULT_AGENT_RELEASE_ROOT}/versions/${VERSION2}/dist/fz-agent.js; ` + `ln -sfn versions/${VERSION2} ${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",
@@ -489,7 +1154,7 @@ function planProvision(options) {
       }] : [],
       ...deploymentEnabled ? [{
         label: "deployment isolation group",
-        command: `groupadd --system ${DEPLOYMENT_GROUP} || true`
+        command: `groupadd --system ${DEPLOYMENT_GROUP} || true; groupadd --system ${SOFTWARE_HELPER_GROUP} || true`
       }] : [],
       ...lifecycleEnabled ? [{
         label: "lifecycle helper access group",
@@ -503,13 +1168,17 @@ function planProvision(options) {
         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} ${user}`
+        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",
@@ -551,7 +1220,9 @@ function planProvision(options) {
       {
         label: "enable and start",
         command: `systemctl enable --now ${[
-          ...deploymentEnabled ? ["forgezero-deploy-runner.service"] : [],
+          "forgezero-agent.socket",
+          "forgezero-agent-update-helper.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"] : [],
@@ -564,9 +1235,13 @@ function planProvision(options) {
       }] : [],
       { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
       { label: "prove the vault socket exists", command: `test -S ${options.socketPath}` },
+      { label: "prove the Agent update helper exists", command: `test -S ${DEFAULT_AGENT_UPDATE_SOCKET}` },
       ...deploymentEnabled ? [{
         label: "prove the deployment runner socket exists",
         command: `test -S ${DEPLOYMENT_RUNNER_SOCKET}`
+      }, {
+        label: "prove the software strategy helper socket exists",
+        command: `test -S ${DEFAULT_SOFTWARE_HELPER_SOCKET}`
       }] : [],
       ...lifecycleEnabled ? [{
         label: "prove the lifecycle helper socket exists",
@@ -586,13 +1261,16 @@ function planProvision(options) {
 export {
   warpServiceDropIn,
   warpConfigUnit,
+  softwareHelperUnit,
   reasonFor,
   planProvision,
   modeFor,
   lifecycleHelperUnit,
   deploymentRunnerUnit,
   atLeast,
+  agentUpdateHelperUnit,
   agentUnit,
+  agentSocketUnit,
   agentEnrolmentUnit,
   WARP_SERVICE_DROP_IN_PATH,
   WARP_CONFIG_UNIT_PATH,
@@ -606,5 +1284,6 @@ export {
   DEPLOYMENT_RUNNER_UNIT_PATH,
   DEPLOYMENT_RUNNER_SOCKET,
   DEPLOYMENT_GROUP,
-  CAPABILITY_CHECKS
+  CAPABILITY_CHECKS,
+  AGENT_SOCKET_UNIT_PATH
 };