@forgezero/agent 0.1.71 → 0.1.73

package/README.md

@@ -1025,7 +1025,7 @@ import type {
 <a id="forgezero-agent-metal-bootstrap"></a>
 ## @forgezero/agent/metal-bootstrap
 
-Physical-metal bootstrap planning, application and status evidence. This entry exposes 10 named value exports and 6 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Physical-metal bootstrap planning, application and status evidence. This entry exposes 10 named value exports and 7 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 {
@@ -1048,6 +1048,7 @@ import type {
   MetalBootstrapPlan,
   MetalBootstrapResult,
   MetalBootstrapStatus,
+  MetalBootstrapValidationOptions,
 } from '@forgezero/agent/metal-bootstrap';
 ```
 

package/dist/agent-heartbeat.js

@@ -749,7 +749,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.71";
+var VERSION3 = "0.1.73";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");

package/dist/bootstrap.js

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

package/dist/fz-agent.js

@@ -8588,7 +8588,7 @@ import { join as join3 } from "path";
 import { fileURLToPath } from "url";
 
 // src/version.ts
-var VERSION2 = "0.1.71";
+var VERSION2 = "0.1.73";
 
 // src/ssh-bootstrap.ts
 class SshBootstrapError extends Error {

package/dist/fz.js

@@ -4829,7 +4829,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION2 = "0.1.71";
+var VERSION2 = "0.1.73";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -15522,7 +15522,7 @@ var validUnit = (unit) => {
     throw new MetalBootstrapError("the OTLP collector must be independently supervised");
   }
 };
-function validateMetalBootstrapConfig(config) {
+function validateMetalBootstrapConfig(config, options = {}) {
   if (!config || typeof config !== "object")
     throw new MetalBootstrapError("metal bootstrap config must be an object");
   exactKeys4(config, ["kind", "metalHostname", "profile", "hostTelemetryEndpoint", "hostTelemetryUnit", "agentSeedFile"], "metal bootstrap config");
@@ -15566,7 +15566,7 @@ function validateMetalBootstrapConfig(config) {
   for (const image of Object.values(config.profile.images))
     if (!image.path.startsWith("/var/lib/forgezero/images/") || resolve8(image.path) !== image.path || /[\0\r\n]/.test(image.path))
       throw new MetalBootstrapError("every pinned guest image must use the fixed image directory");
-  if (config.profile.bunVersion !== SUPPORTED_BUN_VERSION || config.profile.bunReleaseSha256 !== SUPPORTED_BUN_RELEASE_SHA256 || config.profile.agentVersion !== VERSION2) {
+  if (!options.allowHistoricalRelease && (config.profile.bunVersion !== SUPPORTED_BUN_VERSION || config.profile.bunReleaseSha256 !== SUPPORTED_BUN_RELEASE_SHA256 || config.profile.agentVersion !== VERSION2)) {
     throw new MetalBootstrapError("metal guest runtime must use the package-owned Bun and Agent release coordinates");
   }
   let api;
@@ -15612,7 +15612,7 @@ function validateOwnerOnlyPath(path, requireRootOwner) {
     throw new MetalBootstrapError(requireRootOwner ? "private bootstrap file must be root-owned" : "private bootstrap file has an unexpected owner");
   }
 }
-function readMetalBootstrapConfig(path) {
+function readMetalBootstrapConfig(path, options = {}) {
   validateOwnerOnlyPath(path, false);
   const metadata = statSync(path);
   if (metadata.size < 2 || metadata.size > MAX_CONFIG_BYTES)
@@ -15623,7 +15623,7 @@ function readMetalBootstrapConfig(path) {
   } catch {
     throw new MetalBootstrapError("metal bootstrap config is not valid JSON");
   }
-  return validateMetalBootstrapConfig(parsed);
+  return validateMetalBootstrapConfig(parsed, options);
 }
 function planMetalBootstrap(config) {
   validateMetalBootstrapConfig(config);
@@ -17418,6 +17418,7 @@ function parseOptions(argv2) {
     realm: process.env.FZ_REALM ?? "platform",
     realmExplicit: Boolean(process.env.FZ_REALM),
     json: false,
+    help: false,
     apply: false,
     enrol: false,
     socket: process.env.SSH_AUTH_SOCK,
@@ -17456,6 +17457,8 @@ function parseOptions(argv2) {
       options.socket = argv2[++index];
     else if (token === "--json")
       options.json = true;
+    else if (token === "--help" || token === "-h")
+      options.help = true;
     else if (token === "--apply")
       options.apply = true;
     else if (token === "--enrol")
@@ -18331,11 +18334,13 @@ function writeMetalOperatorFiles(directory) {
 function writePlatformGenesisFleet(directory) {
   const output = genesisOutputDirectory(directory);
   const metalRequestFile = bootstrapAnswer("Owner-only metal remote request containing the reviewed genesis guests");
-  const metalRequest = readOperatorMetalBootstrapRequest(metalRequestFile);
+  const metalRequest = readOperatorMetalBootstrapRequest(metalRequestFile, { validateMetalConfig: false });
   const guestHostKeysFile = bootstrapAnswer("Owner-only guest host-key evidence file");
   const guestHostKeys = readOperatorGuestHostKeyEvidence(guestHostKeysFile, metalRequest);
   const fleet = metalRequest.genesis.nodes;
-  const metalHostname = readMetalBootstrapConfig(metalRequest.metalConfigFile).metalHostname;
+  const metalHostname = readMetalBootstrapConfig(metalRequest.metalConfigFile, {
+    allowHistoricalRelease: true
+  }).metalHostname;
   const checkpointPath = join12(output, "cloudflare-handoff.json");
   const template = interactiveBootstrap("platform", fleet, checkpointPath);
   const region = {
@@ -18443,7 +18448,7 @@ function interactiveBootstrap(kind, genesisGuests, genesisCloudflareCheckpoint)
   const backupBucket = backupEndpoint ? bootstrapAnswer("Backup S3 bucket") : undefined;
   const backupAccessKeyId = backupEndpoint ? bootstrapAnswer("Backup S3 access-key id") : undefined;
   const cloudflareHandoffFile = genesis ? cloudflareHostHandoffPath(genesisCloudflareCheckpoint, computeReference) : bootstrapAnswer("Node-specific Cloudflare host handoff (blank for no public edge)", "");
-  const cloudflareNodeName = cloudflareHandoffFile ? bootstrapAnswer("Cloudflare handoff node name", computeReference) : undefined;
+  const cloudflareNodeName = cloudflareHandoffFile ? genesis ? computeReference : bootstrapAnswer("Cloudflare handoff node name", computeReference) : undefined;
   const databaseNetworkMode = "private-lan";
   const enrolmentSource = genesis ? "genesis-derived" : bootstrapAnswer("Enrolment source (genesis-derived/api-token)", "genesis-derived");
   return {
@@ -19471,6 +19476,10 @@ if (import.meta.main) {
 }
 async function runCli() {
   const { command, args, options } = parseOptions(process.argv.slice(2));
+  if (options.help) {
+    usage();
+    process.exit(0);
+  }
   try {
     hydrateSession(options);
   } catch (cause) {

package/dist/metal-bootstrap.d.ts

@@ -44,10 +44,17 @@ export interface MetalBootstrapApplyOptions {
 export declare class MetalBootstrapError extends Error {
 }
 export declare function normalizeMetalPublicIdentity(value: string): string;
-export declare function validateMetalBootstrapConfig(config: MetalBootstrapConfig): MetalBootstrapConfig;
+export interface MetalBootstrapValidationOptions {
+    /**
+     * Read identity/topology from a config that was already applied by an older
+     * Agent release. New installs and repairs must never set this flag.
+     */
+    allowHistoricalRelease?: boolean;
+}
+export declare function validateMetalBootstrapConfig(config: MetalBootstrapConfig, options?: MetalBootstrapValidationOptions): MetalBootstrapConfig;
 /** Reject symlinks and group/world access before parsing coordinates or entropy. */
 export declare function validateOwnerOnlyPath(path: string, requireRootOwner: boolean): void;
-export declare function readMetalBootstrapConfig(path: string): MetalBootstrapConfig;
+export declare function readMetalBootstrapConfig(path: string, options?: MetalBootstrapValidationOptions): MetalBootstrapConfig;
 export declare function planMetalBootstrap(config: MetalBootstrapConfig): MetalBootstrapPlan;
 export declare function renderMetalUnits(config: MetalBootstrapConfig): Record<string, string>;
 export declare function applyMetalBootstrap(config: MetalBootstrapConfig, options: MetalBootstrapApplyOptions): Promise<MetalBootstrapResult>;

package/dist/metal-bootstrap.js

@@ -354,7 +354,7 @@ function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
 }
 
 // src/version.ts
-var VERSION = "0.1.71";
+var VERSION = "0.1.73";
 
 // src/otel-collector.ts
 var FORGEZERO_OTEL_COLLECTOR_UNIT = "forgezero-otel-collector.service";
@@ -579,7 +579,7 @@ var validUnit = (unit) => {
     throw new MetalBootstrapError("the OTLP collector must be independently supervised");
   }
 };
-function validateMetalBootstrapConfig(config) {
+function validateMetalBootstrapConfig(config, options = {}) {
   if (!config || typeof config !== "object")
     throw new MetalBootstrapError("metal bootstrap config must be an object");
   exactKeys(config, ["kind", "metalHostname", "profile", "hostTelemetryEndpoint", "hostTelemetryUnit", "agentSeedFile"], "metal bootstrap config");
@@ -623,7 +623,7 @@ function validateMetalBootstrapConfig(config) {
   for (const image of Object.values(config.profile.images))
     if (!image.path.startsWith("/var/lib/forgezero/images/") || resolve(image.path) !== image.path || /[\0\r\n]/.test(image.path))
       throw new MetalBootstrapError("every pinned guest image must use the fixed image directory");
-  if (config.profile.bunVersion !== SUPPORTED_BUN_VERSION || config.profile.bunReleaseSha256 !== SUPPORTED_BUN_RELEASE_SHA256 || config.profile.agentVersion !== VERSION) {
+  if (!options.allowHistoricalRelease && (config.profile.bunVersion !== SUPPORTED_BUN_VERSION || config.profile.bunReleaseSha256 !== SUPPORTED_BUN_RELEASE_SHA256 || config.profile.agentVersion !== VERSION)) {
     throw new MetalBootstrapError("metal guest runtime must use the package-owned Bun and Agent release coordinates");
   }
   let api;
@@ -669,7 +669,7 @@ function validateOwnerOnlyPath(path, requireRootOwner) {
     throw new MetalBootstrapError(requireRootOwner ? "private bootstrap file must be root-owned" : "private bootstrap file has an unexpected owner");
   }
 }
-function readMetalBootstrapConfig(path) {
+function readMetalBootstrapConfig(path, options = {}) {
   validateOwnerOnlyPath(path, false);
   const metadata = statSync(path);
   if (metadata.size < 2 || metadata.size > MAX_CONFIG_BYTES)
@@ -680,7 +680,7 @@ function readMetalBootstrapConfig(path) {
   } catch {
     throw new MetalBootstrapError("metal bootstrap config is not valid JSON");
   }
-  return validateMetalBootstrapConfig(parsed);
+  return validateMetalBootstrapConfig(parsed, options);
 }
 function planMetalBootstrap(config) {
   validateMetalBootstrapConfig(config);

package/dist/operator-bootstrap.js

@@ -1416,7 +1416,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.71";
+var VERSION = "0.1.73";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -5233,7 +5233,7 @@ var validUnit = (unit) => {
     throw new MetalBootstrapError("the OTLP collector must be independently supervised");
   }
 };
-function validateMetalBootstrapConfig(config) {
+function validateMetalBootstrapConfig(config, options = {}) {
   if (!config || typeof config !== "object")
     throw new MetalBootstrapError("metal bootstrap config must be an object");
   exactKeys2(config, ["kind", "metalHostname", "profile", "hostTelemetryEndpoint", "hostTelemetryUnit", "agentSeedFile"], "metal bootstrap config");
@@ -5277,7 +5277,7 @@ function validateMetalBootstrapConfig(config) {
   for (const image of Object.values(config.profile.images))
     if (!image.path.startsWith("/var/lib/forgezero/images/") || resolve5(image.path) !== image.path || /[\0\r\n]/.test(image.path))
       throw new MetalBootstrapError("every pinned guest image must use the fixed image directory");
-  if (config.profile.bunVersion !== SUPPORTED_BUN_VERSION || config.profile.bunReleaseSha256 !== SUPPORTED_BUN_RELEASE_SHA256 || config.profile.agentVersion !== VERSION) {
+  if (!options.allowHistoricalRelease && (config.profile.bunVersion !== SUPPORTED_BUN_VERSION || config.profile.bunReleaseSha256 !== SUPPORTED_BUN_RELEASE_SHA256 || config.profile.agentVersion !== VERSION)) {
     throw new MetalBootstrapError("metal guest runtime must use the package-owned Bun and Agent release coordinates");
   }
   let api;
@@ -5323,7 +5323,7 @@ function validateOwnerOnlyPath(path, requireRootOwner) {
     throw new MetalBootstrapError(requireRootOwner ? "private bootstrap file must be root-owned" : "private bootstrap file has an unexpected owner");
   }
 }
-function readMetalBootstrapConfig(path) {
+function readMetalBootstrapConfig(path, options = {}) {
   validateOwnerOnlyPath(path, false);
   const metadata = statSync(path);
   if (metadata.size < 2 || metadata.size > MAX_CONFIG_BYTES)
@@ -5334,7 +5334,7 @@ function readMetalBootstrapConfig(path) {
   } catch {
     throw new MetalBootstrapError("metal bootstrap config is not valid JSON");
   }
-  return validateMetalBootstrapConfig(parsed);
+  return validateMetalBootstrapConfig(parsed, options);
 }
 function planMetalBootstrap(config) {
   validateMetalBootstrapConfig(config);

package/dist/platform-fleet-verification.js

@@ -2125,7 +2125,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.71";
+var VERSION3 = "0.1.73";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";

package/dist/provision.js

@@ -2125,7 +2125,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.71";
+var VERSION3 = "0.1.73";
 
 // 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.71";
+export declare const VERSION = "0.1.73";

package/package.json

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