@forgezero/agent 0.1.86 → 0.1.88

package/dist/provision.js

@@ -16,6 +16,7 @@ import {
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 var DEFAULT_AGENT_RELEASE_ROOT = "/opt/forgezero/agent";
+var DEFAULT_AGENT_CANDIDATE_LINK = `${DEFAULT_AGENT_RELEASE_ROOT}/candidate`;
 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*)$/;
@@ -209,25 +210,90 @@ function restoreAgentRelease(staged) {
     rmSync(next, { force: true });
   }
 }
+function selectAgentCandidate(staged) {
+  const link = join(dirname(staged.currentLink), "candidate");
+  const next = `${link}.${randomUUID()}.next`;
+  try {
+    symlinkSync(staged.nextTarget, next);
+    renameSync(next, link);
+    syncPath(dirname(link));
+  } finally {
+    rmSync(next, { force: true });
+  }
+}
+function clearAgentCandidate(root = DEFAULT_AGENT_RELEASE_ROOT) {
+  rmSync(join(resolve(root), "candidate"), { force: true });
+}
 
 // src/agent-update-helper.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import {
-  chmodSync as chmodSync2,
+  chmodSync as chmodSync3,
   closeSync as closeSync2,
-  existsSync as existsSync2,
+  existsSync as existsSync3,
   fsyncSync as fsyncSync2,
   mkdirSync as mkdirSync2,
   openSync as openSync2,
   readFileSync as readFileSync2,
-  renameSync as renameSync2,
-  rmSync as rmSync2,
-  unlinkSync,
+  renameSync as renameSync3,
+  rmSync as rmSync3,
+  unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync2
 } from "node:fs";
-import { connect, createServer } from "node:net";
-import { dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
+import { connect as connect2, createServer as createServer2 } from "node:net";
+import { dirname as dirname3, join as join2, resolve as resolve2 } from "node:path";
 import { DEFAULT_SOCKET } from "@forgezero/vault";
+
+// src/agent-handover.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { chmodSync as chmodSync2, existsSync as existsSync2, renameSync as renameSync2, rmSync as rmSync2, symlinkSync as symlinkSync2, unlinkSync } from "node:fs";
+import { basename, dirname as dirname2 } from "node:path";
+import { connect, createServer } from "node:net";
+var DEFAULT_AGENT_CANDIDATE_READY_SOCKET = "/run/forgezero/candidate-ready.sock";
+function switchAgentSocketRoute(route, backend) {
+  if (dirname2(route) !== dirname2(backend))
+    throw new Error("Agent handover sockets must share one runtime directory");
+  const target = basename(backend);
+  const next = `${route}.${randomUUID2()}.next`;
+  try {
+    symlinkSync2(target, next);
+    renameSync2(next, route);
+  } finally {
+    rmSync2(next, { force: true });
+  }
+}
+function probeAgentCandidate(expected, socketPath = DEFAULT_AGENT_CANDIDATE_READY_SOCKET, timeoutMs = 5000) {
+  return new Promise((resolve2) => {
+    const socket = connect(socketPath);
+    let buffer = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve2(value);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      try {
+        const value = JSON.parse(buffer.slice(0, newline));
+        finish(value.version === expected.version && value.nodeKey === expected.nodeKey && value.bound === expected.bound && expected.vault.includes(value.vault));
+      } catch {
+        finish(false);
+      }
+    });
+    socket.on("error", () => finish(false));
+  });
+}
+
+// src/agent-update-helper.ts
 var AGENT_UPDATE_GROUP = "forgezero-update";
 var AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-helper.service";
 var AGENT_UPDATE_JOURNAL = "/var/lib/forgezero/agent-update.json";
@@ -322,13 +388,13 @@ function validateJournal(value, root) {
   return journal;
 }
 function readJournal(path, root) {
-  if (!existsSync2(path))
+  if (!existsSync3(path))
     return;
   return validateJournal(JSON.parse(readFileSync2(path, "utf8")), root);
 }
 function writeAtomic(path, value, mode) {
-  mkdirSync2(dirname2(path), { recursive: true, mode: 493 });
-  const next = `${path}.${randomUUID2()}.next`;
+  mkdirSync2(dirname3(path), { recursive: true, mode: 493 });
+  const next = `${path}.${randomUUID3()}.next`;
   let file;
   try {
     file = openSync2(next, "wx", mode);
@@ -337,8 +403,8 @@ function writeAtomic(path, value, mode) {
     fsyncSync2(file);
     closeSync2(file);
     file = undefined;
-    renameSync2(next, path);
-    const directory = openSync2(dirname2(path), "r");
+    renameSync3(next, path);
+    const directory = openSync2(dirname3(path), "r");
     try {
       fsyncSync2(directory);
     } finally {
@@ -347,7 +413,7 @@ function writeAtomic(path, value, mode) {
   } finally {
     if (file !== undefined)
       closeSync2(file);
-    rmSync2(next, { force: true });
+    rmSync3(next, { force: true });
   }
 }
 var publicReceipt = (journal) => {
@@ -380,7 +446,7 @@ function writeUpdateState(journalPath, receiptPath, journal) {
 }
 function readAgentUpdateReceipt(path = AGENT_UPDATE_RECEIPT) {
   try {
-    if (!existsSync2(path))
+    if (!existsSync3(path))
       return;
     return validateReceipt(JSON.parse(readFileSync2(path, "utf8")));
   } catch {
@@ -420,10 +486,37 @@ var restartAgent = async (target, run) => {
     throw new Error(`systemd could not restart ${service}`);
   }
 };
+var candidateUnit = (target) => target === "compute" ? "forgezero-agent-candidate.service" : "forgezero-metal-agent-candidate.service";
+var startCandidate = async (staged, target, expectedNodeKey, run, probe = (expected) => probeAgentCandidate(expected, DEFAULT_AGENT_CANDIDATE_READY_SOCKET)) => {
+  selectAgentCandidate(staged);
+  if (!await runOk(run, "/usr/bin/systemctl", ["restart", candidateUnit(target)])) {
+    clearAgentCandidate(dirname3(staged.currentLink));
+    throw new Error(`systemd could not start ${candidateUnit(target)}`);
+  }
+  if (!await probe({
+    version: staged.version,
+    nodeKey: expectedNodeKey,
+    bound: true,
+    vault: target === "compute" ? ["ready"] : ["unbound"]
+  })) {
+    await run({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target)] });
+    clearAgentCandidate(dirname3(staged.currentLink));
+    throw new Error("the candidate Agent did not prove its identity and durable state");
+  }
+};
+var stopCandidate = async (staged, target, run) => {
+  await run({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target)] });
+  clearAgentCandidate(dirname3(staged.currentLink));
+};
+var socketPaths = (publicSocket = process.env.FZ_AGENT_PUBLIC_SOCKET ?? DEFAULT_SOCKET) => ({
+  route: `${publicSocket}.backend`,
+  active: `${publicSocket}.backend.active`,
+  candidate: `${publicSocket}.backend.candidate`
+});
 var targetProbe = (target, run) => 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"]);
 function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
   return new Promise((resolve3) => {
-    const socket = connect(socketPath);
+    const socket = connect2(socketPath);
     let settled = false;
     let buffer = "";
     const finish = (value) => {
@@ -456,12 +549,13 @@ function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
 async function activateAgentRelease(staged, options = {}) {
   const run = options.run ?? runCommand;
   const target = options.target ?? "compute";
-  const probe = options.probe ?? targetProbe(target, run);
+  const paths = socketPaths(options.publicSocketPath);
+  const probe = options.probe ?? (target === "compute" ? () => probeAgentSocket(paths.active) : targetProbe(target, run));
   const now = options.now ?? Date.now;
   const journalPath = options.journalPath ?? AGENT_UPDATE_JOURNAL;
   const receiptPath = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
-  const previous = readJournal(journalPath, dirname2(staged.currentLink));
-  const attemptId = options.attemptId ?? randomUUID2();
+  const previous = readJournal(journalPath, dirname3(staged.currentLink));
+  const attemptId = options.attemptId ?? randomUUID3();
   if (!ATTEMPT_ID.test(attemptId))
     throw new Error("Agent update attempt ID is invalid");
   const startedAtTs = now();
@@ -483,11 +577,19 @@ async function activateAgentRelease(staged, options = {}) {
   writeUpdateState(journalPath, receiptPath, journal);
   let selectionAttempted = false;
   try {
+    if (!options.candidatePrepared) {
+      throw new Error("direct activation requires a separately identity-bound candidate preparation");
+    }
+    if (target === "compute")
+      switchAgentSocketRoute(paths.route, paths.candidate);
     selectionAttempted = true;
     selectAgentRelease(staged);
     await restartAgent(target, run);
     if (!await probe())
-      throw new Error("the replacement Agent did not answer its retained Vault socket");
+      throw new Error("the replacement Agent did not answer its active Vault backend");
+    if (target === "compute")
+      switchAgentSocketRoute(paths.route, paths.active);
+    await stopCandidate(staged, target, run);
     journal = { ...journal, outcome: "active", updatedAtTs: now(), rollbackHealthy: undefined };
     writeUpdateState(journalPath, receiptPath, journal);
     run({
@@ -505,10 +607,13 @@ async function activateAgentRelease(staged, options = {}) {
         restored = true;
         await restartAgent(target, run);
         rollbackHealthy = await probe();
+        if (rollbackHealthy && target === "compute")
+          switchAgentSocketRoute(paths.route, paths.active);
       } catch {
         rollbackHealthy = false;
       }
     }
+    await stopCandidate(staged, target, run).catch(() => {});
     const failures = failureCount + 1;
     const updatedAtTs = now();
     journal = {
@@ -528,28 +633,38 @@ async function recoverInterruptedAgentUpdate(options = {}) {
   const root = resolve2(options.root ?? DEFAULT_AGENT_RELEASE_ROOT);
   const journalPath = options.journalPath ?? AGENT_UPDATE_JOURNAL;
   const receiptPath = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
+  const run = options.run ?? runCommand;
   const journal = readJournal(journalPath, root);
-  if (!journal)
+  if (!journal) {
+    for (const target of ["compute", "metal"]) {
+      await run({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target)] });
+    }
+    clearAgentCandidate(root);
     return;
+  }
   if (journal.outcome !== "activating") {
+    await stopCandidate(stagedFromJournal(journal, root), journal.target, run).catch(() => {});
     writeAtomic(receiptPath, publicReceipt(journal), 416);
     return publicReceipt(journal);
   }
   const staged = stagedFromJournal(journal, root);
-  if (!existsSync2(join2(root, journal.previousTarget))) {
+  if (!existsSync3(join2(root, journal.previousTarget))) {
     throw new Error("Agent update rollback release is missing");
   }
-  const run = options.run ?? runCommand;
-  const probe = options.probe ?? targetProbe(journal.target, run);
+  const paths = socketPaths(options.publicSocketPath);
+  const probe = options.probe ?? (journal.target === "compute" ? () => probeAgentSocket(paths.active) : targetProbe(journal.target, run));
   restoreAgentRelease(staged);
   let rollbackHealthy = false;
   let failureMessage = "activation was interrupted before its health verdict became durable";
   try {
     await restartAgent(journal.target, run);
     rollbackHealthy = await probe();
+    if (rollbackHealthy && journal.target === "compute")
+      switchAgentSocketRoute(paths.route, paths.active);
   } catch (cause) {
     failureMessage = `${failureMessage}; ${cause instanceof Error ? cause.message : String(cause)}`;
   }
+  await stopCandidate(staged, journal.target, run).catch(() => {});
   const failures = journal.failureCount + 1;
   const updatedAtTs = (options.now ?? Date.now)();
   const recovered = {
@@ -566,15 +681,23 @@ async function recoverInterruptedAgentUpdate(options = {}) {
 }
 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));
+  if (existsSync3(socketPath))
+    unlinkSync2(socketPath);
+  mkdirSync2(dirname3(socketPath), { recursive: true, mode: 488 });
   const receiptPath = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
   const journalPath = options.journalPath ?? AGENT_UPDATE_JOURNAL;
   const releaseRoot = options.root ?? DEFAULT_AGENT_RELEASE_ROOT;
-  const activate = options.activate ?? ((staged, target, attemptId) => activateAgentRelease(staged, { target, attemptId, journalPath, receiptPath, now: options.now }));
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const activate = options.activate ?? ((staged, target, attemptId) => activateAgentRelease(staged, {
+    target,
+    attemptId,
+    journalPath,
+    receiptPath,
+    now: options.now,
+    candidatePrepared: true
+  }));
   let busy = true;
+  let pending;
   let blocked;
   (options.recover ?? (() => recoverInterruptedAgentUpdate({
     root: releaseRoot,
@@ -586,7 +709,7 @@ function startAgentUpdateHelper(options = {}) {
   }).finally(() => {
     busy = false;
   });
-  const server = createServer((socket) => {
+  const server = createServer2((socket) => {
     let buffer = "";
     socket.on("data", (chunk) => {
       buffer += chunk.toString("utf8");
@@ -605,16 +728,52 @@ function startAgentUpdateHelper(options = {}) {
       Promise.resolve().then(() => JSON.parse(line)).then(async (request) => {
         if (blocked)
           throw new Error(`update journal needs operator recovery: ${blocked}`);
-        if (busy)
-          throw new Error("another Agent update or recovery is already active");
-        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 attemptId = request.attemptId ?? randomUUID2();
+        const attemptId = request.attemptId ?? randomUUID3();
         if (!ATTEMPT_ID.test(attemptId))
           throw new Error("Agent update attempt ID is invalid");
+        if (request.op === "commit" || request.op === "abort") {
+          if (!pending || pending.attemptId !== attemptId || pending.target !== request.target || pending.staged.fromVersion !== request.currentVersion || pending.staged.version !== request.targetVersion) {
+            throw new Error("Agent update handover does not match the prepared candidate");
+          }
+          const selected = pending;
+          pending = undefined;
+          if (request.op === "abort") {
+            await stopCandidate(selected.staged, selected.target, runCommand);
+            busy = false;
+            const response3 = {
+              ok: true,
+              status: "aborted",
+              version: selected.staged.version,
+              attemptId
+            };
+            socket.end(`${JSON.stringify(response3)}
+`);
+            return;
+          }
+          const outcome = await activate(selected.staged, selected.target, attemptId);
+          busy = false;
+          if (outcome?.ok === false)
+            throw new Error(outcome.reason ?? "Agent handover failed");
+          const response2 = {
+            ok: true,
+            status: "active",
+            version: selected.staged.version,
+            attemptId
+          };
+          socket.end(`${JSON.stringify(response2)}
+`);
+          return;
+        }
+        if (request.op !== "prepare")
+          throw new Error("unknown update operation");
+        if (typeof request.expectedNodeKey !== "string" || request.expectedNodeKey.length < 16 || Buffer.byteLength(request.expectedNodeKey, "utf8") > 512 || /[\0\r\n]/.test(request.expectedNodeKey)) {
+          throw new Error("Agent update expected node identity is invalid");
+        }
+        if (busy)
+          throw new Error("another Agent update or recovery is already active");
         const prior = readJournal(journalPath, releaseRoot);
         const now = (options.now ?? Date.now)();
         if (prior?.targetVersion === request.release.version && (prior.outcome === "rolled-back" || prior.outcome === "failed") && (prior.retryAfterTs ?? 0) > now)
@@ -625,17 +784,23 @@ function startAgentUpdateHelper(options = {}) {
           currentVersion: request.currentVersion,
           root: releaseRoot
         });
-        const response = { ok: true, status: "staged", version: staged.version, attemptId };
+        await startCandidate(staged, request.target, request.expectedNodeKey, runCommand);
+        pending = { staged, target: request.target, attemptId, expectedNodeKey: request.expectedNodeKey };
+        ownsBusy = false;
+        setTimer(() => {
+          if (pending?.attemptId !== attemptId)
+            return;
+          const expired = pending;
+          pending = undefined;
+          stopCandidate(expired.staged, expired.target, runCommand).finally(() => {
+            busy = false;
+          });
+        }, 180000);
+        const response = { ok: true, status: "prepared", version: staged.version, attemptId };
         socket.end(`${JSON.stringify(response)}
 `);
-        setTimer(() => void activate(staged, request.target, attemptId).catch((cause) => {
-          blocked = cause instanceof Error ? cause.message : String(cause);
-        }).finally(() => {
-          busy = false;
-        }), 100);
-        ownsBusy = false;
       }).catch((cause) => {
-        if (ownsBusy)
+        if (ownsBusy && !pending)
           busy = false;
         const response = {
           ok: false,
@@ -647,12 +812,12 @@ function startAgentUpdateHelper(options = {}) {
     });
     socket.on("error", () => socket.destroy());
   });
-  server.listen(socketPath, () => chmodSync2(socketPath, 432));
+  server.listen(socketPath, () => chmodSync3(socketPath, 432));
   return server;
 }
 function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, timeoutMs = 90000) {
   return new Promise((resolve3, reject) => {
-    const socket = connect(socketPath, () => socket.write(`${JSON.stringify(request)}
+    const socket = connect2(socketPath, () => socket.write(`${JSON.stringify(request)}
 `));
     let buffer = "";
     socket.setTimeout(timeoutMs, () => {
@@ -680,22 +845,22 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 import { createHash as createHash2 } from "node:crypto";
 import {
   accessSync,
-  chmodSync as chmodSync3,
+  chmodSync as chmodSync4,
   copyFileSync,
   createReadStream,
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   mkdtempSync,
   mkdirSync as mkdirSync3,
   readFileSync as readFileSync3,
-  renameSync as renameSync3,
-  rmSync as rmSync3,
+  renameSync as renameSync4,
+  rmSync as rmSync4,
   statSync,
-  symlinkSync as symlinkSync2,
-  unlinkSync as unlinkSync2,
+  symlinkSync as symlinkSync3,
+  unlinkSync as unlinkSync3,
   writeFileSync as writeFileSync3
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname as dirname3, join as join3 } from "node:path";
+import { dirname as dirname4, join as join3 } from "node:path";
 var PINNED_BUN_VERSION = "1.3.14";
 var BUN_RELEASE_SHA256 = "951ee2aee855f08595aeec6225226a298d3fea83a3dcd6465c09cbccdf7e848f";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
@@ -868,23 +1033,23 @@ var softwareDownloadCommand = (url, destination, maximumBytes) => {
   ];
 };
 var download = async (url, destination, sha256, maximumBytes = 512 * 1024 * 1024) => {
-  if (existsSync3(destination))
+  if (existsSync4(destination))
     throw new Error("download destination already exists");
   const received = await run(softwareDownloadCommand(url, destination, maximumBytes));
   if (received.exitCode !== 0) {
-    rmSync3(destination, { force: true });
+    rmSync4(destination, { force: true });
     throw new Error(`software download failed (${received.exitCode}): ${received.output.trim()}`);
   }
-  chmodSync3(destination, 384);
+  chmodSync4(destination, 384);
   if (statSync(destination).size > maximumBytes) {
-    rmSync3(destination, { force: true });
+    rmSync4(destination, { force: true });
     throw new Error("download exceeds reviewed size bound");
   }
   const digest = createHash2("sha256");
   for await (const chunk of createReadStream(destination))
     digest.update(chunk);
   if (digest.digest("hex") !== sha256) {
-    rmSync3(destination, { force: true });
+    rmSync4(destination, { force: true });
     throw new Error("download checksum mismatch");
   }
 };
@@ -900,12 +1065,12 @@ var aptInstallMany = async (names) => {
   return update.exitCode === 0 ? run(["/usr/bin/apt-get", "install", "-y", ...names], environment) : update;
 };
 var writeOwnedPolicy = (pathValue, content, mode = 420) => {
-  if (existsSync3(pathValue)) {
+  if (existsSync4(pathValue)) {
     if (readFileSync3(pathValue, "utf8") !== content)
       throw new Error(`refusing to overwrite non-ForgeZero policy at ${pathValue}`);
     return;
   }
-  mkdirSync3(dirname3(pathValue), { recursive: true, mode: 493 });
+  mkdirSync3(dirname4(pathValue), { recursive: true, mode: 493 });
   writeFileSync3(pathValue, content, { mode, flag: "wx" });
 };
 var installContainerdRuntime = async (directory, osVersion) => {
@@ -917,7 +1082,7 @@ var installContainerdRuntime = async (directory, osVersion) => {
   const nerdctlExtract = await run(["/usr/bin/tar", "-xzf", nerdctl, "-C", "/usr/local/bin", "nerdctl"]);
   if (nerdctlExtract.exitCode !== 0)
     return nerdctlExtract;
-  chmodSync3("/usr/local/bin/nerdctl", 493);
+  chmodSync4("/usr/local/bin/nerdctl", 493);
   const buildkit = join3(directory, "buildkit.tar.gz");
   await download(`https://github.com/moby/buildkit/releases/download/v${BUILDKIT_VERSION}/buildkit-v${BUILDKIT_VERSION}.linux-amd64.tar.gz`, buildkit, BUILDKIT_SHA256);
   const unpacked = join3(directory, "buildkit");
@@ -927,15 +1092,15 @@ var installContainerdRuntime = async (directory, osVersion) => {
     return buildkitExtract;
   for (const binary of ["buildctl", "buildkitd"]) {
     copyFileSync(join3(unpacked, "bin", binary), `/usr/local/bin/${binary}`);
-    chmodSync3(`/usr/local/bin/${binary}`, 493);
+    chmodSync4(`/usr/local/bin/${binary}`, 493);
   }
   mkdirSync3("/etc/containerd", { recursive: true, mode: 493 });
   const expected = CONTAINERD_CONFIG(false);
   const kataExpected = CONTAINERD_CONFIG(true);
-  if (existsSync3(CONTAINERD_CONFIG_PATH) && ![expected, kataExpected].includes(readFileSync3(CONTAINERD_CONFIG_PATH, "utf8"))) {
+  if (existsSync4(CONTAINERD_CONFIG_PATH) && ![expected, kataExpected].includes(readFileSync3(CONTAINERD_CONFIG_PATH, "utf8"))) {
     return { exitCode: 2, output: "refusing to overwrite an existing containerd configuration that differs from the reviewed ForgeZero policy" };
   }
-  if (!existsSync3(CONTAINERD_CONFIG_PATH))
+  if (!existsSync4(CONTAINERD_CONFIG_PATH))
     writeFileSync3(CONTAINERD_CONFIG_PATH, expected, { mode: 420, flag: "wx" });
   writeOwnedPolicy("/etc/systemd/system/forgezero-buildkit.service", BUILDKIT_UNIT);
   mkdirSync3("/var/lib/forgezero/containerd", { recursive: true, mode: 448 });
@@ -948,10 +1113,10 @@ var installContainerdRuntime = async (directory, osVersion) => {
 };
 var installKataRuntime = async (directory) => {
   for (const pathValue of ["/dev/kvm", "/dev/sev"])
-    if (!existsSync3(pathValue))
+    if (!existsSync4(pathValue))
       return { exitCode: 2, output: `${pathValue} is required for Kata SEV-SNP` };
   for (const parameter of ["/sys/module/kvm_amd/parameters/sev", "/sys/module/kvm_amd/parameters/sev_snp"]) {
-    if (!existsSync3(parameter) || !/^(1|Y)$/i.test(readFileSync3(parameter, "utf8").trim()))
+    if (!existsSync4(parameter) || !/^(1|Y)$/i.test(readFileSync3(parameter, "utf8").trim()))
       return { exitCode: 2, output: `${parameter} does not enable SEV-SNP` };
   }
   const dependencies = await aptInstallMany(["zstd"]);
@@ -966,7 +1131,7 @@ var installKataRuntime = async (directory) => {
   const extracted = await run(["/usr/bin/tar", "-xf", tar, "-C", "/"]);
   if (extracted.exitCode !== 0)
     return extracted;
-  if (!existsSync3("/opt/kata/bin/containerd-shim-kata-v2") || !existsSync3(KATA_SNP_CONFIG_PATH)) {
+  if (!existsSync4("/opt/kata/bin/containerd-shim-kata-v2") || !existsSync4(KATA_SNP_CONFIG_PATH)) {
     return { exitCode: 2, output: "Kata archive does not contain the reviewed QEMU SNP runtime and configuration" };
   }
   const snpConfig = readFileSync3(KATA_SNP_CONFIG_PATH, "utf8");
@@ -974,19 +1139,19 @@ var installKataRuntime = async (directory) => {
     return { exitCode: 2, output: "Kata QEMU configuration does not enable confidential SEV-SNP guests" };
   }
   mkdirSync3("/etc/kata-containers", { recursive: true, mode: 493 });
-  if (existsSync3(KATA_ACTIVE_CONFIG_PATH) && readFileSync3(KATA_ACTIVE_CONFIG_PATH, "utf8") !== snpConfig) {
+  if (existsSync4(KATA_ACTIVE_CONFIG_PATH) && readFileSync3(KATA_ACTIVE_CONFIG_PATH, "utf8") !== snpConfig) {
     return { exitCode: 2, output: "refusing to overwrite a non-ForgeZero Kata runtime configuration" };
   }
-  if (!existsSync3(KATA_ACTIVE_CONFIG_PATH))
+  if (!existsSync4(KATA_ACTIVE_CONFIG_PATH))
     copyFileSync(KATA_SNP_CONFIG_PATH, KATA_ACTIVE_CONFIG_PATH);
-  chmodSync3(KATA_ACTIVE_CONFIG_PATH, 420);
+  chmodSync4(KATA_ACTIVE_CONFIG_PATH, 420);
   try {
-    unlinkSync2("/usr/local/bin/containerd-shim-kata-v2");
+    unlinkSync3("/usr/local/bin/containerd-shim-kata-v2");
   } catch {}
-  symlinkSync2("/opt/kata/bin/containerd-shim-kata-v2", "/usr/local/bin/containerd-shim-kata-v2");
+  symlinkSync3("/opt/kata/bin/containerd-shim-kata-v2", "/usr/local/bin/containerd-shim-kata-v2");
   const base = CONTAINERD_CONFIG(false);
   const kata = CONTAINERD_CONFIG(true);
-  if (!existsSync3(CONTAINERD_CONFIG_PATH) || ![base, kata].includes(readFileSync3(CONTAINERD_CONFIG_PATH, "utf8"))) {
+  if (!existsSync4(CONTAINERD_CONFIG_PATH) || ![base, kata].includes(readFileSync3(CONTAINERD_CONFIG_PATH, "utf8"))) {
     return { exitCode: 2, output: "containerd must use the reviewed ForgeZero policy before Kata is installed" };
   }
   if (readFileSync3(CONTAINERD_CONFIG_PATH, "utf8") !== kata)
@@ -1006,7 +1171,7 @@ async function executeSoftwareOperation(operation) {
       const binary = await run(["/usr/bin/docker", "--version"]);
       if (!successful(binary, /Docker version/))
         return { ...binary, exitCode: 1 };
-      if (!existsSync3(DOCKER_DAEMON_PATH) || readFileSync3(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG)
+      if (!existsSync4(DOCKER_DAEMON_PATH) || readFileSync3(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG)
         return { exitCode: 1, output: "Docker daemon policy is absent or differs from the reviewed ForgeZero policy" };
       const active = await run(["/usr/bin/systemctl", "is-active", "--quiet", "docker.service"]);
       return active.exitCode === 0 ? { exitCode: 0, output: binary.output } : active;
@@ -1019,17 +1184,17 @@ async function executeSoftwareOperation(operation) {
         run(["/usr/bin/systemctl", "is-active", "--quiet", "containerd.service"]),
         run(["/usr/bin/systemctl", "is-active", "--quiet", "forgezero-buildkit.service"])
       ]);
-      const policy = existsSync3(CONTAINERD_CONFIG_PATH) ? readFileSync3(CONTAINERD_CONFIG_PATH, "utf8") : "";
+      const policy = existsSync4(CONTAINERD_CONFIG_PATH) ? readFileSync3(CONTAINERD_CONFIG_PATH, "utf8") : "";
       const validPolicy = policy === CONTAINERD_CONFIG(false) || policy === CONTAINERD_CONFIG(true);
       return successful(containerd, /containerd/) && successful(nerdctl, new RegExp(NERDCTL_VERSION.replaceAll(".", "\\."))) && successful(buildkit, new RegExp(BUILDKIT_VERSION.replaceAll(".", "\\."))) && active.exitCode === 0 && builder.exitCode === 0 && validPolicy ? { exitCode: 0, output: `${containerd.output}${nerdctl.output}${buildkit.output}` } : { exitCode: 1, output: "containerd, nerdctl, BuildKit, or ForgeZero storage/runtime policy is unavailable" };
     }
     if (software === "kata-containers") {
       const shim = await run(["/opt/kata/bin/containerd-shim-kata-v2", "--version"]);
-      const policy = existsSync3(CONTAINERD_CONFIG_PATH) ? readFileSync3(CONTAINERD_CONFIG_PATH, "utf8") : "";
-      const activeConfig = existsSync3(KATA_ACTIVE_CONFIG_PATH) ? readFileSync3(KATA_ACTIVE_CONFIG_PATH, "utf8") : "";
-      const host = ["/dev/kvm", "/dev/sev", KATA_SNP_CONFIG_PATH, KATA_ACTIVE_CONFIG_PATH].every(existsSync3) && ["/sys/module/kvm_amd/parameters/sev", "/sys/module/kvm_amd/parameters/sev_snp"].every((parameter) => existsSync3(parameter) && /^(1|Y)$/i.test(readFileSync3(parameter, "utf8").trim()));
+      const policy = existsSync4(CONTAINERD_CONFIG_PATH) ? readFileSync3(CONTAINERD_CONFIG_PATH, "utf8") : "";
+      const activeConfig = existsSync4(KATA_ACTIVE_CONFIG_PATH) ? readFileSync3(KATA_ACTIVE_CONFIG_PATH, "utf8") : "";
+      const host = ["/dev/kvm", "/dev/sev", KATA_SNP_CONFIG_PATH, KATA_ACTIVE_CONFIG_PATH].every(existsSync4) && ["/sys/module/kvm_amd/parameters/sev", "/sys/module/kvm_amd/parameters/sev_snp"].every((parameter) => existsSync4(parameter) && /^(1|Y)$/i.test(readFileSync3(parameter, "utf8").trim()));
       const active = await run(["/usr/bin/systemctl", "is-active", "--quiet", "containerd.service"]);
-      return successful(shim, /kata.*4\.0\.0/i) && policy === CONTAINERD_CONFIG(true) && activeConfig === (existsSync3(KATA_SNP_CONFIG_PATH) ? readFileSync3(KATA_SNP_CONFIG_PATH, "utf8") : "") && host && active.exitCode === 0 ? { exitCode: 0, output: shim.output } : { exitCode: 1, output: "Kata QEMU SNP runtime, host capability, or containerd policy is unavailable" };
+      return successful(shim, /kata.*4\.0\.0/i) && policy === CONTAINERD_CONFIG(true) && activeConfig === (existsSync4(KATA_SNP_CONFIG_PATH) ? readFileSync3(KATA_SNP_CONFIG_PATH, "utf8") : "") && host && active.exitCode === 0 ? { exitCode: 0, output: shim.output } : { exitCode: 1, output: "Kata QEMU SNP runtime, host capability, or containerd policy is unavailable" };
     }
     if (software === "nginx") {
       const binary = await run(["/usr/sbin/nginx", "-v"]);
@@ -1070,10 +1235,10 @@ async function executeSoftwareOperation(operation) {
       return installed;
     if (software === "docker") {
       mkdirSync3("/etc/docker", { recursive: true, mode: 493 });
-      if (existsSync3(DOCKER_DAEMON_PATH) && readFileSync3(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG) {
+      if (existsSync4(DOCKER_DAEMON_PATH) && readFileSync3(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG) {
         return { exitCode: 2, output: "refusing to overwrite an existing Docker daemon configuration that differs from the reviewed ForgeZero policy" };
       }
-      if (!existsSync3(DOCKER_DAEMON_PATH))
+      if (!existsSync4(DOCKER_DAEMON_PATH))
         writeFileSync3(DOCKER_DAEMON_PATH, DOCKER_DAEMON_CONFIG, { mode: 420, flag: "wx" });
       const enabled = await run(["/usr/bin/systemctl", "enable", "docker.service"]);
       return enabled.exitCode === 0 ? run(["/usr/bin/systemctl", "restart", "docker.service"]) : enabled;
@@ -1123,20 +1288,20 @@ async function executeSoftwareOperation(operation) {
         return unzipped;
       mkdirSync3("/usr/local/lib/forgezero/runtime", { recursive: true, mode: 493 });
       copyFileSync(join3(unpacked, "bun-linux-x64", "bun"), "/usr/local/lib/forgezero/runtime/bun.next");
-      chmodSync3("/usr/local/lib/forgezero/runtime/bun.next", 493);
-      renameSync3("/usr/local/lib/forgezero/runtime/bun.next", "/usr/local/lib/forgezero/runtime/bun");
+      chmodSync4("/usr/local/lib/forgezero/runtime/bun.next", 493);
+      renameSync4("/usr/local/lib/forgezero/runtime/bun.next", "/usr/local/lib/forgezero/runtime/bun");
       try {
-        unlinkSync2("/usr/local/bin/bun");
+        unlinkSync3("/usr/local/bin/bun");
       } catch {}
-      symlinkSync2("/usr/local/lib/forgezero/runtime/bun", "/usr/local/bin/bun");
+      symlinkSync3("/usr/local/lib/forgezero/runtime/bun", "/usr/local/bin/bun");
       return { exitCode: 0, output: "" };
     }
     if (software === "cloudflared") {
       const binary = join3(directory, "cloudflared");
       await download("https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64", binary, CLOUDFLARED_SHA256);
-      chmodSync3(binary, 493);
+      chmodSync4(binary, 493);
       copyFileSync(binary, "/usr/local/bin/cloudflared");
-      chmodSync3("/usr/local/bin/cloudflared", 493);
+      chmodSync4("/usr/local/bin/cloudflared", 493);
       return { exitCode: 0, output: "" };
     }
     const deb = join3(directory, "arangodb.deb");
@@ -1149,7 +1314,7 @@ async function executeSoftwareOperation(operation) {
     await run(["/usr/bin/systemctl", "disable", "--now", "arangodb3.service"]);
     return { exitCode: 0, output: "" };
   } finally {
-    rmSync3(directory, { recursive: true, force: true });
+    rmSync4(directory, { recursive: true, force: true });
   }
 }
 function observeSoftwareHost(osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch) {
@@ -1648,9 +1813,9 @@ function phasePipeline(definition, phase, profile, executeRelease = false) {
 
 // src/deployment-connectivity.ts
 import { createHash as createHash3 } from "node:crypto";
-import { mkdirSync as mkdirSync4, renameSync as renameSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { mkdirSync as mkdirSync4, renameSync as renameSync5, writeFileSync as writeFileSync4 } from "node:fs";
 import { createConnection } from "node:net";
-import { dirname as dirname4 } from "node:path";
+import { dirname as dirname5 } from "node:path";
 
 // src/process-input.ts
 async function writeAndCloseProcessInput(input, value) {
@@ -1671,7 +1836,7 @@ var checked2 = async (host, argv2, label) => {
   return result.output.trim();
 };
 async function sealWithSystemd(name, path2, value) {
-  mkdirSync4(dirname4(path2), { recursive: true, mode: 448 });
+  mkdirSync4(dirname5(path2), { recursive: true, mode: 448 });
   const next = `${path2}.next`;
   const child = Bun.spawn(["/usr/bin/systemd-creds", "encrypt", `--name=${name}`, "-", next], {
     stdin: "pipe",
@@ -1687,15 +1852,15 @@ async function sealWithSystemd(name, path2, value) {
   ]);
   if (exitCode !== 0)
     throw new Error(`systemd credential sealing failed: ${`${stdout}${stderr}`.replaceAll(value, "[REDACTED]").slice(0, 512)}`);
-  renameSync4(next, path2);
+  renameSync5(next, path2);
 }
 var defaultHost = {
   seal: sealWithSystemd,
   write(path2, content, mode) {
-    mkdirSync4(dirname4(path2), { recursive: true, mode: 493 });
+    mkdirSync4(dirname5(path2), { recursive: true, mode: 493 });
     const next = `${path2}.next`;
     writeFileSync4(next, content, { mode });
-    renameSync4(next, path2);
+    renameSync5(next, path2);
   },
   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" } });
@@ -1927,14 +2092,14 @@ WantedBy=multi-user.target
 }
 
 // src/software-helper.ts
-import { chmodSync as chmodSync4, existsSync as existsSync6, mkdirSync as mkdirSync7, unlinkSync as unlinkSync3 } from "node:fs";
-import { connect as connect2, createServer as createServer2 } from "node:net";
-import { dirname as dirname7 } from "node:path";
+import { chmodSync as chmodSync5, existsSync as existsSync7, mkdirSync as mkdirSync7, unlinkSync as unlinkSync4 } from "node:fs";
+import { connect as connect3, createServer as createServer3 } from "node:net";
+import { dirname as dirname8 } from "node:path";
 
 // src/service-supervisor.ts
 import { createHash as createHash4 } from "node:crypto";
-import { existsSync as existsSync4, mkdirSync as mkdirSync5, readFileSync as readFileSync4, readdirSync, realpathSync, renameSync as renameSync5, rmSync as rmSync4, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname as dirname5, join as join4, resolve as resolve3, sep } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync4, readdirSync, realpathSync, renameSync as renameSync6, rmSync as rmSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname6, join as join4, resolve as resolve3, sep } from "node:path";
 var SERVICE_STATE_DIRECTORY = "/var/lib/forgezero/services";
 var SERVICE_CONFIG_DIRECTORY = "/etc/forgezero/services";
 var SERVICE_UNIT_DIRECTORY = "/etc/systemd/system";
@@ -1944,17 +2109,17 @@ var statePath = (id) => `${SERVICE_STATE_DIRECTORY}/${id}.json`;
 var within = (root, path2) => path2 === root || path2.startsWith(`${root}${sep}`);
 var defaultHost2 = {
   write(path2, content, mode) {
-    mkdirSync5(dirname5(path2), { recursive: true, mode: 493 });
+    mkdirSync5(dirname6(path2), { recursive: true, mode: 493 });
     const next = `${path2}.next`;
     writeFileSync5(next, content, { mode });
-    renameSync5(next, path2);
+    renameSync6(next, path2);
   },
   read: (path2) => readFileSync4(path2, "utf8"),
-  exists: existsSync4,
-  list: (path2) => existsSync4(path2) ? readdirSync(path2) : [],
+  exists: existsSync5,
+  list: (path2) => existsSync5(path2) ? readdirSync(path2) : [],
   realpath: realpathSync,
   mkdir: (path2, mode) => mkdirSync5(path2, { recursive: true, mode }),
-  remove: (path2) => rmSync4(path2, { force: true }),
+  remove: (path2) => rmSync5(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",
@@ -2150,20 +2315,20 @@ async function activateSupervisedService(request, host = defaultHost2) {
 
 // src/container-supervisor.ts
 import { createHash as createHash5 } from "node:crypto";
-import { existsSync as existsSync5, mkdirSync as mkdirSync6, readFileSync as readFileSync5, readdirSync as readdirSync2, realpathSync as realpathSync2, renameSync as renameSync6, rmSync as rmSync5, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname6, resolve as resolve4, sep as sep2 } from "node:path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync6, readFileSync as readFileSync5, readdirSync as readdirSync2, realpathSync as realpathSync2, renameSync as renameSync7, rmSync as rmSync6, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname7, resolve as resolve4, sep as sep2 } from "node:path";
 var defaultHost3 = {
   realpath: realpathSync2,
-  exists: existsSync5,
+  exists: existsSync6,
   read: (path2) => readFileSync5(path2, "utf8"),
   write(path2, content, mode) {
-    mkdirSync6(dirname6(path2), { recursive: true, mode: 493 });
+    mkdirSync6(dirname7(path2), { recursive: true, mode: 493 });
     const next = `${path2}.next`;
     writeFileSync6(next, content, { mode });
-    renameSync6(next, path2);
+    renameSync7(next, path2);
   },
-  remove: (path2) => rmSync5(path2, { force: true }),
-  list: (path2) => existsSync5(path2) ? readdirSync2(path2) : [],
+  remove: (path2) => rmSync6(path2, { force: true }),
+  list: (path2) => existsSync6(path2) ? readdirSync2(path2) : [],
   mkdir: (path2, mode) => mkdirSync6(path2, { recursive: true, mode }),
   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" } });
@@ -2458,9 +2623,9 @@ var MAX_REQUEST_BYTES2 = 128 * 1024;
 var MAX_PENDING_REQUESTS = 128;
 function startSoftwareHelper(options = {}) {
   const socketPath = options.socketPath ?? DEFAULT_SOFTWARE_HELPER_SOCKET;
-  if (existsSync6(socketPath))
-    unlinkSync3(socketPath);
-  mkdirSync7(dirname7(socketPath), { recursive: true, mode: 488 });
+  if (existsSync7(socketPath))
+    unlinkSync4(socketPath);
+  mkdirSync7(dirname8(socketPath), { recursive: true, mode: 488 });
   const ensure = options.ensure ?? ensureSoftwareRequirements;
   const activate = options.activate ?? activateSupervisedService;
   const buildContainer = options.buildContainer ?? buildContainerImage;
@@ -2468,7 +2633,7 @@ function startSoftwareHelper(options = {}) {
   const applyConnectivity = options.applyConnectivity ?? applyDeploymentConnectivity;
   let tail = Promise.resolve();
   let pending = 0;
-  const server = createServer2((socket) => {
+  const server = createServer3((socket) => {
     let buffer = "";
     socket.on("data", (chunk) => {
       buffer += chunk.toString("utf8");
@@ -2547,12 +2712,12 @@ function startSoftwareHelper(options = {}) {
     });
     socket.on("error", () => socket.destroy());
   });
-  server.listen(socketPath, () => chmodSync4(socketPath, 432));
+  server.listen(socketPath, () => chmodSync5(socketPath, 432));
   return server;
 }
 function requestContainer(op, request, socketPath, timeoutMs) {
   return new Promise((resolve5, reject) => {
-    const socket = connect2(socketPath, () => socket.write(`${JSON.stringify({ op, request })}
+    const socket = connect3(socketPath, () => socket.write(`${JSON.stringify({ op, request })}
 `));
     let buffer = "";
     socket.setTimeout(timeoutMs, () => {
@@ -2590,7 +2755,7 @@ function requestDeploymentConnectivity(request, socketPath = DEFAULT_SOFTWARE_HE
 }
 function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 10 * 60000) {
   return new Promise((resolve5, reject) => {
-    const socket = connect2(socketPath, () => socket.write(`${JSON.stringify({ op: "activate-service", request })}
+    const socket = connect3(socketPath, () => socket.write(`${JSON.stringify({ op: "activate-service", request })}
 `));
     let buffer = "";
     socket.setTimeout(timeoutMs, () => {
@@ -2619,7 +2784,7 @@ function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_
 function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
   validateSoftwareRequirements(requirements);
   return new Promise((resolve5, reject) => {
-    const socket = connect2(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
+    const socket = connect3(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
 `));
     let buffer = "";
     socket.setTimeout(timeoutMs, () => {
@@ -2647,7 +2812,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.86";
+var VERSION3 = "0.1.88";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";
@@ -2763,6 +2928,7 @@ 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 AGENT_SOCKET_PROXY_UNIT_PATH = "/etc/systemd/system/forgezero-agent-proxy.service";
+var AGENT_CANDIDATE_UNIT_PATH = "/etc/systemd/system/forgezero-agent-candidate.service";
 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";
@@ -2874,6 +3040,7 @@ Type=simple
 User=root
 Group=${AGENT_UPDATE_GROUP}
 Environment=FZ_AGENT_UPDATE_SOCKET=${DEFAULT_AGENT_UPDATE_SOCKET}
+Environment=FZ_AGENT_PUBLIC_SOCKET=${systemdPath(options.socketPath, "agent socket")}
 ExecStart=${bin} update-helper
 Restart=always
 RestartSec=2
@@ -2918,13 +3085,11 @@ WantedBy=sockets.target
 `;
 }
 function agentSocketProxyUnit(options) {
-  const backend = agentBackendSocketPath(options.socketPath);
+  const backend = agentRoutingSocketPath(options.socketPath);
   const user = options.user ?? "forgezero";
   return `[Unit]
 Description=ForgeZero application Vault socket proxy
 Documentation=https://www.forgezero.net/docs/agent
-Requires=forgezero-agent.service
-After=forgezero-agent.service
 
 [Service]
 User=${user}
@@ -2945,12 +3110,26 @@ RestrictAddressFamilies=AF_UNIX
 `;
 }
 function agentBackendSocketPath(publicSocketPath) {
+  const socket = systemdPath(publicSocketPath, "agent socket");
+  const backend = `${socket}.backend.active`;
+  if (Buffer.byteLength(backend) > 100)
+    throw new Error("agent socket path is too long for a Unix socket");
+  return backend;
+}
+function agentRoutingSocketPath(publicSocketPath) {
   const socket = systemdPath(publicSocketPath, "agent socket");
   const backend = `${socket}.backend`;
   if (Buffer.byteLength(backend) > 100)
     throw new Error("agent socket path is too long for a Unix socket");
   return backend;
 }
+function agentCandidateSocketPath(publicSocketPath) {
+  const socket = systemdPath(publicSocketPath, "agent socket");
+  const backend = `${socket}.backend.candidate`;
+  if (Buffer.byteLength(backend) > 100)
+    throw new Error("agent socket path is too long for a Unix socket");
+  return backend;
+}
 var systemdPath = (value, label) => {
   if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
     throw new Error(`invalid ${label} path`);
@@ -3234,7 +3413,11 @@ function agentUnit(options) {
   }
   const environment = [
     "NODE_ENV=production",
-    `FZ_SOCKET_PATH=${agentBackendSocketPath(options.socketPath)}`,
+    `FZ_SOCKET_PATH=${options.backendSocketPath ?? agentBackendSocketPath(options.socketPath)}`,
+    `FZ_AGENT_PUBLIC_SOCKET=${options.socketPath}`,
+    `FZ_AGENT_ROUTE_SOCKET=${agentRoutingSocketPath(options.socketPath)}`,
+    options.handoverCandidate ? "FZ_AGENT_HANDOVER_CANDIDATE=true" : null,
+    options.handoverCandidate ? `FZ_AGENT_HANDOVER_READY_SOCKET=${DEFAULT_AGENT_CANDIDATE_READY_SOCKET}` : null,
     `FZ_CONTROL_SOCKET=${controlSocketPath}`,
     `FZ_SEED_CREDENTIAL=agent-seed`,
     `FZ_AGENT_MODE=${options.mode}`,
@@ -3371,6 +3554,26 @@ ${deploymentWrites}
 WantedBy=multi-user.target
 `;
 }
+function agentCandidateUnit(options) {
+  return agentUnit({
+    ...options,
+    binPath: `${DEFAULT_AGENT_RELEASE_ROOT}/candidate/dist/fz-agent.js`,
+    backendSocketPath: agentCandidateSocketPath(options.socketPath),
+    handoverCandidate: true,
+    gitCredentialPath: undefined,
+    deploymentCredentials: {},
+    bootstrapSshCredentialPath: undefined,
+    bootstrapSshPublicKeyPath: undefined,
+    pullBootstrap: false,
+    pullDeployments: false,
+    pullMigrations: false,
+    lifecycleProfilePath: undefined,
+    bootstrapTargetTelemetryEndpoint: undefined,
+    repository: undefined,
+    bootstrapBundlePath: undefined,
+    bootstrapBundleManifestPath: undefined
+  }).replace("Description=ForgeZero node agent", "Description=ForgeZero candidate node agent");
+}
 var renderOperation = (operation) => {
   if (operation.kind === "commands")
     return operation.commands.map(({ argv: argv2 }) => argv2.join(" ")).join(`
@@ -3506,6 +3709,7 @@ function planProvision(options) {
     auxiliaryUnits: [
       { path: AGENT_SOCKET_UNIT_PATH, unit: agentSocketUnit(options) },
       { path: AGENT_SOCKET_PROXY_UNIT_PATH, unit: agentSocketProxyUnit(options) },
+      { path: AGENT_CANDIDATE_UNIT_PATH, unit: agentCandidateUnit(options) },
       { path: AGENT_UPDATE_HELPER_UNIT_PATH, unit: agentUpdateHelperUnit(options) },
       ...options.enforceEgress ? [
         { path: AGENT_EGRESS_UNIT_PATH, unit: agentEgressUnit(options) }
@@ -3647,8 +3851,11 @@ export {
   agentUnit,
   agentSocketUnit,
   agentSocketProxyUnit,
+  agentRoutingSocketPath,
   agentEnrolmentUnit,
   agentEgressUnit,
+  agentCandidateUnit,
+  agentCandidateSocketPath,
   agentBackendSocketPath,
   WARP_SERVICE_DROP_IN_PATH,
   WARP_CONFIG_UNIT_PATH,
@@ -3667,5 +3874,6 @@ export {
   APPLICATION_RUNTIME_USER,
   AGENT_SOCKET_UNIT_PATH,
   AGENT_SOCKET_PROXY_UNIT_PATH,
-  AGENT_EGRESS_UNIT_PATH
+  AGENT_EGRESS_UNIT_PATH,
+  AGENT_CANDIDATE_UNIT_PATH
 };