@forgezero/agent 0.1.87 → 0.1.88

package/dist/agent-handover.d.ts

@@ -6,8 +6,14 @@ export interface AgentCandidateReady {
     bound: boolean;
     vault: 'ready' | 'partial' | 'unavailable' | 'unbound';
 }
+export interface AgentCandidateExpectation {
+    version: string;
+    nodeKey: string;
+    bound: boolean;
+    vault: readonly AgentCandidateReady['vault'][];
+}
 /** 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>;
+export declare function probeAgentCandidate(expected: AgentCandidateExpectation, socketPath?: string, timeoutMs?: number): Promise<boolean>;

package/dist/agent-heartbeat.js

@@ -284,7 +284,7 @@ function probeAgentCandidate(expected, socketPath = DEFAULT_AGENT_CANDIDATE_READ
         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 ?? ""));
+        finish(value.version === expected.version && value.nodeKey === expected.nodeKey && value.bound === expected.bound && expected.vault.includes(value.vault));
       } catch {
         finish(false);
       }
@@ -487,13 +487,18 @@ var restartAgent = async (target, run) => {
   }
 };
 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)) => {
+var startCandidate = async (staged, target, expectedNodeKey, run, probe = (expected) => probeAgentCandidate(expected, DEFAULT_AGENT_CANDIDATE_READY_SOCKET)) => {
   selectAgentCandidate(staged);
   if (!await runOk(run, "/usr/bin/systemctl", ["restart", candidateUnit(target)])) {
     clearAgentCandidate(dirname3(staged.currentLink));
     throw new Error(`systemd could not start ${candidateUnit(target)}`);
   }
-  if (!await probe({ version: staged.version })) {
+  if (!await probe({
+    version: staged.version,
+    nodeKey: expectedNodeKey,
+    bound: true,
+    vault: target === "compute" ? ["ready"] : ["unbound"]
+  })) {
     await run({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target)] });
     clearAgentCandidate(dirname3(staged.currentLink));
     throw new Error("the candidate Agent did not prove its identity and durable state");
@@ -572,8 +577,9 @@ async function activateAgentRelease(staged, options = {}) {
   writeUpdateState(journalPath, receiptPath, journal);
   let selectionAttempted = false;
   try {
-    if (!options.candidatePrepared)
-      await startCandidate(staged, target, run);
+    if (!options.candidatePrepared) {
+      throw new Error("direct activation requires a separately identity-bound candidate preparation");
+    }
     if (target === "compute")
       switchAgentSocketRoute(paths.route, paths.candidate);
     selectionAttempted = true;
@@ -763,6 +769,9 @@ function startAgentUpdateHelper(options = {}) {
         }
         if (request.op !== "prepare")
           throw new Error("unknown update operation");
+        if (typeof request.expectedNodeKey !== "string" || request.expectedNodeKey.length < 16 || Buffer.byteLength(request.expectedNodeKey, "utf8") > 512 || /[\0\r\n]/.test(request.expectedNodeKey)) {
+          throw new Error("Agent update expected node identity is invalid");
+        }
         if (busy)
           throw new Error("another Agent update or recovery is already active");
         const prior = readJournal(journalPath, releaseRoot);
@@ -775,8 +784,8 @@ function startAgentUpdateHelper(options = {}) {
           currentVersion: request.currentVersion,
           root: releaseRoot
         });
-        await startCandidate(staged, request.target, runCommand);
-        pending = { staged, target: request.target, attemptId };
+        await startCandidate(staged, request.target, request.expectedNodeKey, runCommand);
+        pending = { staged, target: request.target, attemptId, expectedNodeKey: request.expectedNodeKey };
         ownsBusy = false;
         setTimer(() => {
           if (pending?.attemptId !== attemptId)
@@ -908,7 +917,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.87";
+var VERSION3 = "0.1.88";
 
 // src/agent-heartbeat.ts
 function readAgentHostMetrics() {
@@ -1009,7 +1018,14 @@ async function heartbeatAgentOnce(options) {
       let candidatePrepared = false;
       let drained = false;
       try {
-        const update2 = options.applyUpdate ?? ((phase, next, current, attemptId) => requestAgentUpdate(phase === "prepare" ? { op: "prepare", target: options.updateTarget ?? "compute", release: next, currentVersion: current, attemptId } : {
+        const update2 = options.applyUpdate ?? ((phase, next, current, attemptId) => requestAgentUpdate(phase === "prepare" ? {
+          op: "prepare",
+          target: options.updateTarget ?? "compute",
+          release: next,
+          currentVersion: current,
+          expectedNodeKey: options.nodeKey,
+          attemptId
+        } : {
           op: phase,
           target: options.updateTarget ?? "compute",
           currentVersion: current,

package/dist/agent-update-helper.d.ts

@@ -11,6 +11,7 @@ export type AgentUpdateRequest = {
     target: 'compute' | 'metal';
     attemptId?: string;
     currentVersion: string;
+    expectedNodeKey: string;
     release: AgentRelease;
 } | {
     op: 'commit' | 'abort';

package/dist/agent-update-helper.js

@@ -284,7 +284,7 @@ function probeAgentCandidate(expected, socketPath = DEFAULT_AGENT_CANDIDATE_READ
         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 ?? ""));
+        finish(value.version === expected.version && value.nodeKey === expected.nodeKey && value.bound === expected.bound && expected.vault.includes(value.vault));
       } catch {
         finish(false);
       }
@@ -487,13 +487,18 @@ var restartAgent = async (target, run) => {
   }
 };
 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)) => {
+var startCandidate = async (staged, target, expectedNodeKey, run, probe = (expected) => probeAgentCandidate(expected, DEFAULT_AGENT_CANDIDATE_READY_SOCKET)) => {
   selectAgentCandidate(staged);
   if (!await runOk(run, "/usr/bin/systemctl", ["restart", candidateUnit(target)])) {
     clearAgentCandidate(dirname3(staged.currentLink));
     throw new Error(`systemd could not start ${candidateUnit(target)}`);
   }
-  if (!await probe({ version: staged.version })) {
+  if (!await probe({
+    version: staged.version,
+    nodeKey: expectedNodeKey,
+    bound: true,
+    vault: target === "compute" ? ["ready"] : ["unbound"]
+  })) {
     await run({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target)] });
     clearAgentCandidate(dirname3(staged.currentLink));
     throw new Error("the candidate Agent did not prove its identity and durable state");
@@ -572,8 +577,9 @@ async function activateAgentRelease(staged, options = {}) {
   writeUpdateState(journalPath, receiptPath, journal);
   let selectionAttempted = false;
   try {
-    if (!options.candidatePrepared)
-      await startCandidate(staged, target, run);
+    if (!options.candidatePrepared) {
+      throw new Error("direct activation requires a separately identity-bound candidate preparation");
+    }
     if (target === "compute")
       switchAgentSocketRoute(paths.route, paths.candidate);
     selectionAttempted = true;
@@ -763,6 +769,9 @@ function startAgentUpdateHelper(options = {}) {
         }
         if (request.op !== "prepare")
           throw new Error("unknown update operation");
+        if (typeof request.expectedNodeKey !== "string" || request.expectedNodeKey.length < 16 || Buffer.byteLength(request.expectedNodeKey, "utf8") > 512 || /[\0\r\n]/.test(request.expectedNodeKey)) {
+          throw new Error("Agent update expected node identity is invalid");
+        }
         if (busy)
           throw new Error("another Agent update or recovery is already active");
         const prior = readJournal(journalPath, releaseRoot);
@@ -775,8 +784,8 @@ function startAgentUpdateHelper(options = {}) {
           currentVersion: request.currentVersion,
           root: releaseRoot
         });
-        await startCandidate(staged, request.target, runCommand);
-        pending = { staged, target: request.target, attemptId };
+        await startCandidate(staged, request.target, request.expectedNodeKey, runCommand);
+        pending = { staged, target: request.target, attemptId, expectedNodeKey: request.expectedNodeKey };
         ownsBusy = false;
         setTimer(() => {
           if (pending?.attemptId !== attemptId)

package/dist/bootstrap.js

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

package/dist/fz-agent.js

@@ -9378,7 +9378,7 @@ async function writeAndCloseProcessInput(input, value) {
 }
 
 // src/version.ts
-var VERSION2 = "0.1.87";
+var VERSION2 = "0.1.88";
 
 // src/ssh-bootstrap.ts
 class SshBootstrapError extends Error {
@@ -11987,7 +11987,7 @@ function probeAgentCandidate(expected, socketPath = DEFAULT_AGENT_CANDIDATE_READ
         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 ?? ""));
+        finish(value.version === expected.version && value.nodeKey === expected.nodeKey && value.bound === expected.bound && expected.vault.includes(value.vault));
       } catch {
         finish(false);
       }
@@ -12190,13 +12190,18 @@ var restartAgent = async (target2, run2) => {
   }
 };
 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)) => {
+var startCandidate = async (staged, target2, expectedNodeKey, 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 })) {
+  if (!await probe({
+    version: staged.version,
+    nodeKey: expectedNodeKey,
+    bound: true,
+    vault: target2 === "compute" ? ["ready"] : ["unbound"]
+  })) {
     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");
@@ -12275,8 +12280,9 @@ async function activateAgentRelease(staged, options = {}) {
   writeUpdateState(journalPath, receiptPath, journal);
   let selectionAttempted = false;
   try {
-    if (!options.candidatePrepared)
-      await startCandidate(staged, target2, run2);
+    if (!options.candidatePrepared) {
+      throw new Error("direct activation requires a separately identity-bound candidate preparation");
+    }
     if (target2 === "compute")
       switchAgentSocketRoute(paths.route, paths.candidate);
     selectionAttempted = true;
@@ -12466,6 +12472,9 @@ function startAgentUpdateHelper(options = {}) {
         }
         if (request.op !== "prepare")
           throw new Error("unknown update operation");
+        if (typeof request.expectedNodeKey !== "string" || request.expectedNodeKey.length < 16 || Buffer.byteLength(request.expectedNodeKey, "utf8") > 512 || /[\0\r\n]/.test(request.expectedNodeKey)) {
+          throw new Error("Agent update expected node identity is invalid");
+        }
         if (busy)
           throw new Error("another Agent update or recovery is already active");
         const prior = readJournal(journalPath, releaseRoot);
@@ -12478,8 +12487,8 @@ function startAgentUpdateHelper(options = {}) {
           currentVersion: request.currentVersion,
           root: releaseRoot
         });
-        await startCandidate(staged, request.target, runCommand);
-        pending = { staged, target: request.target, attemptId };
+        await startCandidate(staged, request.target, request.expectedNodeKey, runCommand);
+        pending = { staged, target: request.target, attemptId, expectedNodeKey: request.expectedNodeKey };
         ownsBusy = false;
         setTimer(() => {
           if (pending?.attemptId !== attemptId)
@@ -12636,7 +12645,14 @@ async function heartbeatAgentOnce(options) {
       let candidatePrepared = false;
       let drained = false;
       try {
-        const update2 = options.applyUpdate ?? ((phase, next, current2, attemptId) => requestAgentUpdate(phase === "prepare" ? { op: "prepare", target: options.updateTarget ?? "compute", release: next, currentVersion: current2, attemptId } : {
+        const update2 = options.applyUpdate ?? ((phase, next, current2, attemptId) => requestAgentUpdate(phase === "prepare" ? {
+          op: "prepare",
+          target: options.updateTarget ?? "compute",
+          release: next,
+          currentVersion: current2,
+          expectedNodeKey: options.nodeKey,
+          attemptId
+        } : {
           op: phase,
           target: options.updateTarget ?? "compute",
           currentVersion: current2,

package/dist/fz.js

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

package/dist/metal-bootstrap.js

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

package/dist/operator-bootstrap.js

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

package/dist/platform-fleet-verification.js

@@ -284,7 +284,7 @@ function probeAgentCandidate(expected, socketPath = DEFAULT_AGENT_CANDIDATE_READ
         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 ?? ""));
+        finish(value.version === expected.version && value.nodeKey === expected.nodeKey && value.bound === expected.bound && expected.vault.includes(value.vault));
       } catch {
         finish(false);
       }
@@ -487,13 +487,18 @@ var restartAgent = async (target, run) => {
   }
 };
 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)) => {
+var startCandidate = async (staged, target, expectedNodeKey, run, probe = (expected) => probeAgentCandidate(expected, DEFAULT_AGENT_CANDIDATE_READY_SOCKET)) => {
   selectAgentCandidate(staged);
   if (!await runOk(run, "/usr/bin/systemctl", ["restart", candidateUnit(target)])) {
     clearAgentCandidate(dirname3(staged.currentLink));
     throw new Error(`systemd could not start ${candidateUnit(target)}`);
   }
-  if (!await probe({ version: staged.version })) {
+  if (!await probe({
+    version: staged.version,
+    nodeKey: expectedNodeKey,
+    bound: true,
+    vault: target === "compute" ? ["ready"] : ["unbound"]
+  })) {
     await run({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target)] });
     clearAgentCandidate(dirname3(staged.currentLink));
     throw new Error("the candidate Agent did not prove its identity and durable state");
@@ -572,8 +577,9 @@ async function activateAgentRelease(staged, options = {}) {
   writeUpdateState(journalPath, receiptPath, journal);
   let selectionAttempted = false;
   try {
-    if (!options.candidatePrepared)
-      await startCandidate(staged, target, run);
+    if (!options.candidatePrepared) {
+      throw new Error("direct activation requires a separately identity-bound candidate preparation");
+    }
     if (target === "compute")
       switchAgentSocketRoute(paths.route, paths.candidate);
     selectionAttempted = true;
@@ -763,6 +769,9 @@ function startAgentUpdateHelper(options = {}) {
         }
         if (request.op !== "prepare")
           throw new Error("unknown update operation");
+        if (typeof request.expectedNodeKey !== "string" || request.expectedNodeKey.length < 16 || Buffer.byteLength(request.expectedNodeKey, "utf8") > 512 || /[\0\r\n]/.test(request.expectedNodeKey)) {
+          throw new Error("Agent update expected node identity is invalid");
+        }
         if (busy)
           throw new Error("another Agent update or recovery is already active");
         const prior = readJournal(journalPath, releaseRoot);
@@ -775,8 +784,8 @@ function startAgentUpdateHelper(options = {}) {
           currentVersion: request.currentVersion,
           root: releaseRoot
         });
-        await startCandidate(staged, request.target, runCommand);
-        pending = { staged, target: request.target, attemptId };
+        await startCandidate(staged, request.target, request.expectedNodeKey, runCommand);
+        pending = { staged, target: request.target, attemptId, expectedNodeKey: request.expectedNodeKey };
         ownsBusy = false;
         setTimer(() => {
           if (pending?.attemptId !== attemptId)
@@ -2803,7 +2812,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.87";
+var VERSION3 = "0.1.88";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";

package/dist/provision.js

@@ -284,7 +284,7 @@ function probeAgentCandidate(expected, socketPath = DEFAULT_AGENT_CANDIDATE_READ
         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 ?? ""));
+        finish(value.version === expected.version && value.nodeKey === expected.nodeKey && value.bound === expected.bound && expected.vault.includes(value.vault));
       } catch {
         finish(false);
       }
@@ -487,13 +487,18 @@ var restartAgent = async (target, run) => {
   }
 };
 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)) => {
+var startCandidate = async (staged, target, expectedNodeKey, run, probe = (expected) => probeAgentCandidate(expected, DEFAULT_AGENT_CANDIDATE_READY_SOCKET)) => {
   selectAgentCandidate(staged);
   if (!await runOk(run, "/usr/bin/systemctl", ["restart", candidateUnit(target)])) {
     clearAgentCandidate(dirname3(staged.currentLink));
     throw new Error(`systemd could not start ${candidateUnit(target)}`);
   }
-  if (!await probe({ version: staged.version })) {
+  if (!await probe({
+    version: staged.version,
+    nodeKey: expectedNodeKey,
+    bound: true,
+    vault: target === "compute" ? ["ready"] : ["unbound"]
+  })) {
     await run({ command: "/usr/bin/systemctl", args: ["stop", candidateUnit(target)] });
     clearAgentCandidate(dirname3(staged.currentLink));
     throw new Error("the candidate Agent did not prove its identity and durable state");
@@ -572,8 +577,9 @@ async function activateAgentRelease(staged, options = {}) {
   writeUpdateState(journalPath, receiptPath, journal);
   let selectionAttempted = false;
   try {
-    if (!options.candidatePrepared)
-      await startCandidate(staged, target, run);
+    if (!options.candidatePrepared) {
+      throw new Error("direct activation requires a separately identity-bound candidate preparation");
+    }
     if (target === "compute")
       switchAgentSocketRoute(paths.route, paths.candidate);
     selectionAttempted = true;
@@ -763,6 +769,9 @@ function startAgentUpdateHelper(options = {}) {
         }
         if (request.op !== "prepare")
           throw new Error("unknown update operation");
+        if (typeof request.expectedNodeKey !== "string" || request.expectedNodeKey.length < 16 || Buffer.byteLength(request.expectedNodeKey, "utf8") > 512 || /[\0\r\n]/.test(request.expectedNodeKey)) {
+          throw new Error("Agent update expected node identity is invalid");
+        }
         if (busy)
           throw new Error("another Agent update or recovery is already active");
         const prior = readJournal(journalPath, releaseRoot);
@@ -775,8 +784,8 @@ function startAgentUpdateHelper(options = {}) {
           currentVersion: request.currentVersion,
           root: releaseRoot
         });
-        await startCandidate(staged, request.target, runCommand);
-        pending = { staged, target: request.target, attemptId };
+        await startCandidate(staged, request.target, request.expectedNodeKey, runCommand);
+        pending = { staged, target: request.target, attemptId, expectedNodeKey: request.expectedNodeKey };
         ownsBusy = false;
         setTimer(() => {
           if (pending?.attemptId !== attemptId)
@@ -2803,7 +2812,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.87";
+var VERSION3 = "0.1.88";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";

package/dist/version.d.ts

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

package/package.json

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