@forgezero/agent 0.1.85 → 0.1.87

package/README.md

@@ -11,7 +11,7 @@ The node agent deploys on a compute; tenant mode also holds one complete project
 
 ## Package overview
 
-Every managed compute. It owns node identity, attestation and repository pipelines. Tenant mode additionally holds one whole project across its environments in RAM and answers over a unix socket; platform mode never replicates the API vault beside the process that already holds every unlocked realm seed. Supported runtimes: bun, node. Package root: @forgezero/agent. The sections below show the actual named imports emitted by each declaration entry point; wildcard imports are intentionally not used in the documentation.
+Every managed compute. It owns node identity, attestation and repository pipelines. An SNP compute may hold its assigned whole project across environments in RAM after current attestation. Ordinary compute is API-only unless an administrator explicitly records the versioned non-TEE risk acceptance for that concrete machine. Platform mode never replicates realm-wide API authority beside the process that already holds unlocked realm seeds. Supported runtimes: bun, node. Package root: @forgezero/agent. The sections below show the actual named imports emitted by each declaration entry point; wildcard imports are intentionally not used in the documentation.
 
 ```text
 bun add -g @forgezero/agent
@@ -38,7 +38,7 @@ Every row links to the detailed explanation and named-import/example area below.
 | fz | The operator command: keys, status, genesis, unlock, run, and agent install. | Bun/Node host | [Reference + usage](#fz) |
 | fz run | The fallback for software that cannot read the local socket: start a process with scoped vault values in its environment. | Bun/Node host | [Reference + usage](#fz-run) |
 | fz agent install | Provision the same hardened agent service locally that the platform provisions remotely. | Bun/Node host | [Reference + usage](#fz-agent-install) |
-| fz-agent | The service entry point. Identity and private Git material arrive only as systemd credentials. A platform bootstrap may use a statically configured local control socket; an enrolled tenant guest builds each deployment manager from its signed server claim and reads all commands from the checked-out .fz definition. The signed enrolment binding constructs the exact project Vault replica scope, and an SNP guest completes its first live attestation before Vault synchronization begins. | Bun/Node host | [Reference + usage](#fz-agent) |
+| fz-agent | The service entry point. Identity and private Git material arrive only as systemd credentials. A platform bootstrap may use a statically configured local control socket; an enrolled tenant guest builds each deployment manager from its signed server claim and reads all commands from the checked-out .fz definition. The signed enrolment binding constructs the exact project scope. Vault synchronization succeeds only when the API sees current SNP evidence or an audited versioned non-TEE acceptance; ordinary compute otherwise remains API-only and a revocation clears its resident cache. | Bun/Node host | [Reference + usage](#fz-agent) |
 | fz-agent (socket) | identity, sign, attest, get, sync and held — the whole interface an application sees. | Bun/Node host | [Reference + usage](#fz-agent-socket) |
 | @forgezero/agent/migration-pull | PQ-authenticated outbound lifecycle claims with fenced renewal, awaited async execution, idempotent acknowledgement and bounded shutdown drain. The executor reports local facts only. | Bun/Node host | [Reference + usage](#forgezero-agent-migration-pull) |
 | @forgezero/agent/lifecycle-helper | The root-owned fixed-operation boundary for migration work. Signed controller claims can request only private reachability probes, local health checks, or stops of units named in a root-owned profile; they cannot carry commands. | Bun/Node host | [Reference + usage](#forgezero-agent-lifecycle-helper) |
@@ -79,7 +79,7 @@ Every row links to the detailed explanation and named-import/example area below.
 | @forgezero/agent/software | Exact managed-software inventory, requirement and evidence contracts. | Bun/Node host | [Reference + usage](#forgezero-agent-software) |
 | @forgezero/agent/software-helper | Root-owned fixed installation/update boundary for declared software. | Bun/Node host | [Reference + usage](#forgezero-agent-software-helper) |
 | @forgezero/agent/ubuntu | The closed guest-image view: pinned Ubuntu 26.04 LTS x64 supports ordinary or SEV-SNP compute, while pinned Ubuntu 24.04 LTS x64 is limited to ordinary non-confidential compute. Every other OS remains rejected until its own pinned strategy and acceptance evidence are added. | Bun/Node host | [Reference + usage](#forgezero-agent-ubuntu) |
-| fz-agent (replica) | The project-scoped vault replica: resident in RAM, never on disk, invalidated by cursor rather than by timer, and refusing a read it can no longer vouch for. | Bun/Node host | [Reference + usage](#fz-agent-replica) |
+| fz-agent (replica) | The authorized project-scoped vault replica: resident in RAM, never on disk, invalidated by cursor rather than by timer, cleared when local authority is revoked, and refusing a read it can no longer vouch for. | Bun/Node host | [Reference + usage](#fz-agent-replica) |
 
 ## Commands
 
@@ -89,8 +89,8 @@ fz deploy init --runtime containerd --os ubuntu-24.04 --replicas 1 --cpu-cores 2
 fz deploy init --runtime kata-snp --os ubuntu-26.04 --replicas 1 --cpu-cores 2 --memory-mib 4096 --storage-gib 40 --reuse require — Create one Kata QEMU SEV-SNP definition on existing eligible capacity. Use reuse prefer only with the explicit provisioning and spend-ceiling flags shown by fz deploy init --help.
 fz deploy compile — Compile and validate TypeScript deployment intent into .fz/deploy.plan.json.
 fz deploy check — Refuse stale plans, unsafe provider/action coordinates and unresolved deployment blockers.
-fz bootstrap platform bundle --root /absolute/api --branch dev --output /secure/forgezero/development/api.bundle — Build one verified release-generation-one source bundle without a Git credential.
-fz bootstrap platform remote apply --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json — Dry-plan one pinned operator-to-guest bootstrap; add --apply only after review.
+fz bootstrap platform launch --profile development --apply — Run the one attended ForgeZero launch: public topology and bundle are derived; answer only email settings, hidden provider tokens and APPLY.
+fz bootstrap platform fleet apply --bootstrap-config /secure/forgezero/development/genesis/platform-fleet-remote.json — Resume or diagnose an already generated fleet plan; this is not the normal first-launch path.
 fz bootstrap platform --help — Inspect attended platform bootstrap inputs before applying them.
 fz bootstrap metal --help — Inspect the identity-only physical provisioner bootstrap.
 fz host transactions|schema-plan|schema-apply — Plan fixed supervised database maintenance; add --apply only after reviewing the exact argv and credential names.
@@ -103,8 +103,8 @@ fz deploy init --runtime containerd --os ubuntu-24.04 --replicas 1 --cpu-cores 2
 fz deploy init --runtime kata-snp --os ubuntu-26.04 --replicas 1 --cpu-cores 2 --memory-mib 4096 --storage-gib 40 --reuse require
 fz deploy compile
 fz deploy check
-fz bootstrap platform bundle --root /absolute/api --branch dev --output /secure/forgezero/development/api.bundle
-fz bootstrap platform remote apply --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json
+fz bootstrap platform launch --profile development --apply
+fz bootstrap platform fleet apply --bootstrap-config /secure/forgezero/development/genesis/platform-fleet-remote.json
 fz bootstrap platform --help
 fz bootstrap metal --help
 fz host transactions|schema-plan|schema-apply
@@ -167,7 +167,7 @@ fz agent install --help
 <a id="fz-agent"></a>
 ## fz-agent
 
-The service entry point. Identity and private Git material arrive only as systemd credentials. A platform bootstrap may use a statically configured local control socket; an enrolled tenant guest builds each deployment manager from its signed server claim and reads all commands from the checked-out .fz definition. The signed enrolment binding constructs the exact project Vault replica scope, and an SNP guest completes its first live attestation before Vault synchronization begins. This entry requires a Bun/Node host runtime. Run the command with `--help` before applying it.
+The service entry point. Identity and private Git material arrive only as systemd credentials. A platform bootstrap may use a statically configured local control socket; an enrolled tenant guest builds each deployment manager from its signed server claim and reads all commands from the checked-out .fz definition. The signed enrolment binding constructs the exact project scope. Vault synchronization succeeds only when the API sees current SNP evidence or an audited versioned non-TEE acceptance; ordinary compute otherwise remains API-only and a revocation clears its resident cache. This entry requires a Bun/Node host runtime. Run the command with `--help` before applying it.
 
 ```text
 fz-agent --help
@@ -755,14 +755,13 @@ import type {
 } from '@forgezero/agent/operator-bootstrap';
 ```
 
-## @forgezero/agent/operator-bootstrap — Run the same typed platform bootstrap from an operator laptop
+## @forgezero/agent/operator-bootstrap — Launch the platform from an operator laptop
 
-The request contains the pinned SSH transport, reviewed platform config, and one verified local Git bundle copied identically to every genesis compute. No repository key is created. Hidden credential values are sealed immediately as systemd credentials.
+The selected ForgeZero profile and pinned Metal evidence derive every public coordinate. The CLI builds the clean API bundle, retains cluster material only as an owner-host encrypted systemd credential for safe resume, deploys all three computes, seals hidden credentials, seeds inventory and prints the invitation. Low-level file commands are reserved for resume and repair.
 
 ```text
-fz bootstrap platform remote apply --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json
-# Review, then allow the SSH-agent approval prompt:
-fz bootstrap platform remote apply --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json --apply
+# The command prints the derived plan before its final APPLY confirmation:
+fz bootstrap platform launch --profile development --apply
 ```
 
 <a id="forgezero-agent-host-maintenance"></a>
@@ -1809,7 +1808,7 @@ export const selectedCapability = SUPPORTED_GUEST_IMAGE;
 <a id="fz-agent-replica"></a>
 ## fz-agent (replica)
 
-The project-scoped vault replica: resident in RAM, never on disk, invalidated by cursor rather than by timer, and refusing a read it can no longer vouch for. This is a managed runtime interface label, not an import or standalone executable.
+The authorized project-scoped vault replica: resident in RAM, never on disk, invalidated by cursor rather than by timer, cleared when local authority is revoked, and refusing a read it can no longer vouch for. This is a managed runtime interface label, not an import or standalone executable.
 
 ```text
 fz-agent (replica)

package/dist/agent-handover.d.ts

@@ -0,0 +1,13 @@
+import { type Server } from 'node:net';
+export declare const DEFAULT_AGENT_CANDIDATE_READY_SOCKET = "/run/forgezero/candidate-ready.sock";
+export interface AgentCandidateReady {
+    version: string;
+    nodeKey: string;
+    bound: boolean;
+    vault: 'ready' | 'partial' | 'unavailable' | 'unbound';
+}
+/** New proxy connections resolve the new backend; established streams are untouched. */
+export declare function switchAgentSocketRoute(route: string, backend: string): void;
+/** Root-observable readiness appears only after identity, binding and Vault initialization. */
+export declare function startAgentCandidateReady(ready: AgentCandidateReady, socketPath?: string): Server;
+export declare function probeAgentCandidate(expected: Pick<AgentCandidateReady, 'version'>, socketPath?: string, timeoutMs?: number): Promise<boolean>;

package/dist/agent-heartbeat.d.ts

@@ -72,11 +72,11 @@ export interface AgentHeartbeatOptions {
     applyDeploymentIntake?: (directive: NonNullable<AgentHeartbeatResponse['deploymentIntake']>) => Promise<void> | void;
     receiptPath?: string;
     now?: () => number;
-    /** Stop new lifecycle/deploy claims and await current jobs before replacement. */
+    /** Stop new lifecycle/deploy claims and await current jobs after candidate readiness. */
     prepareUpdate?: (release: AgentRelease) => Promise<void>;
-    /** Restart the drained current process if staging is refused before activation. */
+    /** Recover only after a prepared candidate could not be committed. */
     recoverUpdate?: (cause: unknown) => Promise<void> | void;
-    applyUpdate?: (release: AgentRelease, currentVersion: string, attemptId: string) => Promise<AgentUpdateResponse>;
+    applyUpdate?: (phase: 'prepare' | 'commit' | 'abort', release: AgentRelease, currentVersion: string, attemptId: string) => Promise<AgentUpdateResponse>;
     setTimer?: (callback: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;

package/dist/agent-heartbeat.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 && 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";
@@ -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,32 @@ 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, 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 })) {
+    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 +544,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 +572,18 @@ async function activateAgentRelease(staged, options = {}) {
   writeUpdateState(journalPath, receiptPath, journal);
   let selectionAttempted = false;
   try {
+    if (!options.candidatePrepared)
+      await startCandidate(staged, target, run);
+    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 +601,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 +627,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 +675,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 +703,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 +722,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 ?? 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 (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 +775,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,
@@ -647,12 +803,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, () => {
@@ -677,7 +833,7 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 }
 
 // src/agent-heartbeat.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, statfsSync } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync3, statfsSync } from "node:fs";
 import { cpus, freemem, loadavg, totalmem } from "node:os";
 
 // src/signed-node-http.ts
@@ -691,9 +847,11 @@ import {
 
 class SignedNodeHttpError extends Error {
   status;
-  constructor(status, message) {
+  code;
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code;
     this.name = "SignedNodeHttpError";
   }
 }
@@ -740,7 +898,7 @@ async function postSignedNode(options, path, body) {
   if (!response.ok) {
     const failure = payload;
     const reason2 = failure ? failure.error?.message ?? failure.message : undefined;
-    throw new SignedNodeHttpError(response.status, reason2 || `signed node request returned HTTP ${response.status}`);
+    throw new SignedNodeHttpError(response.status, reason2 || `signed node request returned HTTP ${response.status}`, failure?.error?.code);
   }
   try {
     return await openResponse(recipient.secretKey, signature, payload);
@@ -750,7 +908,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.85";
+var VERSION3 = "0.1.87";
 
 // src/agent-heartbeat.ts
 function readAgentHostMetrics() {
@@ -796,7 +954,7 @@ function observeAgentHost(version = VERSION3, mode = "enrolled", osRelease = rea
     runtimeCapabilities: {
       native: true,
       ociRunc: ubuntuX64,
-      kataQemuSnp: ubuntuX64 && osVersion === "26.04" && existsSync3("/dev/kvm") && existsSync3("/dev/sev") && enabled("/sys/module/kvm_amd/parameters/sev") && enabled("/sys/module/kvm_amd/parameters/sev_snp")
+      kataQemuSnp: ubuntuX64 && osVersion === "26.04" && existsSync4("/dev/kvm") && existsSync4("/dev/sev") && enabled("/sys/module/kvm_amd/parameters/sev") && enabled("/sys/module/kvm_amd/parameters/sev_snp")
     },
     capacity: {
       logicalCpu: Math.max(1, metrics.logicalCpu),
@@ -848,18 +1006,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, current, attemptId) => requestAgentUpdate(phase === "prepare" ? { op: "prepare", target: options.updateTarget ?? "compute", release: next, currentVersion: current, attemptId } : {
+          op: phase,
+          target: options.updateTarget ?? "compute",
+          currentVersion: current,
+          targetVersion: next.version,
+          attemptId
+        }));
         const apply = async () => {
-          const applied = await (options.applyUpdate ?? ((next, current, attemptId) => requestAgentUpdate({
-            op: "apply",
-            target: options.updateTarget ?? "compute",
-            release: next,
-            currentVersion: current,
-            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) {
@@ -872,9 +1036,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, current, attemptId) => requestAgentUpdate({
+            op: phase,
+            target: options.updateTarget ?? "compute",
+            currentVersion: current,
+            targetVersion: next.version,
+            attemptId
+          })))("abort", release, observation.version, desired.attemptId).catch(() => {});
+        }
+        if (drained)
           await options.recoverUpdate?.(cause);
         throw cause;
       }