@forgezero/agent 0.1.87 → 0.1.89

package/README.md

@@ -272,10 +272,11 @@ export const selectedCapability = DEFAULT_LIFECYCLE_HELPER_SOCKET;
 <a id="forgezero-agent-provision"></a>
 ## @forgezero/agent/provision
 
-The install plan as data, with no transport — so `fz` running locally and the platform running over SSH provision an identical machine. This entry exposes 34 named value exports and 11 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+The install plan as data, with no transport — so `fz` running locally and the platform running over SSH provision an identical machine. This entry exposes 38 named value exports and 11 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
+  AGENT_CANDIDATE_UNIT_PATH,
   AGENT_EGRESS_UNIT_PATH,
   AGENT_SOCKET_PROXY_UNIT_PATH,
   AGENT_SOCKET_UNIT_PATH,
@@ -295,8 +296,11 @@ import {
   WARP_CONFIG_UNIT_PATH,
   WARP_SERVICE_DROP_IN_PATH,
   agentBackendSocketPath,
+  agentCandidateSocketPath,
+  agentCandidateUnit,
   agentEgressUnit,
   agentEnrolmentUnit,
+  agentRoutingSocketPath,
   agentSocketProxyUnit,
   agentSocketUnit,
   agentUnit,
@@ -333,10 +337,10 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  AGENT_EGRESS_UNIT_PATH,
+  AGENT_CANDIDATE_UNIT_PATH,
 } from '@forgezero/agent/provision';
 
-export const selectedCapability = AGENT_EGRESS_UNIT_PATH;
+export const selectedCapability = AGENT_CANDIDATE_UNIT_PATH;
 ```
 
 <a id="forgezero-agent-platform-genesis"></a>
@@ -534,15 +538,18 @@ export const selectedCapability = heartbeatAgentOnce;
 <a id="forgezero-agent-agent-update"></a>
 ## @forgezero/agent/agent-update
 
-Verified Agent update planning against the platform release coordinate. This entry exposes 8 named value exports and 4 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Verified Agent update planning against the platform release coordinate. This entry exposes 11 named value exports and 4 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
+  DEFAULT_AGENT_CANDIDATE_LINK,
   DEFAULT_AGENT_RELEASE_ROOT,
   DEFAULT_AGENT_UPDATE_SOCKET,
   MAX_AGENT_TARBALL_BYTES,
+  clearAgentCandidate,
   compareVersions,
   restoreAgentRelease,
+  selectAgentCandidate,
   selectAgentRelease,
   stageAgentRelease,
   validateAgentRelease,
@@ -562,10 +569,10 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  DEFAULT_AGENT_RELEASE_ROOT,
+  DEFAULT_AGENT_CANDIDATE_LINK,
 } from '@forgezero/agent/agent-update';
 
-export const selectedCapability = DEFAULT_AGENT_RELEASE_ROOT;
+export const selectedCapability = DEFAULT_AGENT_CANDIDATE_LINK;
 ```
 
 <a id="forgezero-agent-agent-update-helper"></a>
@@ -709,7 +716,7 @@ await readBootstrapBundle(built.bundlePath, built.manifestPath);
 <a id="forgezero-agent-operator-bootstrap"></a>
 ## @forgezero/agent/operator-bootstrap
 
-Pinned-host operator transport that stages owner-only handoffs and invokes the same typed platform bootstrap through the caller-approved SSH agent. This entry exposes 19 named value exports and 17 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Pinned-host operator transport that stages owner-only handoffs and invokes the same typed platform bootstrap through the caller-approved SSH agent. This entry exposes 24 named value exports and 17 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -718,6 +725,10 @@ import {
   applyOperatorPlatformFleetBootstrap,
   collectOperatorGuestHostKeys,
   createOperatorSshHop,
+  operatorMetalClusterBootstrapCode,
+  operatorPackagedAgentPath,
+  operatorPackagedFzCliPath,
+  operatorPackagedGitSshPath,
   operatorPlatformFleetCoordinates,
   planOperatorMetalBootstrap,
   planOperatorPlatformBootstrap,
@@ -726,6 +737,7 @@ import {
   readOperatorMetalBootstrapRequest,
   readOperatorPlatformBootstrapFleetRequest,
   readOperatorPlatformBootstrapRequest,
+  redactOperatorSecretDiagnostic,
   verifyOperatorPlatformFleet,
   withOperatorGuestTransport,
   writeOperatorGuestHostKeyEvidence,
@@ -800,7 +812,7 @@ console.log(plan.argv);
 <a id="forgezero-agent-capacity-calibration"></a>
 ## @forgezero/agent/capacity-calibration
 
-One-time target-local safe-concurrency calibration with private evidence. This entry exposes 3 named value exports and 4 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+One-time target-local safe-concurrency calibration with private evidence. This entry exposes 3 named value exports and 5 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -813,6 +825,7 @@ import type {
   CapacityCalibration,
   CapacityCalibrationOptions,
   CapacityStage,
+  HostCapacitySample,
   ValidatedCapacityCalibrationOptions,
 } from '@forgezero/agent/capacity-calibration';
 ```
@@ -1560,11 +1573,12 @@ export const selectedCapability = MetalProvisionError;
 <a id="forgezero-agent-platform-bootstrap-runtime"></a>
 ## @forgezero/agent/platform-bootstrap-runtime
 
-Pure platform bootstrap validation, render and resumable phase-state contracts. This entry exposes 10 named value exports and 14 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Pure platform bootstrap validation, render and resumable phase-state contracts. This entry exposes 11 named value exports and 14 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
   activatePlatformRelease,
+  assertReleaseLinksContained,
   planLocalOtlpProof,
   planPlatformActivation,
   platformApiCredentialSpecs,

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.89";
 
 // 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.d.ts

@@ -1,5 +1,5 @@
 import { type ProvisionPlan } from './cli/agent-install';
-import type { Capabilities } from './provision';
+import { type Capabilities } from './provision';
 import { type SoftwareCommandResult, type SoftwareRequirement } from './software';
 import { type PlatformSharedEnvironment } from './platform-bootstrap-runtime';
 import { type BootstrapBundleManifest } from './bootstrap-bundle';
@@ -191,6 +191,13 @@ export declare const BOOTSTRAP_STATE_PATH = "/var/lib/forgezero/bootstrap.json";
 export declare function validateBootstrapConfig(value: BootstrapConfig): BootstrapConfig;
 export declare function planBootstrap(input: BootstrapConfig, initialized?: boolean): BootstrapPlan;
 export declare function bootstrapIdentityDigest(config: BootstrapConfig): string;
+export declare const legacyBootstrapIdentityDigest: (config: BootstrapConfig) => string;
+/** Exact prior-release identities accepted only while generation one is still unenrolled. */
+export declare function interruptedPlatformReleaseIdentityDigests(config: PlatformBootstrapConfig, releaseEvidence: {
+    revision: string;
+    sha256: string;
+    branch: string;
+}, bootstrapManifest?: BootstrapBundleManifest): readonly string[];
 export declare function bootstrapStatus(host?: BootstrapHost): Promise<BootstrapStatus>;
 export declare function applyBootstrap(input: BootstrapConfig, host?: BootstrapHost, secrets?: BootstrapSecrets, dependencies?: {
     fetcher?: typeof fetch;