@forgezero/agent 0.1.85 → 0.1.87

package/dist/fz-agent.js

@@ -3,9 +3,9 @@
 
 // src/index.ts
 import { randomBytes as randomBytes7 } from "crypto";
-import { readFileSync as readFileSync20, writeFileSync as writeFileSync18, existsSync as existsSync22, mkdirSync as mkdirSync18, chmodSync as chmodSync18, lstatSync as lstatSync9, statfsSync as statfsSync3 } from "fs";
+import { readFileSync as readFileSync20, writeFileSync as writeFileSync18, existsSync as existsSync23, mkdirSync as mkdirSync18, chmodSync as chmodSync19, lstatSync as lstatSync10, statfsSync as statfsSync3 } from "fs";
 import { cpus as cpus2, totalmem as totalmem2 } from "os";
-import { dirname as dirname14, join as join12 } from "path";
+import { dirname as dirname16, join as join12 } from "path";
 
 // ../access/dist/security.js
 var HEX = Array.from({ length: 256 }, (_, index) => index.toString(16).padStart(2, "0"));
@@ -4201,7 +4201,16 @@ var DEFAULT_SOCKET = "/run/forgezero/vault.sock";
 
 // src/socket.ts
 import { createServer } from "net";
-import { chmodSync, existsSync, unlinkSync } from "fs";
+import {
+  existsSync,
+  chmodSync,
+  lstatSync,
+  readlinkSync,
+  renameSync,
+  symlinkSync,
+  unlinkSync
+} from "fs";
+import { basename, dirname } from "path";
 
 // src/cache.ts
 class CacheError extends Error {
@@ -4326,9 +4335,11 @@ function createSecretCache(options) {
 // src/signed-node-http.ts
 class SignedNodeHttpError extends Error {
   status;
-  constructor(status, message) {
+  code;
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code;
     this.name = "SignedNodeHttpError";
   }
 }
@@ -4375,7 +4386,7 @@ async function postSignedNode(options, path, body) {
   if (!response.ok) {
     const failure = payload;
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
-    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
+    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`, failure?.error?.code);
   }
   try {
     return await openResponse(recipient.secretKey, signature, payload);
@@ -4413,8 +4424,17 @@ function tenantNodeApiUrl(apiUrl, tenantSlug) {
   return url.toString().replace(/\/$/, "");
 }
 function createNodeVaultCache(options) {
-  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body);
-  return createSecretCache({
+  let cache;
+  const post = async (operation, body) => {
+    try {
+      return await postSignedNode(options, `v1/node/vault/${operation}`, body);
+    } catch (cause) {
+      if (cause instanceof SignedNodeHttpError && cause.code === "VAULT_API_ONLY")
+        cache?.clear();
+      throw cause;
+    }
+  };
+  cache = createSecretCache({
     ttlMs: options.ttlMs,
     maxStaleMs: options.maxStaleMs,
     list: async () => {
@@ -4443,6 +4463,7 @@ function createNodeVaultCache(options) {
       };
     }
   });
+  return cache;
 }
 function startNodeVaultSync(cache, options = {}) {
   const interval = Math.max(1000, options.intervalMs ?? 30000);
@@ -4483,6 +4504,32 @@ function handleApplicationRequest(options, request) {
   return handleRequest(options, request);
 }
 var MAX_LINE_BYTES = 64 * 1024;
+function ensureAgentSocketRoute(routePath, activePath) {
+  const target = basename(activePath);
+  if (dirname(routePath) !== dirname(activePath) || target.includes("/") || target === "." || target === "..") {
+    throw new Error("agent socket route and active backend must share one runtime directory");
+  }
+  try {
+    if (lstatSync(routePath).isSymbolicLink()) {
+      const current = readlinkSync(routePath);
+      if (current === target || existsSync(`${dirname(routePath)}/${current}`))
+        return;
+    } else
+      throw new Error("agent socket route must be a symbolic link");
+  } catch (cause) {
+    if (cause.code !== "ENOENT")
+      throw cause;
+  }
+  const next = `${routePath}.${process.pid}.next`;
+  try {
+    symlinkSync(target, next);
+    renameSync(next, routePath);
+  } finally {
+    try {
+      unlinkSync(next);
+    } catch {}
+  }
+}
 function handleRequest(options, request) {
   switch (request?.op) {
     case "identity":
@@ -4641,9 +4688,9 @@ function safeOp(line) {
 }
 
 // src/deployment.ts
-import { chmodSync as chmodSync4, existsSync as existsSync4, lstatSync as lstatSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync as renameSync3, statfsSync, writeFileSync as writeFileSync3 } from "fs";
+import { chmodSync as chmodSync4, existsSync as existsSync4, lstatSync as lstatSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync as renameSync4, statfsSync, writeFileSync as writeFileSync3 } from "fs";
 import { createHash as createHash5, randomUUID } from "crypto";
-import { dirname as dirname2, isAbsolute as isAbsolute2, join as join2 } from "path";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join2 } from "path";
 
 // ../runtime/dist/queue.js
 class QueueStoppedError extends Error {
@@ -4958,15 +5005,15 @@ import {
   mkdtempSync,
   mkdirSync,
   readFileSync,
-  renameSync,
+  renameSync as renameSync2,
   rmSync,
   statSync,
-  symlinkSync,
+  symlinkSync as symlinkSync2,
   unlinkSync as unlinkSync2,
   writeFileSync
 } from "fs";
 import { tmpdir } from "os";
-import { dirname, join } from "path";
+import { dirname as dirname2, join } from "path";
 var PINNED_BUN_VERSION = "1.3.14";
 var BUN_RELEASE_SHA256 = "951ee2aee855f08595aeec6225226a298d3fea83a3dcd6465c09cbccdf7e848f";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
@@ -5176,7 +5223,7 @@ var writeOwnedPolicy = (pathValue, content, mode = 420) => {
       throw new Error(`refusing to overwrite non-ForgeZero policy at ${pathValue}`);
     return;
   }
-  mkdirSync(dirname(pathValue), { recursive: true, mode: 493 });
+  mkdirSync(dirname2(pathValue), { recursive: true, mode: 493 });
   writeFileSync(pathValue, content, { mode, flag: "wx" });
 };
 var installContainerdRuntime = async (directory, osVersion) => {
@@ -5254,7 +5301,7 @@ var installKataRuntime = async (directory) => {
   try {
     unlinkSync2("/usr/local/bin/containerd-shim-kata-v2");
   } catch {}
-  symlinkSync("/opt/kata/bin/containerd-shim-kata-v2", "/usr/local/bin/containerd-shim-kata-v2");
+  symlinkSync2("/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 (!existsSync2(CONTAINERD_CONFIG_PATH) || ![base, kata].includes(readFileSync(CONTAINERD_CONFIG_PATH, "utf8"))) {
@@ -5395,11 +5442,11 @@ async function executeSoftwareOperation(operation) {
       mkdirSync("/usr/local/lib/forgezero/runtime", { recursive: true, mode: 493 });
       copyFileSync(join(unpacked, "bun-linux-x64", "bun"), "/usr/local/lib/forgezero/runtime/bun.next");
       chmodSync2("/usr/local/lib/forgezero/runtime/bun.next", 493);
-      renameSync("/usr/local/lib/forgezero/runtime/bun.next", "/usr/local/lib/forgezero/runtime/bun");
+      renameSync2("/usr/local/lib/forgezero/runtime/bun.next", "/usr/local/lib/forgezero/runtime/bun");
       try {
         unlinkSync2("/usr/local/bin/bun");
       } catch {}
-      symlinkSync("/usr/local/lib/forgezero/runtime/bun", "/usr/local/bin/bun");
+      symlinkSync2("/usr/local/lib/forgezero/runtime/bun", "/usr/local/bin/bun");
       return { exitCode: 0, output: "" };
     }
     if (software === "cloudflared") {
@@ -7766,10 +7813,10 @@ import {
   chmodSync as chmodSync3,
   createReadStream as createReadStream2,
   existsSync as existsSync3,
-  lstatSync,
+  lstatSync as lstatSync2,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync2,
-  renameSync as renameSync2,
+  renameSync as renameSync3,
   rmSync as rmSync2,
   writeFileSync as writeFileSync2
 } from "fs";
@@ -7865,13 +7912,13 @@ function persistCapacityCalibration(args) {
     throw new DeploymentError("PIPELINE_FAILED", "capacity evidence directory must be an absolute Agent-owned path");
   }
   if (!existsSync4(args.directory)) {
-    const parent = lstatSync2(dirname2(args.directory));
+    const parent = lstatSync3(dirname3(args.directory));
     if (!parent.isDirectory() || parent.isSymbolicLink()) {
       throw new DeploymentError("PIPELINE_FAILED", "capacity evidence parent must be a real Agent-owned directory");
     }
     mkdirSync3(args.directory, { mode: 448 });
   }
-  const stats = lstatSync2(args.directory);
+  const stats = lstatSync3(args.directory);
   if (!stats.isDirectory() || stats.isSymbolicLink()) {
     throw new DeploymentError("PIPELINE_FAILED", "capacity evidence directory must be a real Agent-owned directory");
   }
@@ -7894,7 +7941,7 @@ function persistCapacityCalibration(args) {
   }, null, 2)}
 `, { mode: 384, flag: "wx" });
   chmodSync4(next, 384);
-  renameSync3(next, path2);
+  renameSync4(next, path2);
   return path2;
 }
 function createDeploymentManager(options) {
@@ -7929,10 +7976,10 @@ function createDeploymentManager(options) {
     }
     if (existsSync4(knownHostsPath) && readFileSync3(knownHostsPath, "utf8") === content)
       return;
-    mkdirSync3(dirname2(knownHostsPath), { recursive: true, mode: 448 });
+    mkdirSync3(dirname3(knownHostsPath), { recursive: true, mode: 448 });
     const next = `${knownHostsPath}.${process.pid}.${randomUUID()}.next`;
     writeFileSync3(next, content, { mode: 384, flag: "wx" });
-    renameSync3(next, knownHostsPath);
+    renameSync4(next, knownHostsPath);
     chmodSync4(knownHostsPath, 384);
   };
   const gitBaseEnvironment = () => ({
@@ -8058,7 +8105,7 @@ function createDeploymentManager(options) {
     if (bootstrapBundle) {
       let metadata;
       try {
-        metadata = lstatSync2(bootstrapBundle.path);
+        metadata = lstatSync3(bootstrapBundle.path);
       } catch {
         throw new DeploymentError("SOURCE_FAILED", "The attended bootstrap bundle is missing.");
       }
@@ -8346,7 +8393,7 @@ function createDeploymentManager(options) {
           const component2 = plan.spec.components[String(resolved.component ?? "")];
           const mounts = component2?.kind === "database" ? [component2.storage] : component2?.storage ?? [];
           for (const mount of mounts) {
-            const candidate = existsSync4(mount.path) ? mount.path : dirname2(mount.path);
+            const candidate = existsSync4(mount.path) ? mount.path : dirname3(mount.path);
             const stats = statfsSync(candidate);
             const freePercent = Number(stats.bavail) / Number(stats.blocks) * 100;
             const minimum = mount.class === "ephemeral" ? 0 : mount.minimumFreePercent ?? 0;
@@ -8922,12 +8969,12 @@ import {
   existsSync as existsSync6,
   mkdirSync as mkdirSync4,
   readFileSync as readFileSync4,
-  renameSync as renameSync4,
+  renameSync as renameSync5,
   statSync as statSync2,
   unlinkSync as unlinkSync4,
   writeFileSync as writeFileSync4
 } from "fs";
-import { dirname as dirname3 } from "path";
+import { dirname as dirname4 } from "path";
 function privateNetworkAttachmentFromEnvironment(env = process.env) {
   const values = {
     accountId: env.FZ_CF_ACCOUNT_ID?.trim() ?? "",
@@ -8973,12 +9020,12 @@ function loadGuestBinding(path2, expectedNodeKey) {
   return parsed;
 }
 function persistGuestBinding(path2, binding) {
-  mkdirSync4(dirname3(path2), { recursive: true, mode: 448 });
+  mkdirSync4(dirname4(path2), { recursive: true, mode: 448 });
   const temporary = `${path2}.next`;
   writeFileSync4(temporary, `${JSON.stringify(binding)}
 `, { mode: 384 });
   chmodSync6(temporary, 384);
-  renameSync4(temporary, path2);
+  renameSync5(temporary, path2);
 }
 async function enrolGuestIdentity(options) {
   const token = options.token?.trim() ?? (options.tokenPath ? readFileSync4(options.tokenPath, "utf8").trim() : "");
@@ -9331,7 +9378,7 @@ async function writeAndCloseProcessInput(input, value) {
 }
 
 // src/version.ts
-var VERSION2 = "0.1.85";
+var VERSION2 = "0.1.87";
 
 // src/ssh-bootstrap.ts
 class SshBootstrapError extends Error {
@@ -10050,7 +10097,7 @@ import {
   unlinkSync as unlinkSync5,
   writeFileSync as writeFileSync6
 } from "fs";
-import { dirname as dirname4, isAbsolute as isAbsolute3, join as join4 } from "path";
+import { dirname as dirname5, isAbsolute as isAbsolute3, join as join4 } from "path";
 import { isIP as isIP2 } from "net";
 
 // src/compute.ts
@@ -10599,7 +10646,7 @@ async function provisionMetalGuest(profile, claim, exec) {
   }
   const service = `forgezero-guest@${name}.service`;
   const unitPath = join4(profile.unitDir, service);
-  mkdirSync5(dirname4(unitPath), { recursive: true });
+  mkdirSync5(dirname5(unitPath), { recursive: true });
   writeFileSync6(unitPath, guestUnit(spec), { mode: 420 });
   await checked2(exec, ["systemctl", "daemon-reload"]);
   if (prior?.phase === "running") {
@@ -11567,7 +11614,7 @@ function requestLifecycleAction(claim, socketPath = DEFAULT_LIFECYCLE_HELPER_SOC
 }
 
 // src/warp-config.ts
-import { chmodSync as chmodSync11, mkdirSync as mkdirSync7, renameSync as renameSync5, symlinkSync as symlinkSync2, unlinkSync as unlinkSync9, writeFileSync as writeFileSync8 } from "fs";
+import { chmodSync as chmodSync11, mkdirSync as mkdirSync7, renameSync as renameSync6, symlinkSync as symlinkSync3, unlinkSync as unlinkSync9, writeFileSync as writeFileSync8 } from "fs";
 var xml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
 function renderWarpMdm(options) {
   if (!/^[a-z0-9][a-z0-9-]{0,62}$/i.test(options.organization))
@@ -11593,14 +11640,14 @@ function materializeWarpMdm(options) {
   const next = `${runtimePath}.next`;
   writeFileSync8(next, renderWarpMdm(options), { mode: 384 });
   chmodSync11(next, 384);
-  renameSync5(next, runtimePath);
+  renameSync6(next, runtimePath);
   try {
     unlinkSync9(servicePath);
   } catch (cause) {
     if (cause.code !== "ENOENT")
       throw cause;
   }
-  symlinkSync2(runtimePath, servicePath);
+  symlinkSync3(runtimePath, servicePath);
   return { runtimePath, servicePath };
 }
 
@@ -11657,14 +11704,15 @@ import {
   mkdirSync as mkdirSync8,
   openSync as openSync2,
   readFileSync as readFileSync9,
-  readlinkSync,
-  renameSync as renameSync6,
+  readlinkSync as readlinkSync2,
+  renameSync as renameSync7,
   rmSync as rmSync5,
-  symlinkSync as symlinkSync3,
+  symlinkSync as symlinkSync4,
   writeFileSync as writeFileSync9
 } from "fs";
-import { dirname as dirname5, join as join7, resolve as resolve2 } from "path";
+import { dirname as dirname6, join as join7, resolve as resolve2 } from "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 VERSION3 = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
@@ -11685,7 +11733,7 @@ var syncReleaseDirectory = (directory) => {
     join7(directory, "dist", "fz-git-ssh.js"),
     join7(directory, "dist"),
     directory,
-    dirname5(directory)
+    dirname6(directory)
   ])
     syncPath(path2);
 };
@@ -11807,19 +11855,19 @@ async function stageAgentRelease(releaseInput, options) {
         args: ["-xOzf", archive, member]
       }, `agent update extraction of ${member}`);
       const destination = join7(unpacked, relative);
-      mkdirSync8(dirname5(destination), { recursive: true, mode: 448 });
+      mkdirSync8(dirname6(destination), { recursive: true, mode: 448 });
       writeFileSync9(destination, extracted.output, { mode: 384, flag: "wx" });
     }
     await validateReleaseDirectory(unpacked, release, run2);
     if (!existsSync12(finalDirectory)) {
-      renameSync6(unpacked, finalDirectory);
+      renameSync7(unpacked, finalDirectory);
       syncReleaseDirectory(finalDirectory);
     } else
       await validateReleaseDirectory(finalDirectory, release, run2);
     if (!existsSync12(currentLink)) {
       throw new Error("agent update requires an active immutable release to roll back to");
     }
-    const previousTarget = readlinkSync(currentLink);
+    const previousTarget = readlinkSync2(currentLink);
     if (previousTarget !== join7("versions", options.currentVersion)) {
       throw new Error("agent update current release does not match the running version");
     }
@@ -11839,43 +11887,116 @@ async function stageAgentRelease(releaseInput, options) {
   }
 }
 function selectAgentRelease(staged) {
-  const next = join7(dirname5(staged.currentLink), `.current.${randomUUID2()}.next`);
+  const next = join7(dirname6(staged.currentLink), `.current.${randomUUID2()}.next`);
   try {
-    symlinkSync3(staged.nextTarget, next);
-    renameSync6(next, staged.currentLink);
-    syncPath(dirname5(staged.currentLink));
+    symlinkSync4(staged.nextTarget, next);
+    renameSync7(next, staged.currentLink);
+    syncPath(dirname6(staged.currentLink));
   } finally {
     rmSync5(next, { force: true });
   }
 }
 function restoreAgentRelease(staged) {
-  const next = join7(dirname5(staged.currentLink), `.current.${randomUUID2()}.rollback`);
+  const next = join7(dirname6(staged.currentLink), `.current.${randomUUID2()}.rollback`);
+  try {
+    symlinkSync4(staged.previousTarget, next);
+    renameSync7(next, staged.currentLink);
+    syncPath(dirname6(staged.currentLink));
+  } finally {
+    rmSync5(next, { force: true });
+  }
+}
+function selectAgentCandidate(staged) {
+  const link = join7(dirname6(staged.currentLink), "candidate");
+  const next = `${link}.${randomUUID2()}.next`;
   try {
-    symlinkSync3(staged.previousTarget, next);
-    renameSync6(next, staged.currentLink);
-    syncPath(dirname5(staged.currentLink));
+    symlinkSync4(staged.nextTarget, next);
+    renameSync7(next, link);
+    syncPath(dirname6(link));
   } finally {
     rmSync5(next, { force: true });
   }
 }
+function clearAgentCandidate(root = DEFAULT_AGENT_RELEASE_ROOT) {
+  rmSync5(join7(resolve2(root), "candidate"), { force: true });
+}
 
 // src/agent-update-helper.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import {
-  chmodSync as chmodSync13,
+  chmodSync as chmodSync14,
   closeSync as closeSync3,
-  existsSync as existsSync13,
+  existsSync as existsSync14,
   fsyncSync as fsyncSync2,
   mkdirSync as mkdirSync9,
   openSync as openSync3,
   readFileSync as readFileSync10,
-  renameSync as renameSync7,
-  rmSync as rmSync6,
-  unlinkSync as unlinkSync10,
+  renameSync as renameSync9,
+  rmSync as rmSync7,
+  unlinkSync as unlinkSync11,
   writeFileSync as writeFileSync10
 } from "fs";
+import { connect as connect6, createServer as createServer7 } from "net";
+import { dirname as dirname8, join as join8, resolve as resolve3 } from "path";
+
+// src/agent-handover.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import { chmodSync as chmodSync13, existsSync as existsSync13, renameSync as renameSync8, rmSync as rmSync6, symlinkSync as symlinkSync5, unlinkSync as unlinkSync10 } from "fs";
+import { basename as basename2, dirname as dirname7 } from "path";
 import { connect as connect5, createServer as createServer6 } from "net";
-import { dirname as dirname6, join as join8, resolve as resolve3 } from "path";
+var DEFAULT_AGENT_CANDIDATE_READY_SOCKET = "/run/forgezero/candidate-ready.sock";
+function switchAgentSocketRoute(route, backend) {
+  if (dirname7(route) !== dirname7(backend))
+    throw new Error("Agent handover sockets must share one runtime directory");
+  const target2 = basename2(backend);
+  const next = `${route}.${randomUUID3()}.next`;
+  try {
+    symlinkSync5(target2, next);
+    renameSync8(next, route);
+  } finally {
+    rmSync6(next, { force: true });
+  }
+}
+function startAgentCandidateReady(ready, socketPath = DEFAULT_AGENT_CANDIDATE_READY_SOCKET) {
+  if (existsSync13(socketPath))
+    unlinkSync10(socketPath);
+  const server = createServer6((socket) => socket.end(`${JSON.stringify(ready)}
+`));
+  server.listen(socketPath, () => chmodSync13(socketPath, 432));
+  return server;
+}
+function probeAgentCandidate(expected, socketPath = DEFAULT_AGENT_CANDIDATE_READY_SOCKET, timeoutMs = 5000) {
+  return new Promise((resolve3) => {
+    const socket = connect5(socketPath);
+    let buffer = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve3(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 && typeof value.nodeKey === "string" && typeof value.bound === "boolean" && ["ready", "partial", "unavailable", "unbound"].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";
@@ -11970,13 +12091,13 @@ function validateJournal(value, root) {
   return journal;
 }
 function readJournal(path2, root) {
-  if (!existsSync13(path2))
+  if (!existsSync14(path2))
     return;
   return validateJournal(JSON.parse(readFileSync10(path2, "utf8")), root);
 }
 function writeAtomic(path2, value, mode) {
-  mkdirSync9(dirname6(path2), { recursive: true, mode: 493 });
-  const next = `${path2}.${randomUUID3()}.next`;
+  mkdirSync9(dirname8(path2), { recursive: true, mode: 493 });
+  const next = `${path2}.${randomUUID4()}.next`;
   let file;
   try {
     file = openSync3(next, "wx", mode);
@@ -11985,8 +12106,8 @@ function writeAtomic(path2, value, mode) {
     fsyncSync2(file);
     closeSync3(file);
     file = undefined;
-    renameSync7(next, path2);
-    const directory = openSync3(dirname6(path2), "r");
+    renameSync9(next, path2);
+    const directory = openSync3(dirname8(path2), "r");
     try {
       fsyncSync2(directory);
     } finally {
@@ -11995,7 +12116,7 @@ function writeAtomic(path2, value, mode) {
   } finally {
     if (file !== undefined)
       closeSync3(file);
-    rmSync6(next, { force: true });
+    rmSync7(next, { force: true });
   }
 }
 var publicReceipt = (journal) => {
@@ -12028,7 +12149,7 @@ function writeUpdateState(journalPath, receiptPath, journal) {
 }
 function readAgentUpdateReceipt(path2 = AGENT_UPDATE_RECEIPT) {
   try {
-    if (!existsSync13(path2))
+    if (!existsSync14(path2))
       return;
     return validateReceipt(JSON.parse(readFileSync10(path2, "utf8")));
   } catch {
@@ -12068,10 +12189,32 @@ var restartAgent = async (target2, run2) => {
     throw new Error(`systemd could not restart ${service}`);
   }
 };
+var candidateUnit = (target2) => target2 === "compute" ? "forgezero-agent-candidate.service" : "forgezero-metal-agent-candidate.service";
+var startCandidate = async (staged, target2, run2, probe = (expected) => probeAgentCandidate(expected, DEFAULT_AGENT_CANDIDATE_READY_SOCKET)) => {
+  selectAgentCandidate(staged);
+  if (!await runOk(run2, "/usr/bin/systemctl", ["restart", candidateUnit(target2)])) {
+    clearAgentCandidate(dirname8(staged.currentLink));
+    throw new Error(`systemd could not start ${candidateUnit(target2)}`);
+  }
+  if (!await probe({ version: staged.version })) {
+    await run2({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target2)] });
+    clearAgentCandidate(dirname8(staged.currentLink));
+    throw new Error("the candidate Agent did not prove its identity and durable state");
+  }
+};
+var stopCandidate = async (staged, target2, run2) => {
+  await run2({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target2)] });
+  clearAgentCandidate(dirname8(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 = (target2, run2) => target2 === "compute" ? () => probeAgentSocket() : async () => await runOk(run2, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-agent.service"]) && await runOk(run2, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-helper.service"]);
 function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
   return new Promise((resolve4) => {
-    const socket = connect5(socketPath);
+    const socket = connect6(socketPath);
     let settled = false;
     let buffer = "";
     const finish = (value) => {
@@ -12104,12 +12247,13 @@ function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
 async function activateAgentRelease(staged, options = {}) {
   const run2 = options.run ?? runCommand;
   const target2 = options.target ?? "compute";
-  const probe = options.probe ?? targetProbe(target2, run2);
+  const paths = socketPaths(options.publicSocketPath);
+  const probe = options.probe ?? (target2 === "compute" ? () => probeAgentSocket(paths.active) : targetProbe(target2, run2));
   const now = options.now ?? Date.now;
   const journalPath = options.journalPath ?? AGENT_UPDATE_JOURNAL;
   const receiptPath = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
-  const previous = readJournal(journalPath, dirname6(staged.currentLink));
-  const attemptId = options.attemptId ?? randomUUID3();
+  const previous = readJournal(journalPath, dirname8(staged.currentLink));
+  const attemptId = options.attemptId ?? randomUUID4();
   if (!ATTEMPT_ID.test(attemptId))
     throw new Error("Agent update attempt ID is invalid");
   const startedAtTs = now();
@@ -12131,11 +12275,18 @@ async function activateAgentRelease(staged, options = {}) {
   writeUpdateState(journalPath, receiptPath, journal);
   let selectionAttempted = false;
   try {
+    if (!options.candidatePrepared)
+      await startCandidate(staged, target2, run2);
+    if (target2 === "compute")
+      switchAgentSocketRoute(paths.route, paths.candidate);
     selectionAttempted = true;
     selectAgentRelease(staged);
     await restartAgent(target2, run2);
     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 (target2 === "compute")
+      switchAgentSocketRoute(paths.route, paths.active);
+    await stopCandidate(staged, target2, run2);
     journal = { ...journal, outcome: "active", updatedAtTs: now(), rollbackHealthy: undefined };
     writeUpdateState(journalPath, receiptPath, journal);
     run2({
@@ -12153,10 +12304,13 @@ async function activateAgentRelease(staged, options = {}) {
         restored = true;
         await restartAgent(target2, run2);
         rollbackHealthy = await probe();
+        if (rollbackHealthy && target2 === "compute")
+          switchAgentSocketRoute(paths.route, paths.active);
       } catch {
         rollbackHealthy = false;
       }
     }
+    await stopCandidate(staged, target2, run2).catch(() => {});
     const failures = failureCount + 1;
     const updatedAtTs = now();
     journal = {
@@ -12176,28 +12330,38 @@ async function recoverInterruptedAgentUpdate(options = {}) {
   const root = resolve3(options.root ?? DEFAULT_AGENT_RELEASE_ROOT);
   const journalPath = options.journalPath ?? AGENT_UPDATE_JOURNAL;
   const receiptPath = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
+  const run2 = options.run ?? runCommand;
   const journal = readJournal(journalPath, root);
-  if (!journal)
+  if (!journal) {
+    for (const target2 of ["compute", "metal"]) {
+      await run2({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target2)] });
+    }
+    clearAgentCandidate(root);
     return;
+  }
   if (journal.outcome !== "activating") {
+    await stopCandidate(stagedFromJournal(journal, root), journal.target, run2).catch(() => {});
     writeAtomic(receiptPath, publicReceipt(journal), 416);
     return publicReceipt(journal);
   }
   const staged = stagedFromJournal(journal, root);
-  if (!existsSync13(join8(root, journal.previousTarget))) {
+  if (!existsSync14(join8(root, journal.previousTarget))) {
     throw new Error("Agent update rollback release is missing");
   }
-  const run2 = options.run ?? runCommand;
-  const probe = options.probe ?? targetProbe(journal.target, run2);
+  const paths = socketPaths(options.publicSocketPath);
+  const probe = options.probe ?? (journal.target === "compute" ? () => probeAgentSocket(paths.active) : targetProbe(journal.target, run2));
   restoreAgentRelease(staged);
   let rollbackHealthy = false;
   let failureMessage = "activation was interrupted before its health verdict became durable";
   try {
     await restartAgent(journal.target, run2);
     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, run2).catch(() => {});
   const failures = journal.failureCount + 1;
   const updatedAtTs = (options.now ?? Date.now)();
   const recovered = {
@@ -12214,15 +12378,23 @@ async function recoverInterruptedAgentUpdate(options = {}) {
 }
 function startAgentUpdateHelper(options = {}) {
   const socketPath = options.socketPath ?? DEFAULT_AGENT_UPDATE_SOCKET;
-  if (existsSync13(socketPath))
-    unlinkSync10(socketPath);
-  mkdirSync9(dirname6(socketPath), { recursive: true, mode: 488 });
-  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  if (existsSync14(socketPath))
+    unlinkSync11(socketPath);
+  mkdirSync9(dirname8(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, target2, attemptId) => activateAgentRelease(staged, { target: target2, attemptId, journalPath, receiptPath, now: options.now }));
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const activate = options.activate ?? ((staged, target2, attemptId) => activateAgentRelease(staged, {
+    target: target2,
+    attemptId,
+    journalPath,
+    receiptPath,
+    now: options.now,
+    candidatePrepared: true
+  }));
   let busy = true;
+  let pending;
   let blocked;
   (options.recover ?? (() => recoverInterruptedAgentUpdate({
     root: releaseRoot,
@@ -12234,7 +12406,7 @@ function startAgentUpdateHelper(options = {}) {
   }).finally(() => {
     busy = false;
   });
-  const server = createServer6((socket) => {
+  const server = createServer7((socket) => {
     let buffer = "";
     socket.on("data", (chunk) => {
       buffer += chunk.toString("utf8");
@@ -12253,16 +12425,49 @@ 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 ?? randomUUID3();
+        const attemptId = request.attemptId ?? randomUUID4();
         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 (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)
@@ -12273,17 +12478,23 @@ function startAgentUpdateHelper(options = {}) {
           currentVersion: request.currentVersion,
           root: releaseRoot
         });
-        const response = { ok: true, status: "staged", version: staged.version, attemptId };
+        await startCandidate(staged, request.target, runCommand);
+        pending = { staged, target: request.target, attemptId };
+        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,
@@ -12295,12 +12506,12 @@ function startAgentUpdateHelper(options = {}) {
     });
     socket.on("error", () => socket.destroy());
   });
-  server.listen(socketPath, () => chmodSync13(socketPath, 432));
+  server.listen(socketPath, () => chmodSync14(socketPath, 432));
   return server;
 }
 function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, timeoutMs = 90000) {
   return new Promise((resolve4, reject) => {
-    const socket = connect5(socketPath, () => socket.write(`${JSON.stringify(request)}
+    const socket = connect6(socketPath, () => socket.write(`${JSON.stringify(request)}
 `));
     let buffer = "";
     socket.setTimeout(timeoutMs, () => {
@@ -12325,7 +12536,7 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 }
 
 // src/agent-heartbeat.ts
-import { existsSync as existsSync14, readFileSync as readFileSync11, statfsSync as statfsSync2 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync11, statfsSync as statfsSync2 } from "fs";
 import { cpus, freemem, loadavg, totalmem } from "os";
 function readAgentHostMetrics() {
   const filesystem = statfsSync2("/");
@@ -12370,7 +12581,7 @@ function observeAgentHost(version = VERSION2, mode = "enrolled", osRelease = rea
     runtimeCapabilities: {
       native: true,
       ociRunc: ubuntuX64,
-      kataQemuSnp: ubuntuX64 && osVersion === "26.04" && existsSync14("/dev/kvm") && existsSync14("/dev/sev") && enabled("/sys/module/kvm_amd/parameters/sev") && enabled("/sys/module/kvm_amd/parameters/sev_snp")
+      kataQemuSnp: ubuntuX64 && osVersion === "26.04" && existsSync15("/dev/kvm") && existsSync15("/dev/sev") && enabled("/sys/module/kvm_amd/parameters/sev") && enabled("/sys/module/kvm_amd/parameters/sev_snp")
     },
     capacity: {
       logicalCpu: Math.max(1, metrics.logicalCpu),
@@ -12422,18 +12633,24 @@ async function heartbeatAgentOnce(options) {
         });
         return response;
       }
-      let prepared = false;
+      let candidatePrepared = false;
+      let drained = false;
       try {
-        await options.prepareUpdate?.(release);
-        prepared = true;
+        const update2 = options.applyUpdate ?? ((phase, next, current2, attemptId) => requestAgentUpdate(phase === "prepare" ? { op: "prepare", target: options.updateTarget ?? "compute", release: next, currentVersion: current2, attemptId } : {
+          op: phase,
+          target: options.updateTarget ?? "compute",
+          currentVersion: current2,
+          targetVersion: next.version,
+          attemptId
+        }));
         const apply = async () => {
-          const applied = await (options.applyUpdate ?? ((next, current2, attemptId) => requestAgentUpdate({
-            op: "apply",
-            target: options.updateTarget ?? "compute",
-            release: next,
-            currentVersion: current2,
-            attemptId
-          })))(release, observation.version, desired.attemptId);
+          const prepared = await update2("prepare", release, observation.version, desired.attemptId);
+          if (!prepared.ok)
+            throw new AgentUpdateRefusedError(`agent update refused: ${prepared.error.message}`);
+          candidatePrepared = true;
+          await options.prepareUpdate?.(release);
+          drained = true;
+          const applied = await update2("commit", release, observation.version, desired.attemptId);
           if (!applied.ok)
             throw new AgentUpdateRefusedError(`agent update refused: ${applied.error.message}`);
           if (applied.attemptId !== desired.attemptId) {
@@ -12446,9 +12663,18 @@ async function heartbeatAgentOnce(options) {
         } else {
           await apply();
         }
-        options.onEvent?.("update-staged", { from: observation.version, to: release.version });
+        options.onEvent?.("update-active", { from: observation.version, to: release.version });
       } catch (cause) {
-        if (prepared)
+        if (candidatePrepared && !drained) {
+          await (options.applyUpdate ?? ((phase, next, current2, attemptId) => requestAgentUpdate({
+            op: phase,
+            target: options.updateTarget ?? "compute",
+            currentVersion: current2,
+            targetVersion: next.version,
+            attemptId
+          })))("abort", release, observation.version, desired.attemptId).catch(() => {});
+        }
+        if (drained)
           await options.recoverUpdate?.(cause);
         throw cause;
       }
@@ -12489,14 +12715,14 @@ function startAgentHeartbeat(options) {
 }
 
 // src/software-helper.ts
-import { chmodSync as chmodSync14, existsSync as existsSync17, mkdirSync as mkdirSync13, unlinkSync as unlinkSync11 } from "fs";
-import { connect as connect6, createServer as createServer7 } from "net";
-import { dirname as dirname10 } from "path";
+import { chmodSync as chmodSync15, existsSync as existsSync18, mkdirSync as mkdirSync13, unlinkSync as unlinkSync12 } from "fs";
+import { connect as connect7, createServer as createServer8 } from "net";
+import { dirname as dirname12 } from "path";
 
 // src/service-supervisor.ts
 import { createHash as createHash9 } from "crypto";
-import { existsSync as existsSync15, mkdirSync as mkdirSync10, readFileSync as readFileSync12, readdirSync as readdirSync2, realpathSync as realpathSync2, renameSync as renameSync8, rmSync as rmSync7, writeFileSync as writeFileSync11 } from "fs";
-import { dirname as dirname7, join as join9, resolve as resolve4, sep as sep2 } from "path";
+import { existsSync as existsSync16, mkdirSync as mkdirSync10, readFileSync as readFileSync12, readdirSync as readdirSync2, realpathSync as realpathSync2, renameSync as renameSync10, rmSync as rmSync8, writeFileSync as writeFileSync11 } from "fs";
+import { dirname as dirname9, join as join9, resolve as resolve4, sep as sep2 } from "path";
 var SERVICE_STATE_DIRECTORY = "/var/lib/forgezero/services";
 var SERVICE_CONFIG_DIRECTORY = "/etc/forgezero/services";
 var SERVICE_UNIT_DIRECTORY = "/etc/systemd/system";
@@ -12506,17 +12732,17 @@ var statePath = (id2) => `${SERVICE_STATE_DIRECTORY}/${id2}.json`;
 var within2 = (root, path2) => path2 === root || path2.startsWith(`${root}${sep2}`);
 var defaultHost = {
   write(path2, content, mode) {
-    mkdirSync10(dirname7(path2), { recursive: true, mode: 493 });
+    mkdirSync10(dirname9(path2), { recursive: true, mode: 493 });
     const next = `${path2}.next`;
     writeFileSync11(next, content, { mode });
-    renameSync8(next, path2);
+    renameSync10(next, path2);
   },
   read: (path2) => readFileSync12(path2, "utf8"),
-  exists: existsSync15,
-  list: (path2) => existsSync15(path2) ? readdirSync2(path2) : [],
+  exists: existsSync16,
+  list: (path2) => existsSync16(path2) ? readdirSync2(path2) : [],
   realpath: realpathSync2,
   mkdir: (path2, mode) => mkdirSync10(path2, { recursive: true, mode }),
-  remove: (path2) => rmSync7(path2, { force: true }),
+  remove: (path2) => rmSync8(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",
@@ -12712,20 +12938,20 @@ async function activateSupervisedService(request, host = defaultHost) {
 
 // src/container-supervisor.ts
 import { createHash as createHash10 } from "crypto";
-import { existsSync as existsSync16, mkdirSync as mkdirSync11, readFileSync as readFileSync13, readdirSync as readdirSync3, realpathSync as realpathSync3, renameSync as renameSync9, rmSync as rmSync8, writeFileSync as writeFileSync12 } from "fs";
-import { dirname as dirname8, resolve as resolve5, sep as sep3 } from "path";
+import { existsSync as existsSync17, mkdirSync as mkdirSync11, readFileSync as readFileSync13, readdirSync as readdirSync3, realpathSync as realpathSync3, renameSync as renameSync11, rmSync as rmSync9, writeFileSync as writeFileSync12 } from "fs";
+import { dirname as dirname10, resolve as resolve5, sep as sep3 } from "path";
 var defaultHost2 = {
   realpath: realpathSync3,
-  exists: existsSync16,
+  exists: existsSync17,
   read: (path2) => readFileSync13(path2, "utf8"),
   write(path2, content, mode) {
-    mkdirSync11(dirname8(path2), { recursive: true, mode: 493 });
+    mkdirSync11(dirname10(path2), { recursive: true, mode: 493 });
     const next = `${path2}.next`;
     writeFileSync12(next, content, { mode });
-    renameSync9(next, path2);
+    renameSync11(next, path2);
   },
-  remove: (path2) => rmSync8(path2, { force: true }),
-  list: (path2) => existsSync16(path2) ? readdirSync3(path2) : [],
+  remove: (path2) => rmSync9(path2, { force: true }),
+  list: (path2) => existsSync17(path2) ? readdirSync3(path2) : [],
   mkdir: (path2, mode) => mkdirSync11(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" } });
@@ -13014,9 +13240,9 @@ async function activateContainer(requestValue, host = defaultHost2) {
 
 // src/deployment-connectivity.ts
 import { createHash as createHash11 } from "crypto";
-import { mkdirSync as mkdirSync12, renameSync as renameSync10, writeFileSync as writeFileSync13 } from "fs";
+import { mkdirSync as mkdirSync12, renameSync as renameSync12, writeFileSync as writeFileSync13 } from "fs";
 import { createConnection as createConnection2 } from "net";
-import { dirname as dirname9 } from "path";
+import { dirname as dirname11 } from "path";
 var TOKEN2 = /^[A-Za-z0-9._-]{40,16384}$/;
 var UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
 var HOSTNAME2 = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
@@ -13029,7 +13255,7 @@ var checked7 = async (host, argv2, label) => {
   return result.output.trim();
 };
 async function sealWithSystemd(name, path2, value) {
-  mkdirSync12(dirname9(path2), { recursive: true, mode: 448 });
+  mkdirSync12(dirname11(path2), { recursive: true, mode: 448 });
   const next = `${path2}.next`;
   const child = Bun.spawn(["/usr/bin/systemd-creds", "encrypt", `--name=${name}`, "-", next], {
     stdin: "pipe",
@@ -13045,15 +13271,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)}`);
-  renameSync10(next, path2);
+  renameSync12(next, path2);
 }
 var defaultHost3 = {
   seal: sealWithSystemd,
   write(path2, content, mode) {
-    mkdirSync12(dirname9(path2), { recursive: true, mode: 493 });
+    mkdirSync12(dirname11(path2), { recursive: true, mode: 493 });
     const next = `${path2}.next`;
     writeFileSync13(next, content, { mode });
-    renameSync10(next, path2);
+    renameSync12(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" } });
@@ -13292,9 +13518,9 @@ var MAX_REQUEST_BYTES6 = 128 * 1024;
 var MAX_PENDING_REQUESTS = 128;
 function startSoftwareHelper(options = {}) {
   const socketPath = options.socketPath ?? DEFAULT_SOFTWARE_HELPER_SOCKET;
-  if (existsSync17(socketPath))
-    unlinkSync11(socketPath);
-  mkdirSync13(dirname10(socketPath), { recursive: true, mode: 488 });
+  if (existsSync18(socketPath))
+    unlinkSync12(socketPath);
+  mkdirSync13(dirname12(socketPath), { recursive: true, mode: 488 });
   const ensure = options.ensure ?? ensureSoftwareRequirements;
   const activate = options.activate ?? activateSupervisedService;
   const buildContainer = options.buildContainer ?? buildContainerImage;
@@ -13302,7 +13528,7 @@ function startSoftwareHelper(options = {}) {
   const applyConnectivity = options.applyConnectivity ?? applyDeploymentConnectivity;
   let tail = Promise.resolve();
   let pending = 0;
-  const server = createServer7((socket) => {
+  const server = createServer8((socket) => {
     let buffer = "";
     socket.on("data", (chunk) => {
       buffer += chunk.toString("utf8");
@@ -13381,12 +13607,12 @@ function startSoftwareHelper(options = {}) {
     });
     socket.on("error", () => socket.destroy());
   });
-  server.listen(socketPath, () => chmodSync14(socketPath, 432));
+  server.listen(socketPath, () => chmodSync15(socketPath, 432));
   return server;
 }
 function requestContainer(op, request, socketPath, timeoutMs) {
   return new Promise((resolve6, reject) => {
-    const socket = connect6(socketPath, () => socket.write(`${JSON.stringify({ op, request })}
+    const socket = connect7(socketPath, () => socket.write(`${JSON.stringify({ op, request })}
 `));
     let buffer = "";
     socket.setTimeout(timeoutMs, () => {
@@ -13424,7 +13650,7 @@ function requestDeploymentConnectivity(request, socketPath = DEFAULT_SOFTWARE_HE
 }
 function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 10 * 60000) {
   return new Promise((resolve6, reject) => {
-    const socket = connect6(socketPath, () => socket.write(`${JSON.stringify({ op: "activate-service", request })}
+    const socket = connect7(socketPath, () => socket.write(`${JSON.stringify({ op: "activate-service", request })}
 `));
     let buffer = "";
     socket.setTimeout(timeoutMs, () => {
@@ -13453,7 +13679,7 @@ function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_
 function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
   validateSoftwareRequirements(requirements);
   return new Promise((resolve6, reject) => {
-    const socket = connect6(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
+    const socket = connect7(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
 `));
     let buffer = "";
     socket.setTimeout(timeoutMs, () => {
@@ -14413,19 +14639,19 @@ var METAL_SYSTEMD_CREDENTIALS = {
 
 // src/platform-bootstrap-runtime.ts
 import {
-  chmodSync as chmodSync15,
+  chmodSync as chmodSync16,
   chownSync,
   copyFileSync as copyFileSync2,
-  existsSync as existsSync18,
-  lstatSync as lstatSync3,
+  existsSync as existsSync19,
+  lstatSync as lstatSync4,
   mkdirSync as mkdirSync14,
   readFileSync as readFileSync14,
   readdirSync as readdirSync4,
   realpathSync as realpathSync5,
-  renameSync as renameSync11,
-  rmSync as rmSync9,
+  renameSync as renameSync13,
+  rmSync as rmSync10,
   statSync as statSync4,
-  symlinkSync as symlinkSync4,
+  symlinkSync as symlinkSync6,
   writeFileSync as writeFileSync14
 } from "fs";
 import { join as join10 } from "path";
@@ -14480,21 +14706,21 @@ var platformExec = async (argv2) => {
 };
 var replaceLink = (path2, target2) => {
   const pending = `${path2}.next`;
-  rmSync9(pending, { force: true });
+  rmSync10(pending, { force: true });
   if (!target2) {
-    rmSync9(path2, { force: true });
+    rmSync10(path2, { force: true });
     return;
   }
-  symlinkSync4(target2, pending);
-  renameSync11(pending, path2);
+  symlinkSync6(target2, pending);
+  renameSync13(pending, path2);
 };
 var secureRelease = (path2, uid, gid) => {
   const visit = (current2) => {
-    const metadata = lstatSync3(current2);
+    const metadata = lstatSync4(current2);
     if (metadata.isSymbolicLink())
       throw new Error("release contains a symbolic link");
     chownSync(current2, uid, gid);
-    chmodSync15(current2, metadata.isDirectory() ? 365 : 292);
+    chmodSync16(current2, metadata.isDirectory() ? 365 : 292);
     if (metadata.isDirectory())
       for (const name of readdirSync4(current2))
         visit(join10(current2, name));
@@ -14519,7 +14745,7 @@ async function activatePlatformRelease(config, requestedRelease, options = {}) {
   const slots = join10(normalized.root, "slots");
   mkdirSync14(slots, { recursive: true, mode: 493 });
   const slotFile = join10(normalized.root, ".forge-slot");
-  const previousSlot = existsSync18(slotFile) ? readFileSync14(slotFile, "utf8").trim() : undefined;
+  const previousSlot = existsSync19(slotFile) ? readFileSync14(slotFile, "utf8").trim() : undefined;
   const target2 = previousSlot === "blue" ? "green" : "blue";
   const port = target2 === "blue" ? normalized.bluePort : normalized.greenPort;
   const targetLink = join10(slots, target2);
@@ -14559,25 +14785,25 @@ async function activatePlatformRelease(config, requestedRelease, options = {}) {
   }
   const upstream = "/etc/nginx/conf.d/forgezero-upstream.conf";
   const backup = `${upstream}.forgezero-backup`;
-  if (existsSync18(upstream))
+  if (existsSync19(upstream))
     copyFileSync2(upstream, backup);
   else
-    rmSync9(backup, { force: true });
+    rmSync10(backup, { force: true });
   writeFileSync14(upstream, `upstream forgezero { server 127.0.0.1:${port}; }
 `, { mode: 420 });
   const test = await exec(["/usr/sbin/nginx", "-t"]);
   const reload = test.exitCode === 0 ? await exec(["/usr/sbin/nginx", "-s", "reload"]) : test;
   if (reload.exitCode !== 0) {
-    if (existsSync18(backup))
-      renameSync11(backup, upstream);
+    if (existsSync19(backup))
+      renameSync13(backup, upstream);
     else
-      rmSync9(upstream, { force: true });
+      rmSync10(upstream, { force: true });
     await exec(["/usr/sbin/nginx", "-t"]);
     await exec(["/usr/sbin/nginx", "-s", "reload"]);
     await stopTarget();
     throw new Error("nginx refused the promoted upstream");
   }
-  rmSync9(backup, { force: true });
+  rmSync10(backup, { force: true });
   writeFileSync14(slotFile, `${target2}
 `, { mode: 420 });
   if (previousSlot && previousSlot !== target2) {
@@ -14587,12 +14813,12 @@ async function activatePlatformRelease(config, requestedRelease, options = {}) {
   const old = readdirSync4(releases, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join10(releases, entry.name)).sort((left, right) => statSync4(right).mtimeMs - statSync4(left).mtimeMs).slice(normalized.keepReleases);
   for (const path2 of old)
     if (path2 !== release)
-      rmSync9(path2, { recursive: true, force: true });
+      rmSync10(path2, { recursive: true, force: true });
   return { release, slot: target2 };
 }
 
 // src/recovery-host.ts
-import { existsSync as existsSync19, readFileSync as readFileSync15, statSync as statSync5 } from "fs";
+import { existsSync as existsSync20, readFileSync as readFileSync15, statSync as statSync5 } from "fs";
 import { hostname } from "os";
 import { join as join11 } from "path";
 var execute2 = async (argv2) => {
@@ -14618,7 +14844,7 @@ var exactState = (path2, expected) => {
     throw new Error(`state mismatch: ${expected}`);
 };
 var nonEmpty = (path2) => {
-  if (!existsSync19(path2) || !statSync5(path2).isFile() || statSync5(path2).size < 1)
+  if (!existsSync20(path2) || !statSync5(path2).isFile() || statSync5(path2).size < 1)
     throw new Error(`required file missing: ${path2}`);
 };
 var option = (args, name) => {
@@ -14714,20 +14940,20 @@ async function runRecoveryHost(args, run2 = execute2) {
 }
 
 // src/platform-fleet-verification.ts
-import { lstatSync as lstatSync6 } from "fs";
+import { lstatSync as lstatSync7 } from "fs";
 
 // src/bootstrap.ts
 import {
-  chmodSync as chmodSync17,
-  existsSync as existsSync21,
-  lstatSync as lstatSync5,
+  chmodSync as chmodSync18,
+  existsSync as existsSync22,
+  lstatSync as lstatSync6,
   mkdirSync as mkdirSync16,
   readFileSync as readFileSync17,
-  renameSync as renameSync13,
-  rmSync as rmSync11,
+  renameSync as renameSync15,
+  rmSync as rmSync12,
   writeFileSync as writeFileSync16
 } from "fs";
-import { dirname as dirname12 } from "path";
+import { dirname as dirname14 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/provision.ts
@@ -14784,6 +15010,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";
@@ -14895,6 +15122,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
@@ -14939,13 +15167,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}
@@ -14966,12 +15192,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`);
@@ -15255,7 +15495,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}`,
@@ -15392,6 +15636,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(`
@@ -15527,6 +15791,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) }
@@ -15658,19 +15923,19 @@ function planProvision(options) {
 // src/cli/agent-install.ts
 import { randomBytes as randomBytes6 } from "crypto";
 import {
-  chmodSync as chmodSync16,
+  chmodSync as chmodSync17,
   copyFileSync as copyFileSync3,
-  existsSync as existsSync20,
-  lstatSync as lstatSync4,
+  existsSync as existsSync21,
+  lstatSync as lstatSync5,
   mkdirSync as mkdirSync15,
   readFileSync as readFileSync16,
   realpathSync as realpathSync6,
-  renameSync as renameSync12,
-  rmSync as rmSync10,
-  symlinkSync as symlinkSync5,
+  renameSync as renameSync14,
+  rmSync as rmSync11,
+  symlinkSync as symlinkSync7,
   writeFileSync as writeFileSync15
 } from "fs";
-import { dirname as dirname11 } from "path";
+import { dirname as dirname13 } from "path";
 async function readCapabilities(run2) {
   const answers = {};
   const checks = Object.entries(CAPABILITY_CHECKS);
@@ -15728,51 +15993,51 @@ var runProvisionOperation = async (operation) => {
   if (operation.kind === "install-runtime") {
     const release = `/opt/forgezero/agent/versions/${operation.version}`;
     mkdirSync15(`${release}/dist`, { recursive: true, mode: 493 });
-    mkdirSync15(dirname11(operation.binary), { recursive: true, mode: 493 });
+    mkdirSync15(dirname13(operation.binary), { recursive: true, mode: 493 });
     copyFileSync3(operation.source, `${release}/dist/fz-agent.js`);
-    chmodSync16(`${release}/dist/fz-agent.js`, 493);
-    const gitSshSource = `${dirname11(operation.source)}/fz-git-ssh.js`;
-    if (!existsSync20(gitSshSource))
+    chmodSync17(`${release}/dist/fz-agent.js`, 493);
+    const gitSshSource = `${dirname13(operation.source)}/fz-git-ssh.js`;
+    if (!existsSync21(gitSshSource))
       return { stdout: "packaged fz-git-ssh.js is missing", exitCode: 1 };
     copyFileSync3(gitSshSource, `${release}/dist/fz-git-ssh.js`);
-    chmodSync16(`${release}/dist/fz-git-ssh.js`, 493);
+    chmodSync17(`${release}/dist/fz-git-ssh.js`, 493);
     const pending = "/opt/forgezero/agent/current.next";
-    rmSync10(pending, { force: true });
-    symlinkSync5(`versions/${operation.version}`, pending);
-    renameSync12(pending, "/opt/forgezero/agent/current");
-    rmSync10(operation.binary, { force: true });
-    symlinkSync5("/opt/forgezero/agent/current/dist/fz-agent.js", operation.binary);
+    rmSync11(pending, { force: true });
+    symlinkSync7(`versions/${operation.version}`, pending);
+    renameSync14(pending, "/opt/forgezero/agent/current");
+    rmSync11(operation.binary, { force: true });
+    symlinkSync7("/opt/forgezero/agent/current/dist/fz-agent.js", operation.binary);
     const gitSshBinary = "/usr/local/lib/forgezero/agent/fz-git-ssh";
-    rmSync10(gitSshBinary, { force: true });
-    symlinkSync5("/opt/forgezero/agent/current/dist/fz-git-ssh.js", gitSshBinary);
+    rmSync11(gitSshBinary, { force: true });
+    symlinkSync7("/opt/forgezero/agent/current/dist/fz-git-ssh.js", gitSshBinary);
     return { stdout: "", exitCode: 0 };
   }
   if (operation.kind === "ensure-seed") {
-    if (existsSync20(operation.credential) && lstatSync4(operation.credential).size > 0)
+    if (existsSync21(operation.credential) && lstatSync5(operation.credential).size > 0)
       return { stdout: "", exitCode: 0 };
     const seed = randomBytes6(32).toString("base64url");
     const result = await fixed(["/usr/bin/systemd-creds", "encrypt", "--name=agent-seed", "-", operation.credential], seed);
     if (result.exitCode === 0)
-      chmodSync16(operation.credential, 256);
+      chmodSync17(operation.credential, 256);
     return result;
   }
   if (operation.kind === "ensure-git-identity") {
     const key = "/run/forgezero-git-deploy-key";
     const publicKey = `${key}.pub`;
     try {
-      if (!existsSync20(operation.credential) || lstatSync4(operation.credential).size < 1) {
-        rmSync10(key, { force: true });
-        rmSync10(publicKey, { force: true });
+      if (!existsSync21(operation.credential) || lstatSync5(operation.credential).size < 1) {
+        rmSync11(key, { force: true });
+        rmSync11(publicKey, { force: true });
         let result = await fixed(["/usr/bin/ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-C", "forgezero-compute", "-f", key]);
         if (result.exitCode !== 0)
           return result;
         result = await fixed(["/usr/bin/systemd-creds", "encrypt", "--name=git-deploy-key", key, operation.credential]);
         if (result.exitCode !== 0)
           return result;
-        chmodSync16(operation.credential, 256);
+        chmodSync17(operation.credential, 256);
       }
-      if (!existsSync20(operation.publicKey) || lstatSync4(operation.publicKey).size < 1) {
-        if (!existsSync20(key)) {
+      if (!existsSync21(operation.publicKey) || lstatSync5(operation.publicKey).size < 1) {
+        if (!existsSync21(key)) {
           const decrypted = await fixed(["/usr/bin/systemd-creds", "decrypt", "--name=git-deploy-key", operation.credential, key]);
           if (decrypted.exitCode !== 0)
             return decrypted;
@@ -15785,25 +16050,25 @@ var runProvisionOperation = async (operation) => {
       }
       return { stdout: "", exitCode: 0 };
     } finally {
-      rmSync10(key, { force: true });
-      rmSync10(publicKey, { force: true });
+      rmSync11(key, { force: true });
+      rmSync11(publicKey, { force: true });
     }
   }
   if (operation.kind === "ensure-bootstrap-ssh-identity") {
     const key = "/run/forgezero-bootstrap-ssh-key";
     const generatedPublicKey = `${key}.pub`;
     try {
-      if (!existsSync20(operation.credential) || lstatSync4(operation.credential).size < 1) {
-        rmSync10(key, { force: true });
-        rmSync10(generatedPublicKey, { force: true });
+      if (!existsSync21(operation.credential) || lstatSync5(operation.credential).size < 1) {
+        rmSync11(key, { force: true });
+        rmSync11(generatedPublicKey, { force: true });
         let result;
         if (operation.source) {
-          const source = existsSync20(operation.source) ? lstatSync4(operation.source) : undefined;
+          const source = existsSync21(operation.source) ? lstatSync5(operation.source) : undefined;
           if (!source?.isFile() || source.isSymbolicLink() || source.uid !== 0 || source.nlink !== 1 || (source.mode & 63) !== 0 || source.size < 32 || source.size > 16 * 1024) {
             return { stdout: "bootstrap SSH private-key source is missing or unsafe", exitCode: 1 };
           }
           copyFileSync3(operation.source, key);
-          chmodSync16(key, 384);
+          chmodSync17(key, 384);
         } else {
           result = await fixed(["/usr/bin/ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-C", "forgezero-bootstrap-runner", "-f", key]);
           if (result.exitCode !== 0)
@@ -15816,48 +16081,48 @@ var runProvisionOperation = async (operation) => {
         result = await fixed(["/usr/bin/systemd-creds", "encrypt", "--name=bootstrap-ssh-key", key, operation.credential]);
         if (result.exitCode !== 0)
           return result;
-        chmodSync16(operation.credential, 256);
+        chmodSync17(operation.credential, 256);
       }
-      if (!existsSync20(operation.publicKey) || lstatSync4(operation.publicKey).size < 1) {
-        if (!existsSync20(key)) {
+      if (!existsSync21(operation.publicKey) || lstatSync5(operation.publicKey).size < 1) {
+        if (!existsSync21(key)) {
           const decrypted = await fixed(["/usr/bin/systemd-creds", "decrypt", "--name=bootstrap-ssh-key", operation.credential, key]);
           if (decrypted.exitCode !== 0)
             return decrypted;
-          chmodSync16(key, 384);
+          chmodSync17(key, 384);
         }
         const derived = await fixed(["/usr/bin/ssh-keygen", "-y", "-f", key]);
         if (derived.exitCode !== 0 || !/^ssh-ed25519 [A-Za-z0-9+/]+={0,3}\s*$/.test(derived.stdout)) {
           return { stdout: "bootstrap SSH public key derivation failed", exitCode: 1 };
         }
-        mkdirSync15(dirname11(operation.publicKey), { recursive: true, mode: 493 });
+        mkdirSync15(dirname13(operation.publicKey), { recursive: true, mode: 493 });
         writeFileSync15(operation.publicKey, `${derived.stdout.trim()} forgezero-bootstrap-runner
 `, { mode: 292 });
-        chmodSync16(operation.publicKey, 292);
+        chmodSync17(operation.publicKey, 292);
       }
       if (operation.source)
-        rmSync10(operation.source, { force: true });
+        rmSync11(operation.source, { force: true });
       return { stdout: "", exitCode: 0 };
     } finally {
-      rmSync10(key, { force: true });
-      rmSync10(generatedPublicKey, { force: true });
+      rmSync11(key, { force: true });
+      rmSync11(generatedPublicKey, { force: true });
     }
   }
   if (operation.kind === "ensure-enrolment") {
-    if (existsSync20(operation.state) && lstatSync4(operation.state).size > 0 || existsSync20(operation.credential) && lstatSync4(operation.credential).size > 0)
+    if (existsSync21(operation.state) && lstatSync5(operation.state).size > 0 || existsSync21(operation.credential) && lstatSync5(operation.credential).size > 0)
       return { stdout: "", exitCode: 0 };
-    if (!existsSync20(operation.source))
+    if (!existsSync21(operation.source))
       return { stdout: "enrolment source is missing", exitCode: 1 };
     const result = await fixed(["/usr/bin/systemd-creds", "encrypt", "--name=enrol-token", operation.source, operation.credential]);
     if (result.exitCode === 0) {
-      chmodSync16(operation.credential, 256);
-      rmSync10(operation.source, { force: true });
+      chmodSync17(operation.credential, 256);
+      rmSync11(operation.source, { force: true });
     }
     return result;
   }
   if (operation.kind === "wait-socket") {
     for (let attempt = 0;attempt < operation.attempts; attempt += 1) {
       try {
-        if (lstatSync4(operation.path).isSocket())
+        if (lstatSync5(operation.path).isSocket())
           return { stdout: "", exitCode: 0 };
       } catch {}
       await Bun.sleep(operation.intervalMs);
@@ -15865,7 +16130,7 @@ var runProvisionOperation = async (operation) => {
     return { stdout: `socket did not become ready: ${operation.path}`, exitCode: 1 };
   }
   if (operation.kind === "verify-file")
-    return existsSync20(operation.path) && lstatSync4(operation.path).size > 0 ? { stdout: "", exitCode: 0 } : { stdout: "required file is empty", exitCode: 1 };
+    return existsSync21(operation.path) && lstatSync5(operation.path).size > 0 ? { stdout: "", exitCode: 0 } : { stdout: "required file is empty", exitCode: 1 };
   if (operation.kind === "verify-egress") {
     const active = await fixed(["/usr/bin/systemctl", "is-active", "forgezero-agent-egress.service"]);
     if (active.exitCode !== 0)
@@ -15899,7 +16164,7 @@ var runProvisionOperation = async (operation) => {
     const key = "/run/cloudflare-warp-key.gpg";
     writeFileSync15(key, new Uint8Array(await response.arrayBuffer()), { mode: 384 });
     let result = await fixed(["/usr/bin/gpg", "--batch", "--yes", "--dearmor", "-o", "/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg", key]);
-    rmSync10(key, { force: true });
+    rmSync11(key, { force: true });
     if (result.exitCode !== 0)
       return result;
     const codename = os.match(/^VERSION_CODENAME=(.+)$/m)?.[1]?.replace(/^"|"$/g, "");
@@ -15920,7 +16185,7 @@ async function localRunner(operation) {
   if (capability.kind === "version")
     return fixed(capability.argv);
   try {
-    const metadata = lstatSync4(capability.path);
+    const metadata = lstatSync5(capability.path);
     const present = capability.nodeType === "directory" ? metadata.isDirectory() : true;
     return { stdout: present ? `yes
 ` : `no
@@ -16218,19 +16483,19 @@ function localBootstrapHost() {
   };
   return {
     uid: () => process.getuid?.() ?? -1,
-    exists: existsSync21,
+    exists: existsSync22,
     read: (path2) => readFileSync17(path2, "utf8"),
     write(path2, content, mode) {
-      mkdirSync16(dirname12(path2), { recursive: true, mode: 493 });
+      mkdirSync16(dirname14(path2), { recursive: true, mode: 493 });
       const temporary = `${path2}.next.${process.pid}`;
       writeFileSync16(temporary, content, { mode });
-      chmodSync17(temporary, mode);
-      renameSync13(temporary, path2);
+      chmodSync18(temporary, mode);
+      renameSync15(temporary, path2);
     },
     mkdir: (path2, mode) => mkdirSync16(path2, { recursive: true, mode }),
-    remove: (path2) => rmSync11(path2, { force: true }),
+    remove: (path2) => rmSync12(path2, { force: true }),
     inspect(path2) {
-      const value = lstatSync5(path2);
+      const value = lstatSync6(path2);
       return { regular: value.isFile(), symbolic: value.isSymbolicLink(), uid: value.uid, mode: value.mode, links: value.nlink, size: value.size };
     },
     exec: execute3,
@@ -16251,9 +16516,9 @@ function localBootstrapHost() {
     },
     async installAgent(config, phase) {
       const capabilities = await readCapabilities(localRunner);
-      const hasBinding = existsSync21("/var/lib/forgezero/enrolment.json");
-      const hasEnrolCredential = existsSync21(ENROL_CREDENTIAL);
-      const initialBundle = config.kind === "platform" && !existsSync21(BOOTSTRAP_RELEASE_EVIDENCE) ? {
+      const hasBinding = existsSync22("/var/lib/forgezero/enrolment.json");
+      const hasEnrolCredential = existsSync22(ENROL_CREDENTIAL);
+      const initialBundle = config.kind === "platform" && !existsSync22(BOOTSTRAP_RELEASE_EVIDENCE) ? {
         path: config.bootstrapBundle.bundleFile,
         manifestPath: config.bootstrapBundle.manifestFile,
         manifest: parseBootstrapBundleManifest(JSON.parse(readFileSync17(config.bootstrapBundle.manifestFile, "utf8")))
@@ -16269,7 +16534,7 @@ function localBootstrapHost() {
           databaseHealthUrl: `http://${config.database.address}:8529/_api/version`,
           databasePorts: [8529]
         };
-        mkdirSync16(dirname12(LIFECYCLE_PROFILE), { recursive: true, mode: 493 });
+        mkdirSync16(dirname14(LIFECYCLE_PROFILE), { recursive: true, mode: 493 });
         writeFileSync16(LIFECYCLE_PROFILE, `${JSON.stringify(lifecycle, null, 2)}
 `, { mode: 256 });
       }
@@ -16280,7 +16545,7 @@ function localBootstrapHost() {
         initialBundle
       });
       for (const unit3 of [{ path: plan.unitPath, unit: plan.unit }, ...plan.auxiliaryUnits]) {
-        mkdirSync16(dirname12(unit3.path), { recursive: true, mode: 493 });
+        mkdirSync16(dirname14(unit3.path), { recursive: true, mode: 493 });
         writeFileSync16(unit3.path, unit3.unit, { mode: 420 });
       }
       await applyPlan(plan, localRunner);
@@ -16295,7 +16560,7 @@ var localRuntime = () => ({
   bootstrapStatus: () => bootstrapStatus(),
   characterDevice(path2) {
     try {
-      return lstatSync6(path2).isCharacterDevice();
+      return lstatSync7(path2).isCharacterDevice();
     } catch {
       return false;
     }
@@ -16334,9 +16599,9 @@ async function verifyPlatformFleetHost(expectedVersion, runtime = localRuntime()
 
 // src/community-rehearsal-host.ts
 import { createHash as createHash12 } from "crypto";
-import { lstatSync as lstatSync7, mkdirSync as mkdirSync17, readFileSync as readFileSync18, rmSync as rmSync12, symlinkSync as symlinkSync6, unlinkSync as unlinkSync12, writeFileSync as writeFileSync17 } from "fs";
+import { lstatSync as lstatSync8, mkdirSync as mkdirSync17, readFileSync as readFileSync18, rmSync as rmSync13, symlinkSync as symlinkSync8, unlinkSync as unlinkSync13, writeFileSync as writeFileSync17 } from "fs";
 import { isIP as isIP5 } from "net";
-import { dirname as dirname13 } from "path";
+import { dirname as dirname15 } from "path";
 var COMMUNITY_REHEARSAL_VERSION = "3.11.14";
 var COMMUNITY_REHEARSAL_ROOT = "/opt/forgezero-rehearsals/community-cluster-api";
 var COMMUNITY_DATABASE_ROOT = "/var/lib/forgezero-rehearsal-cluster";
@@ -16550,19 +16815,19 @@ async function exec(argv2, stdin) {
 async function applyOperations(operations) {
   for (const operation of operations) {
     if (operation.kind === "remove-tree")
-      rmSync12(operation.path, { recursive: true, force: true });
+      rmSync13(operation.path, { recursive: true, force: true });
     else if (operation.kind === "write") {
-      mkdirSync17(dirname13(operation.path), { recursive: true });
+      mkdirSync17(dirname15(operation.path), { recursive: true });
       writeFileSync17(operation.path, operation.content, { mode: operation.mode });
     } else if (operation.kind === "unlink") {
       try {
-        unlinkSync12(operation.path);
+        unlinkSync13(operation.path);
       } catch (cause) {
         if (cause.code !== "ENOENT")
           throw cause;
       }
     } else if (operation.kind === "symlink")
-      symlinkSync6(operation.target, operation.path);
+      symlinkSync8(operation.target, operation.path);
     else {
       const result = await exec(operation.argv, operation.stdin);
       if (!(operation.accepted ?? [0]).includes(result.exitCode))
@@ -16604,7 +16869,7 @@ async function runCommunityRehearsalHost(request) {
     return { ok: true, action: request.action, node: node.name };
   }
   if (request.action === "prepare") {
-    const metadata = lstatSync7(request.archivePath);
+    const metadata = lstatSync8(request.archivePath);
     if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size < 1 || metadata.size > 64 * 1024 * 1024 || createHash12("sha256").update(readFileSync18(request.archivePath)).digest("hex") !== request.archiveSha256) {
       throw new Error("community rehearsal archive is not the declared bounded release");
     }
@@ -16654,9 +16919,9 @@ async function runCommunityRehearsalHost(request) {
 }
 
 // src/supervised-app.ts
-import { lstatSync as lstatSync8, readFileSync as readFileSync19 } from "fs";
+import { lstatSync as lstatSync9, readFileSync as readFileSync19 } from "fs";
 function readConfig(path2) {
-  const stat = lstatSync8(path2);
+  const stat = lstatSync9(path2);
   if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== 0 || (stat.mode & 18) !== 0 || stat.size > 128 * 1024) {
     throw new Error("supervised app config is unsafe");
   }
@@ -16839,17 +17104,17 @@ function agentCommandArgs(args, command3) {
   return args.slice(index + 1);
 }
 function loadOrCreateSeed(path2) {
-  if (existsSync22(path2)) {
+  if (existsSync23(path2)) {
     const seed2 = new Uint8Array(Buffer.from(readFileSync20(path2, "utf8").trim(), "base64url"));
     if (seed2.length < 32) {
       throw new Error(`agent: the seed at ${path2} is too short to derive a key from.`);
     }
     return seed2;
   }
-  mkdirSync18(dirname14(path2), { recursive: true });
+  mkdirSync18(dirname16(path2), { recursive: true });
   const seed = new Uint8Array(randomBytes7(32));
   writeFileSync18(path2, Buffer.from(seed).toString("base64url"), { mode: 384 });
-  chmodSync18(path2, 384);
+  chmodSync19(path2, 384);
   return seed;
 }
 var DEFAULT_SOCKET_PATH = DEFAULT_SOCKET;
@@ -16878,7 +17143,7 @@ function loadSeedCredential(name = DEFAULT_SEED_CREDENTIAL, directory = process.
   if (!directory)
     throw new Error("agent: CREDENTIALS_DIRECTORY is missing; systemd did not load the node identity.");
   const path2 = `${directory}/${name}`;
-  if (!existsSync22(path2))
+  if (!existsSync23(path2))
     throw new Error(`agent: the systemd credential ${name} is missing at ${path2}.`);
   const seed = new Uint8Array(Buffer.from(readFileSync20(path2, "utf8").trim(), "base64url"));
   if (seed.length < 32)
@@ -17040,7 +17305,7 @@ if (import.meta.main) {
     if (args.length !== 1)
       throw new Error("project-release-check accepts no coordinates");
     for (const relative of ["src/index.ts", "bun.lock", "src/generated/shared/contract-manifest.json"]) {
-      const stat = lstatSync9(join12(process.cwd(), relative));
+      const stat = lstatSync10(join12(process.cwd(), relative));
       if (!stat.isFile() || stat.isSymbolicLink() || stat.size < 1) {
         throw new Error(`project release is missing ${relative}`);
       }
@@ -17379,9 +17644,9 @@ if (import.meta.main) {
         vcpu: cpus2().length,
         memoryGib: Math.max(1, Math.floor(totalmem2() / 1024 ** 3)),
         diskGib: Math.max(1, Math.floor(Number(filesystem.blocks) * Number(filesystem.bsize) / 1024 ** 3)),
-        kvm: existsSync22("/dev/kvm"),
-        snpHost: existsSync22("/dev/sev"),
-        helper: existsSync22(process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET)
+        kvm: existsSync23("/dev/kvm"),
+        snpHost: existsSync23("/dev/sev"),
+        helper: existsSync23(process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET)
       }
     };
     const envelope = signRequest(keys2, keys2.ed25519.publicKey, {
@@ -17408,6 +17673,19 @@ if (import.meta.main) {
     const keys2 = deriveKeysFromSeed(seed);
     seed.fill(0);
     const nodeKey2 = process.env.FZ_NODE_KEY ?? keys2.ed25519.publicKey;
+    if (process.env.FZ_AGENT_HANDOVER_CANDIDATE === "true") {
+      const ready = startAgentCandidateReady({
+        version: VERSION2,
+        nodeKey: nodeKey2,
+        bound: true,
+        vault: "unbound"
+      }, process.env.FZ_AGENT_HANDOVER_READY_SOCKET ?? DEFAULT_AGENT_CANDIDATE_READY_SOCKET);
+      console.log(`[metal-agent] candidate ${VERSION2} ready for atomic handover`);
+      const stop2 = () => ready.close(() => process.exit(0));
+      process.on("SIGTERM", stop2);
+      process.on("SIGINT", stop2);
+      await new Promise(() => {});
+    }
     const pull = startProvisioningPull({
       apiUrl: process.env.FZ_API,
       nodeKey: nodeKey2,
@@ -17416,9 +17694,9 @@ if (import.meta.main) {
       metalHostname: process.env.FZ_METAL_HOSTNAME,
       run: (claim) => requestMetalProvision(claim, process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET),
       metalPreflight: () => ({
-        snpHost: existsSync22("/dev/sev"),
-        kvm: existsSync22("/dev/kvm"),
-        helper: existsSync22(process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET)
+        snpHost: existsSync23("/dev/sev"),
+        kvm: existsSync23("/dev/kvm"),
+        helper: existsSync23(process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET)
       }),
       onEvent: (event, detail) => console.log(`[metal-agent] ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
     });
@@ -17501,7 +17779,11 @@ if (import.meta.main) {
   const telemetry = new AgentTelemetryRuntime(createAgentTelemetry(resolveAgentTelemetryConfig()));
   telemetry.event("agent.started");
   telemetry.setDraining(false);
-  const attestationSource = existsSync22("/dev/sev-guest") ? createSnpAttestationSource() : undefined;
+  const handoverCandidate = process.env.FZ_AGENT_HANDOVER_CANDIDATE === "true";
+  if (!handoverCandidate && process.env.FZ_AGENT_ROUTE_SOCKET && process.env.FZ_SOCKET_PATH) {
+    ensureAgentSocketRoute(process.env.FZ_AGENT_ROUTE_SOCKET, process.env.FZ_SOCKET_PATH);
+  }
+  const attestationSource = existsSync23("/dev/sev-guest") ? createSnpAttestationSource() : undefined;
   const running = runAgent({
     socketPath: process.env.FZ_SOCKET_PATH ?? DEFAULT_SOCKET_PATH,
     seedCredential: process.env.FZ_SEED_CREDENTIAL,
@@ -17516,8 +17798,8 @@ if (import.meta.main) {
   const enrolmentStatePath = process.env.FZ_ENROL_STATE_FILE ?? DEFAULT_ENROLMENT_STATE_PATH;
   let binding = loadGuestBinding(enrolmentStatePath, nodeKey);
   const enrolmentCredential = process.env.FZ_ENROL_TOKEN_CREDENTIAL;
-  const enrolmentCredentialAvailable = Boolean(enrolmentCredential && process.env.CREDENTIALS_DIRECTORY && existsSync22(`${process.env.CREDENTIALS_DIRECTORY}/${enrolmentCredential}`));
-  const legacyEnrolmentFileAvailable = Boolean(process.env.FZ_ENROL_TOKEN_FILE && existsSync22(process.env.FZ_ENROL_TOKEN_FILE));
+  const enrolmentCredentialAvailable = Boolean(enrolmentCredential && process.env.CREDENTIALS_DIRECTORY && existsSync23(`${process.env.CREDENTIALS_DIRECTORY}/${enrolmentCredential}`));
+  const legacyEnrolmentFileAvailable = Boolean(process.env.FZ_ENROL_TOKEN_FILE && existsSync23(process.env.FZ_ENROL_TOKEN_FILE));
   if (!binding && (enrolmentCredentialAvailable || legacyEnrolmentFileAvailable) && process.env.FZ_API) {
     binding = await enrolGuestIdentity({
       apiUrl: process.env.FZ_API,
@@ -17537,6 +17819,7 @@ if (import.meta.main) {
   let nodeApiUrl = binding && process.env.FZ_API ? binding.realm === "platform" ? process.env.FZ_API : tenantNodeApiUrl(process.env.FZ_API, binding.tenantSlug) : process.env.FZ_API;
   let secretCache;
   let vaultSync;
+  let initialVaultState = "unbound";
   if (binding && attestationSource && nodeApiUrl) {
     const result = await telemetry.observe("attestation.refresh", () => attestNodeOnce({
       apiUrl: nodeApiUrl,
@@ -17554,6 +17837,7 @@ if (import.meta.main) {
       projectKey: binding.projectKey
     });
     const initialVault = await telemetry.observe("vault.sync", () => initializeVaultReplica(secretCache), (result) => result.state === "ready" ? "success" : "failed");
+    initialVaultState = initialVault.state;
     running.setVault(secretCache, binding.projectKey);
     vaultSync = startNodeVaultSync(secretCache, {
       telemetry,
@@ -17567,6 +17851,31 @@ if (import.meta.main) {
       console.error("[agent] vault replica unavailable; authenticated refresh remains active and only explicit " + "same-name systemd deployment fallbacks are available");
     }
   }
+  if (handoverCandidate) {
+    const ready = startAgentCandidateReady({
+      version: VERSION2,
+      nodeKey,
+      bound: Boolean(binding),
+      vault: initialVaultState
+    }, process.env.FZ_AGENT_HANDOVER_READY_SOCKET ?? DEFAULT_AGENT_CANDIDATE_READY_SOCKET);
+    console.log(`[agent] candidate ${VERSION2} ready for atomic handover`);
+    let stopping = false;
+    const stop = async () => {
+      if (stopping)
+        return;
+      stopping = true;
+      await vaultSync?.stop();
+      await Promise.all([
+        new Promise((resolve6) => ready.close(() => resolve6())),
+        new Promise((resolve6) => server.close(() => resolve6()))
+      ]);
+      await telemetry.close();
+      process.exit(0);
+    };
+    process.on("SIGTERM", () => void stop());
+    process.on("SIGINT", () => void stop());
+    await new Promise(() => {});
+  }
   const attestationLoop = attestationSource && nodeApiUrl ? startNodeAttestation({
     apiUrl: nodeApiUrl,
     nodeKey,
@@ -17595,7 +17904,7 @@ if (import.meta.main) {
   const bootstrapEnabled = process.env.FZ_BOOTSTRAP_PULL === "true";
   const bootstrapCredential = process.env.FZ_BOOTSTRAP_SSH_KEY_CREDENTIAL;
   const bootstrapKeyPath = bootstrapCredential && process.env.CREDENTIALS_DIRECTORY ? `${process.env.CREDENTIALS_DIRECTORY}/${bootstrapCredential}` : undefined;
-  if (bootstrapEnabled && (!binding || !nodeApiUrl || !process.env.FZ_API || !bootstrapKeyPath || !existsSync22(bootstrapKeyPath) || !process.env.FZ_BOOTSTRAP_TARGET_OTLP_ENDPOINT)) {
+  if (bootstrapEnabled && (!binding || !nodeApiUrl || !process.env.FZ_API || !bootstrapKeyPath || !existsSync23(bootstrapKeyPath) || !process.env.FZ_BOOTSTRAP_TARGET_OTLP_ENDPOINT)) {
     throw new Error("agent: bootstrap runner requires enrolment, API, local SSH credential and target OTLP coordinate");
   }
   const bootstrapPull = bootstrapEnabled ? startSshBootstrapPull({