@forgezero/agent 0.1.50 → 0.1.52

package/dist/agent-heartbeat.js

@@ -749,7 +749,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.50";
+var VERSION3 = "0.1.52";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");

package/dist/bootstrap.js

@@ -1207,7 +1207,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.50";
+var VERSION = "0.1.52";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";

package/dist/community-rehearsal-host.d.ts

@@ -1,3 +1,4 @@
+import { type SoftwareExec } from './software';
 export declare const COMMUNITY_REHEARSAL_VERSION = "3.11.14";
 export declare const COMMUNITY_REHEARSAL_ROOT = "/opt/forgezero-rehearsals/community-cluster-api";
 export declare const COMMUNITY_DATABASE_ROOT = "/var/lib/forgezero-rehearsal-cluster";
@@ -43,6 +44,7 @@ export type CommunityHostOperation = {
     stdin?: string;
     accepted?: readonly number[];
 };
+export declare function ensureCommunityRehearsalArango(execute?: SoftwareExec): Promise<void>;
 export declare function parseCommunityRehearsalHostRequest(value: unknown): CommunityRehearsalHostRequest;
 export declare function planCommunityRehearsalPrepare(request: Extract<CommunityRehearsalHostRequest, {
     action: 'prepare';

package/dist/community-rehearsal-host.js

@@ -1,6 +1,254 @@
-// src/community-rehearsal-host.ts
+// src/software.ts
 import { createHash } from "node:crypto";
-import { lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+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_RELEASE_SHA256 = "951ee2aee855f08595aeec6225226a298d3fea83a3dcd6465c09cbccdf7e848f";
+var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
+var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+var OS_CATALOG = [
+  { id: "ubuntu", version: "26.04", architecture: "x64", status: "active" }
+];
+var SOFTWARE_CATALOG = [
+  { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { 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" } },
+  { 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 softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
+var runSoftwareCommand = async (argv, env = {}) => {
+  let child;
+  try {
+    child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  } catch (cause) {
+    const failure = softwareSpawnFailure(cause, argv);
+    if (failure)
+      return failure;
+    throw cause;
+  }
+  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 run = runSoftwareCommand;
+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) => {
+    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, _options = {}) {
+  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", "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 };
+    if (seen.has(requirement.id))
+      throw new Error(`duplicate software requirement: ${requirement.id}`);
+    seen.add(requirement.id);
+    const catalog = SOFTWARE_CATALOG.find((candidate) => candidate.id === requirement.id && candidate.version === requirement.version);
+    if (!catalog || catalog.status !== "active") {
+      throw new Error(`software requirement is not active: ${requirement.id}@${requirement.version}`);
+    }
+    return requirement;
+  });
+}
+async function ensureSoftwareRequirements(requirementsInput, options) {
+  const requirements = validateSoftwareRequirements(requirementsInput);
+  const observation = options.observation ?? observeSoftwareHost();
+  const os = OS_CATALOG.find((candidate) => candidate.id === observation.os.id && candidate.version === observation.os.versionId && candidate.architecture === observation.architecture);
+  if (!os || os.status !== "active") {
+    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({ kind: "check", software: requirement.id, version: requirement.version });
+    if (before.exitCode === 0) {
+      results.push({ ...requirement, changed: false });
+      continue;
+    }
+    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({ 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 });
+  }
+  return results;
+}
+
+// src/community-rehearsal-host.ts
+import { createHash as createHash2 } from "node:crypto";
+import { lstatSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, symlinkSync as symlinkSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname } from "node:path";
 var COMMUNITY_REHEARSAL_VERSION = "3.11.14";
 var COMMUNITY_REHEARSAL_ROOT = "/opt/forgezero-rehearsals/community-cluster-api";
@@ -13,6 +261,15 @@ var NODES = new Map([
   ["dev-fz-n4", { address: "10.42.0.24", agency: false }]
 ]);
 var RELEASE = /^[a-f0-9]{64}$/;
+async function ensureCommunityRehearsalArango(execute = executeSoftwareOperation) {
+  const requirement = { software: "arangodb", version: COMMUNITY_REHEARSAL_VERSION };
+  if ((await execute({ kind: "check", ...requirement })).exitCode === 0)
+    return;
+  const installed = await execute({ kind: "install", ...requirement });
+  if (installed.exitCode !== 0 || (await execute({ kind: "check", ...requirement })).exitCode !== 0) {
+    throw new Error(`unable to install and verify ArangoDB ${COMMUNITY_REHEARSAL_VERSION}`);
+  }
+}
 var exactObject = (value) => {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error("community rehearsal request must be an object");
@@ -55,7 +312,7 @@ function parseCommunityRehearsalHostRequest(value) {
   throw new Error("unsupported community rehearsal host action");
 }
 var databaseUnit = (node) => {
-  const join = node.name === "dev-fz-n1" ? "" : " --starter.join=10.42.0.21";
+  const join2 = node.name === "dev-fz-n1" ? "" : " --starter.join=10.42.0.21";
   const role = node.agency ? "" : " --cluster.start-agent=false --cluster.start-coordinator=true --cluster.start-dbserver=true";
   return `[Unit]
 Description=ForgeZero isolated Community ${COMMUNITY_REHEARSAL_VERSION} rehearsal cluster
@@ -67,7 +324,7 @@ Type=simple
 User=arangodb
 Group=arangodb
 LoadCredentialEncrypted=arangodb-jwt:${COMMUNITY_CREDENTIAL_ROOT}/arangodb-jwt.cred
-ExecStart=/usr/bin/arangodb --starter.mode=cluster --starter.address=${node.address} --starter.host=${node.address} --starter.data-dir=${COMMUNITY_DATABASE_ROOT} --starter.disable-ipv6 --auth.jwt-secret=%d/arangodb-jwt${join}${role}
+ExecStart=/usr/bin/arangodb --starter.mode=cluster --starter.address=${node.address} --starter.host=${node.address} --starter.data-dir=${COMMUNITY_DATABASE_ROOT} --starter.disable-ipv6 --auth.jwt-secret=%d/arangodb-jwt${join2}${role}
 Restart=always
 RestartSec=5
 LimitNOFILE=100000
@@ -168,19 +425,19 @@ async function exec(argv, stdin) {
 async function applyOperations(operations) {
   for (const operation of operations) {
     if (operation.kind === "remove-tree")
-      rmSync(operation.path, { recursive: true, force: true });
+      rmSync2(operation.path, { recursive: true, force: true });
     else if (operation.kind === "write") {
-      mkdirSync(dirname(operation.path), { recursive: true });
-      writeFileSync(operation.path, operation.content, { mode: operation.mode });
+      mkdirSync2(dirname(operation.path), { recursive: true });
+      writeFileSync2(operation.path, operation.content, { mode: operation.mode });
     } else if (operation.kind === "unlink") {
       try {
-        unlinkSync(operation.path);
+        unlinkSync2(operation.path);
       } catch (cause) {
         if (cause.code !== "ENOENT")
           throw cause;
       }
     } else if (operation.kind === "symlink")
-      symlinkSync(operation.target, operation.path);
+      symlinkSync2(operation.target, operation.path);
     else {
       const result = await exec(operation.argv, operation.stdin);
       if (!(operation.accepted ?? [0]).includes(result.exitCode))
@@ -216,9 +473,10 @@ async function runCommunityRehearsalHost(request) {
   const node = exactNode(request.node);
   if (request.action === "prepare") {
     const metadata = lstatSync(request.archivePath);
-    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size < 1 || metadata.size > 64 * 1024 * 1024 || createHash("sha256").update(readFileSync(request.archivePath)).digest("hex") !== request.archiveSha256) {
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size < 1 || metadata.size > 64 * 1024 * 1024 || createHash2("sha256").update(readFileSync2(request.archivePath)).digest("hex") !== request.archiveSha256) {
       throw new Error("community rehearsal archive is not the declared bounded release");
     }
+    await ensureCommunityRehearsalArango();
     await applyOperations(planCommunityRehearsalPrepare(request));
     return { ok: true, action: request.action, node: node.name, release: request.release };
   }
@@ -265,6 +523,7 @@ export {
   runCommunityRehearsalHost,
   planCommunityRehearsalPrepare,
   parseCommunityRehearsalHostRequest,
+  ensureCommunityRehearsalArango,
   COMMUNITY_REHEARSAL_VERSION,
   COMMUNITY_REHEARSAL_ROOT,
   COMMUNITY_DATABASE_ROOT,

package/dist/definition.js

@@ -41,8 +41,17 @@ var UBUNTU_2604_X64 = [
   { 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 } });
+var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
+var runSoftwareCommand = async (argv, env = {}) => {
+  let child;
+  try {
+    child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  } catch (cause) {
+    const failure = softwareSpawnFailure(cause, argv);
+    if (failure)
+      return failure;
+    throw cause;
+  }
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
@@ -50,6 +59,7 @@ var run = async (argv, env = {}) => {
   ]);
   return { exitCode, output: `${stdout}${stderr}` };
 };
+var run = runSoftwareCommand;
 var download = async (url, destination, sha256) => {
   const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
   if (!response.ok)

package/dist/deploy-file.js

@@ -41,8 +41,17 @@ var UBUNTU_2604_X64 = [
   { 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 } });
+var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
+var runSoftwareCommand = async (argv, env = {}) => {
+  let child;
+  try {
+    child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  } catch (cause) {
+    const failure = softwareSpawnFailure(cause, argv);
+    if (failure)
+      return failure;
+    throw cause;
+  }
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
@@ -50,6 +59,7 @@ var run = async (argv, env = {}) => {
   ]);
   return { exitCode, output: `${stdout}${stderr}` };
 };
+var run = runSoftwareCommand;
 var download = async (url, destination, sha256) => {
   const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
   if (!response.ok)

package/dist/fz-agent.js

@@ -4990,8 +4990,17 @@ var UBUNTU_2604_X64 = [
   { 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 } });
+var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
+var runSoftwareCommand = async (argv, env = {}) => {
+  let child;
+  try {
+    child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  } catch (cause) {
+    const failure = softwareSpawnFailure(cause, argv);
+    if (failure)
+      return failure;
+    throw cause;
+  }
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
@@ -4999,6 +5008,7 @@ var run = async (argv, env = {}) => {
   ]);
   return { exitCode, output: `${stdout}${stderr}` };
 };
+var run = runSoftwareCommand;
 var download = async (url, destination, sha2562) => {
   const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
   if (!response.ok)
@@ -7000,7 +7010,7 @@ function assertSupportedGuestImage(imageKey) {
 }
 
 // src/version.ts
-var VERSION = "0.1.50";
+var VERSION = "0.1.52";
 
 // src/ssh-bootstrap.ts
 class SshBootstrapError extends Error {
@@ -13216,6 +13226,15 @@ var NODES = new Map([
   ["dev-fz-n4", { address: "10.42.0.24", agency: false }]
 ]);
 var RELEASE = /^[a-f0-9]{64}$/;
+async function ensureCommunityRehearsalArango(execute3 = executeSoftwareOperation) {
+  const requirement = { software: "arangodb", version: COMMUNITY_REHEARSAL_VERSION };
+  if ((await execute3({ kind: "check", ...requirement })).exitCode === 0)
+    return;
+  const installed = await execute3({ kind: "install", ...requirement });
+  if (installed.exitCode !== 0 || (await execute3({ kind: "check", ...requirement })).exitCode !== 0) {
+    throw new Error(`unable to install and verify ArangoDB ${COMMUNITY_REHEARSAL_VERSION}`);
+  }
+}
 var exactObject = (value) => {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error("community rehearsal request must be an object");
@@ -13422,6 +13441,7 @@ async function runCommunityRehearsalHost(request) {
     if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size < 1 || metadata.size > 64 * 1024 * 1024 || createHash8("sha256").update(readFileSync16(request.archivePath)).digest("hex") !== request.archiveSha256) {
       throw new Error("community rehearsal archive is not the declared bounded release");
     }
+    await ensureCommunityRehearsalArango();
     await applyOperations(planCommunityRehearsalPrepare(request));
     return { ok: true, action: request.action, node: node.name, release: request.release };
   }

package/dist/fz.js

@@ -4830,7 +4830,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION2 = "0.1.50";
+var VERSION2 = "0.1.52";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";

package/dist/metal-bootstrap.js

@@ -292,7 +292,7 @@ function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
 }
 
 // src/version.ts
-var VERSION = "0.1.50";
+var VERSION = "0.1.52";
 
 // src/otel-collector.ts
 var FORGEZERO_OTEL_COLLECTOR_UNIT = "forgezero-otel-collector.service";

package/dist/operator-bootstrap.js

@@ -1207,7 +1207,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.50";
+var VERSION = "0.1.52";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";

package/dist/platform-fleet-verification.js

@@ -719,8 +719,17 @@ var UBUNTU_2604_X64 = [
   { 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 } });
+var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
+var runSoftwareCommand = async (argv, env = {}) => {
+  let child;
+  try {
+    child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  } catch (cause) {
+    const failure = softwareSpawnFailure(cause, argv);
+    if (failure)
+      return failure;
+    throw cause;
+  }
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
@@ -728,6 +737,7 @@ var run = async (argv, env = {}) => {
   ]);
   return { exitCode, output: `${stdout}${stderr}` };
 };
+var run = runSoftwareCommand;
 var download = async (url, destination, sha256) => {
   const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
   if (!response.ok)
@@ -1697,7 +1707,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.50";
+var VERSION3 = "0.1.52";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync2 } from "node:fs";

package/dist/provision.js

@@ -719,8 +719,17 @@ var UBUNTU_2604_X64 = [
   { 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 } });
+var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
+var runSoftwareCommand = async (argv, env = {}) => {
+  let child;
+  try {
+    child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  } catch (cause) {
+    const failure = softwareSpawnFailure(cause, argv);
+    if (failure)
+      return failure;
+    throw cause;
+  }
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
@@ -728,6 +737,7 @@ var run = async (argv, env = {}) => {
   ]);
   return { exitCode, output: `${stdout}${stderr}` };
 };
+var run = runSoftwareCommand;
 var download = async (url, destination, sha256) => {
   const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
   if (!response.ok)
@@ -1697,7 +1707,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.50";
+var VERSION3 = "0.1.52";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync2 } from "node:fs";

package/dist/software-helper.js

@@ -41,8 +41,17 @@ var UBUNTU_2604_X64 = [
   { 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 } });
+var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
+var runSoftwareCommand = async (argv, env = {}) => {
+  let child;
+  try {
+    child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  } catch (cause) {
+    const failure = softwareSpawnFailure(cause, argv);
+    if (failure)
+      return failure;
+    throw cause;
+  }
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
@@ -50,6 +59,7 @@ var run = async (argv, env = {}) => {
   ]);
   return { exitCode, output: `${stdout}${stderr}` };
 };
+var run = runSoftwareCommand;
 var download = async (url, destination, sha256) => {
   const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
   if (!response.ok)

package/dist/software.d.ts

@@ -46,6 +46,8 @@ export declare const BUN_RELEASE_SHA256 = "951ee2aee855f08595aeec6225226a298d3fe
 /** Public, command-free catalog. Root strategies remain private below. */
 export declare const OS_CATALOG: readonly OsCatalogEntry[];
 export declare const SOFTWARE_CATALOG: readonly SoftwareCatalogEntry[];
+export declare const softwareSpawnFailure: (cause: unknown, argv: readonly string[]) => SoftwareCommandResult | undefined;
+export declare const runSoftwareCommand: (argv: readonly string[], env?: Record<string, string>) => Promise<SoftwareCommandResult>;
 /** Closed, fixed-argv privileged strategy executor. No repository value becomes a command. */
 export declare function executeSoftwareOperation(operation: SoftwareOperation): Promise<SoftwareCommandResult>;
 export declare function observeSoftwareHost(osRelease?: string, architecture?: NodeJS.Architecture): SoftwareObservation;

package/dist/software.js

@@ -41,8 +41,17 @@ var UBUNTU_2604_X64 = [
   { 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 } });
+var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
+var runSoftwareCommand = async (argv, env = {}) => {
+  let child;
+  try {
+    child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  } catch (cause) {
+    const failure = softwareSpawnFailure(cause, argv);
+    if (failure)
+      return failure;
+    throw cause;
+  }
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
@@ -50,6 +59,7 @@ var run = async (argv, env = {}) => {
   ]);
   return { exitCode, output: `${stdout}${stderr}` };
 };
+var run = runSoftwareCommand;
 var download = async (url, destination, sha256) => {
   const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
   if (!response.ok)
@@ -237,6 +247,8 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
 }
 export {
   validateSoftwareRequirements,
+  softwareSpawnFailure,
+  runSoftwareCommand,
   observeSoftwareHost,
   executeSoftwareOperation,
   ensureSoftwareRequirements,

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.50";
+export declare const VERSION = "0.1.52";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/agent",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",