@forgezero/agent 0.1.24 → 0.1.26

package/dist/cli/agent-install.d.ts

@@ -70,6 +70,7 @@ export interface InstallOptions {
     enrolTokenCredentialPath?: string;
     enrolStatePath?: string;
     nodeLabel?: string;
+    nodeHostname?: string;
 }
 export declare function planInstall(options: InstallOptions): ProvisionPlan;
 /** Execute the same ordered plan the control plane executes over SSH. */

package/dist/fz-agent.js

@@ -25,30 +25,44 @@ class CacheError extends Error {
 var DEFAULT_TTL_MS = 60000;
 var DEFAULT_MAX_STALE_MS = 300000;
 function createSecretCache(options) {
-  const entries = new Map;
+  let entries = new Map;
   const now = options.now ?? (() => Date.now());
   const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
   const maxStaleMs = options.maxStaleMs ?? DEFAULT_MAX_STALE_MS;
   let cursor = 0;
   let replicated = false;
   let lastSyncOkMs = now();
-  const loadScope = async () => {
+  const fetchScope = async () => {
+    const next = new Map;
     if (!options.list)
-      return { loaded: 0, failed: [] };
+      return { entries: next, loaded: 0, failed: [] };
     const names = await options.list();
     const failed = [];
-    let loaded = 0;
     for (const name of names) {
       try {
         const result = await options.fetch(name);
-        entries.set(name, { value: result.value, version: result.version, fetchedAtMs: now() });
-        loaded += 1;
+        next.set(name, { value: result.value, version: result.version, fetchedAtMs: now() });
       } catch {
         failed.push(name);
       }
     }
+    return { entries: next, loaded: next.size, failed };
+  };
+  const loadScope = async () => {
+    if (!options.list)
+      return { loaded: 0, failed: [] };
+    const snapshot = await fetchScope();
+    entries = snapshot.entries;
+    replicated = snapshot.failed.length === 0;
+    return { loaded: snapshot.loaded, failed: snapshot.failed };
+  };
+  const refreshScope = async () => {
+    const snapshot = await fetchScope();
+    if (snapshot.failed.length > 0) {
+      throw new CacheError("FETCH_FAILED", `Could not refresh ${snapshot.failed.length} assigned vault ${snapshot.failed.length === 1 ? "entry" : "entries"}.`);
+    }
+    entries = snapshot.entries;
     replicated = true;
-    return { loaded, failed };
   };
   return {
     names: () => [...entries.keys()],
@@ -82,13 +96,26 @@ function createSecretCache(options) {
       const result = await options.changes(cursor);
       if (result.resync) {
         const dropped = [...entries.keys()];
-        entries.clear();
+        if (options.list) {
+          await refreshScope();
+        } else {
+          entries.clear();
+        }
         cursor = 0;
         lastSyncOkMs = now();
-        if (options.list)
-          await loadScope();
         return { invalidated: dropped, cursor: 0, resync: true };
       }
+      if (options.list && result.changed.length > 0) {
+        const held = new Set(entries.keys());
+        await refreshScope();
+        cursor = result.version;
+        lastSyncOkMs = now();
+        return {
+          invalidated: result.changed.filter((name) => held.has(name) || entries.has(name)),
+          cursor,
+          resync: false
+        };
+      }
       const invalidated = [];
       for (const name of result.changed) {
         if (entries.delete(name))
@@ -1225,6 +1252,7 @@ async function enrolGuestIdentity(options) {
     label: options.label,
     gitDeployPublicKey: options.gitDeployPublicKey,
     privateNetworkAttachment: options.privateNetworkAttachment,
+    edgeHostname: options.edgeHostname?.trim() || undefined,
     publicKeys: {
       ed25519: options.keys.ed25519.publicKey,
       mlDsa: options.keys.mlDsa.publicKey
@@ -2717,17 +2745,23 @@ function validateLifecycleProfile(profile) {
   if (!Array.isArray(profile.apiUnits) || profile.apiUnits.length < 1 || profile.apiUnits.some((unit) => !unitPattern.test(unit))) {
     throw new Error("lifecycle profile needs one or more valid API service units");
   }
-  if (!unitPattern.test(profile.databaseUnit))
+  const databaseValues = [profile.databaseUnit, profile.databaseHealthUrl, profile.databasePorts];
+  if (databaseValues.some((value) => value !== undefined) && databaseValues.some((value) => value === undefined)) {
+    throw new Error("database lifecycle settings must be supplied together");
+  }
+  if (profile.databaseUnit && !unitPattern.test(profile.databaseUnit))
     throw new Error("lifecycle profile database unit is invalid");
   const apiUrl = new URL(profile.apiHealthUrl);
   if (apiUrl.protocol !== "http:" || !["127.0.0.1", "[::1]", "::1", "localhost"].includes(apiUrl.hostname)) {
     throw new Error("API health URL must be loopback HTTP");
   }
-  const databaseUrl = new URL(profile.databaseHealthUrl);
-  if (databaseUrl.protocol !== "http:" || !(["127.0.0.1", "[::1]", "::1", "localhost"].includes(databaseUrl.hostname) || privateIp(databaseUrl.hostname))) {
-    throw new Error("database health URL must be loopback or private HTTP");
+  if (profile.databaseHealthUrl) {
+    const databaseUrl = new URL(profile.databaseHealthUrl);
+    if (databaseUrl.protocol !== "http:" || !(["127.0.0.1", "[::1]", "::1", "localhost"].includes(databaseUrl.hostname) || privateIp(databaseUrl.hostname))) {
+      throw new Error("database health URL must be loopback or private HTTP");
+    }
   }
-  if (!Array.isArray(profile.databasePorts) || profile.databasePorts.length < 1 || profile.databasePorts.some((port) => !Number.isInteger(port) || port < 1 || port > 65535)) {
+  if (profile.databasePorts && (!Array.isArray(profile.databasePorts) || profile.databasePorts.length < 1 || profile.databasePorts.some((port) => !Number.isInteger(port) || port < 1 || port > 65535))) {
     throw new Error("lifecycle profile database ports are invalid");
   }
 }
@@ -2786,7 +2820,7 @@ async function executeLifecycleAction(profile, claim, exec = spawnLifecycleComma
           throw new Error("WARP is not connected");
       }
       for (const address of claim.peerPrivateAddresses) {
-        for (const port of profile.databasePorts)
+        for (const port of profile.databasePorts ?? [])
           await tcpProbe(address, port);
       }
       return {
@@ -2796,6 +2830,9 @@ async function executeLifecycleAction(profile, claim, exec = spawnLifecycleComma
       };
     }
     case "database-member-ready": {
+      if (!profile.databaseUnit || !profile.databaseHealthUrl) {
+        throw new Error("this workload has no controller-managed database lifecycle");
+      }
       await requireSuccess(exec, ["/usr/bin/systemctl", "is-active", profile.databaseUnit], "database service check");
       const response = await fetcher(profile.databaseHealthUrl, { signal: AbortSignal.timeout(5000) });
       if (!response.ok && response.status !== 401)
@@ -2812,7 +2849,12 @@ async function executeLifecycleAction(profile, claim, exec = spawnLifecycleComma
       await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits], "API drain");
       return { sourceDrained: true };
     case "source-stopped":
-      await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits, profile.databaseUnit], "source retirement");
+      await requireSuccess(exec, [
+        "/usr/bin/systemctl",
+        "stop",
+        ...profile.apiUnits,
+        ...profile.databaseUnit ? [profile.databaseUnit] : []
+      ], "source retirement");
       return { sourceStopped: true };
     default:
       throw new Error("unknown lifecycle action");
@@ -2940,7 +2982,7 @@ function materializeWarpMdm(options) {
 }
 
 // src/version.ts
-var VERSION = "0.1.24";
+var VERSION = "0.1.26";
 
 // src/index.ts
 function loadOrCreateSeed(path) {
@@ -3083,6 +3125,7 @@ if (import.meta.main) {
       nodeKey: nodeKey2,
       keys: keys2,
       label: process.env.FZ_NODE_LABEL,
+      edgeHostname: process.env.FZ_NODE_HOSTNAME,
       gitDeployPublicKey: process.env.FZ_GIT_PUBLIC_KEY_FILE ? readFileSync5(process.env.FZ_GIT_PUBLIC_KEY_FILE, "utf8").trim() : undefined,
       privateNetworkAttachment: privateNetworkAttachmentFromEnvironment()
     });
@@ -3302,6 +3345,7 @@ if (import.meta.main) {
       nodeKey,
       keys,
       label: process.env.FZ_NODE_LABEL,
+      edgeHostname: process.env.FZ_NODE_HOSTNAME,
       gitDeployPublicKey: process.env.FZ_GIT_PUBLIC_KEY_FILE ? readFileSync5(process.env.FZ_GIT_PUBLIC_KEY_FILE, "utf8").trim() : undefined,
       privateNetworkAttachment: privateNetworkAttachmentFromEnvironment()
     });

package/dist/fz.js

@@ -163,6 +163,7 @@ var systemdPath = (value, label) => {
     throw new Error(`invalid ${label} path`);
   return value;
 };
+var validNodeHostname = (value) => !value || value.length <= 253 && value === value.toLowerCase() && value.split(".").length >= 3 && value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
 function warpConfigUnit(options) {
   if (!options.warpOrganization || !/^[a-z0-9][a-z0-9-]{0,62}$/i.test(options.warpOrganization)) {
     throw new Error("WARP organization is invalid");
@@ -252,10 +253,14 @@ function agentEnrolmentUnit(options) {
   if (!options.apiUrl || !options.enrolTokenCredentialPath || !options.enrolStatePath) {
     throw new Error("direct enrolment needs API, credential and state paths");
   }
+  if (!validNodeHostname(options.nodeHostname))
+    throw new Error("node hostname is invalid");
   const bin = options.binPath ?? "fz-agent";
   const user = options.user ?? "forgezero";
   const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
   const label = options.nodeLabel ? `Environment=FZ_NODE_LABEL=${options.nodeLabel}
+` : "";
+  const hostname = options.nodeHostname ? `Environment=FZ_NODE_HOSTNAME=${options.nodeHostname}
 ` : "";
   const gitPublicKey = options.gitPublicKeyPath ? `Environment=FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}
 ` : "";
@@ -287,7 +292,7 @@ Environment=FZ_SEED_CREDENTIAL=agent-seed
 Environment=FZ_ENROL_TOKEN_CREDENTIAL=enrol-token
 Environment=FZ_ENROL_STATE_FILE=${options.enrolStatePath}
 Environment=FZ_API=${options.apiUrl}
-${label}${gitPublicKey}${networkAttachment}ExecStart=${bin} enrol
+${label}${hostname}${gitPublicKey}${networkAttachment}ExecStart=${bin} enrol
 # A '+' fixed command runs as root solely to remove the host-bound one-time
 # ciphertext. Tenant code and the agent never receive a privilege boundary.
 ExecStartPost=+/usr/bin/rm -f ${options.enrolTokenCredentialPath}
@@ -346,6 +351,8 @@ WantedBy=multi-user.target
 `;
 }
 function agentUnit(options) {
+  if (!validNodeHostname(options.nodeHostname))
+    throw new Error("node hostname is invalid");
   const bin = options.binPath ?? "fz-agent";
   const user = options.user ?? "forgezero";
   const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
@@ -403,6 +410,7 @@ function agentUnit(options) {
     options.environment ? `FZ_ENVIRONMENT=${options.environment}` : null,
     options.enrolStatePath ? `FZ_ENROL_STATE_FILE=${options.enrolStatePath}` : null,
     options.nodeLabel ? `FZ_NODE_LABEL=${options.nodeLabel}` : null,
+    options.nodeHostname ? `FZ_NODE_HOSTNAME=${options.nodeHostname}` : null,
     options.gitPublicKeyPath ? `FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}` : null,
     options.repository ? `FZ_DEPLOY_REPO=${options.repository}` : null,
     options.branch ? `FZ_DEPLOY_BRANCH=${options.branch}` : null,
@@ -966,7 +974,7 @@ async function resolveIdentity(selector, socketPath) {
 }
 
 // src/version.ts
-var VERSION = "0.1.24";
+var VERSION = "0.1.26";
 
 // src/cli/index.ts
 var DEFAULT_MODE = THRESHOLD_MODES[0].id;
@@ -1205,6 +1213,7 @@ async function cmdAgent(options, args) {
       enrolTokenCredentialPath,
       enrolStatePath,
       nodeLabel: process.env.FZ_NODE_LABEL,
+      nodeHostname: process.env.FZ_NODE_HOSTNAME,
       deployRoot: process.env.FZ_DEPLOY_ROOT ?? "/opt/forgezero"
     } : {},
     binPath: process.env.FZ_AGENT_BIN ?? "/usr/local/lib/forgezero/agent/fz-agent",

package/dist/guest-enrolment.d.ts

@@ -30,6 +30,8 @@ export interface GuestEnrolmentOptions {
     label?: string;
     gitDeployPublicKey?: string;
     privateNetworkAttachment?: GuestPrivateNetworkAttachment;
+    /** Stable API ingress identity; signed with the rest of the enrolment body. */
+    edgeHostname?: string;
     fetch?: (input: URL, init: RequestInit) => Promise<Response>;
     requestTimeoutMs?: number;
 }

package/dist/guest-enrolment.js

@@ -135,6 +135,7 @@ async function enrolGuestIdentity(options) {
     label: options.label,
     gitDeployPublicKey: options.gitDeployPublicKey,
     privateNetworkAttachment: options.privateNetworkAttachment,
+    edgeHostname: options.edgeHostname?.trim() || undefined,
     publicKeys: {
       ed25519: options.keys.ed25519.publicKey,
       mlDsa: options.keys.mlDsa.publicKey

package/dist/lifecycle-helper.d.ts

@@ -5,13 +5,13 @@ export interface LifecycleProfile {
     /** Root-owned systemd units whose normal stop path performs application drain. */
     apiUnits: readonly string[];
     /** Root-owned database service stopped only at the final retirement stage. */
-    databaseUnit: string;
+    databaseUnit?: string;
     /** Loopback health endpoint for the API on this compute. */
     apiHealthUrl: string;
     /** Loopback health endpoint for the database member on this compute. */
-    databaseHealthUrl: string;
+    databaseHealthUrl?: string;
     /** Ports that must be reachable on every signed controller-provided private peer. */
-    databasePorts: readonly number[];
+    databasePorts?: readonly number[];
 }
 export interface LifecycleCommandResult {
     exitCode: number;

package/dist/lifecycle-helper.js

@@ -22,17 +22,23 @@ function validateLifecycleProfile(profile) {
   if (!Array.isArray(profile.apiUnits) || profile.apiUnits.length < 1 || profile.apiUnits.some((unit) => !unitPattern.test(unit))) {
     throw new Error("lifecycle profile needs one or more valid API service units");
   }
-  if (!unitPattern.test(profile.databaseUnit))
+  const databaseValues = [profile.databaseUnit, profile.databaseHealthUrl, profile.databasePorts];
+  if (databaseValues.some((value) => value !== undefined) && databaseValues.some((value) => value === undefined)) {
+    throw new Error("database lifecycle settings must be supplied together");
+  }
+  if (profile.databaseUnit && !unitPattern.test(profile.databaseUnit))
     throw new Error("lifecycle profile database unit is invalid");
   const apiUrl = new URL(profile.apiHealthUrl);
   if (apiUrl.protocol !== "http:" || !["127.0.0.1", "[::1]", "::1", "localhost"].includes(apiUrl.hostname)) {
     throw new Error("API health URL must be loopback HTTP");
   }
-  const databaseUrl = new URL(profile.databaseHealthUrl);
-  if (databaseUrl.protocol !== "http:" || !(["127.0.0.1", "[::1]", "::1", "localhost"].includes(databaseUrl.hostname) || privateIp(databaseUrl.hostname))) {
-    throw new Error("database health URL must be loopback or private HTTP");
+  if (profile.databaseHealthUrl) {
+    const databaseUrl = new URL(profile.databaseHealthUrl);
+    if (databaseUrl.protocol !== "http:" || !(["127.0.0.1", "[::1]", "::1", "localhost"].includes(databaseUrl.hostname) || privateIp(databaseUrl.hostname))) {
+      throw new Error("database health URL must be loopback or private HTTP");
+    }
   }
-  if (!Array.isArray(profile.databasePorts) || profile.databasePorts.length < 1 || profile.databasePorts.some((port) => !Number.isInteger(port) || port < 1 || port > 65535)) {
+  if (profile.databasePorts && (!Array.isArray(profile.databasePorts) || profile.databasePorts.length < 1 || profile.databasePorts.some((port) => !Number.isInteger(port) || port < 1 || port > 65535))) {
     throw new Error("lifecycle profile database ports are invalid");
   }
 }
@@ -91,7 +97,7 @@ async function executeLifecycleAction(profile, claim, exec = spawnLifecycleComma
           throw new Error("WARP is not connected");
       }
       for (const address of claim.peerPrivateAddresses) {
-        for (const port of profile.databasePorts)
+        for (const port of profile.databasePorts ?? [])
           await tcpProbe(address, port);
       }
       return {
@@ -101,6 +107,9 @@ async function executeLifecycleAction(profile, claim, exec = spawnLifecycleComma
       };
     }
     case "database-member-ready": {
+      if (!profile.databaseUnit || !profile.databaseHealthUrl) {
+        throw new Error("this workload has no controller-managed database lifecycle");
+      }
       await requireSuccess(exec, ["/usr/bin/systemctl", "is-active", profile.databaseUnit], "database service check");
       const response = await fetcher(profile.databaseHealthUrl, { signal: AbortSignal.timeout(5000) });
       if (!response.ok && response.status !== 401)
@@ -117,7 +126,12 @@ async function executeLifecycleAction(profile, claim, exec = spawnLifecycleComma
       await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits], "API drain");
       return { sourceDrained: true };
     case "source-stopped":
-      await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits, profile.databaseUnit], "source retirement");
+      await requireSuccess(exec, [
+        "/usr/bin/systemctl",
+        "stop",
+        ...profile.apiUnits,
+        ...profile.databaseUnit ? [profile.databaseUnit] : []
+      ], "source retirement");
       return { sourceStopped: true };
     default:
       throw new Error("unknown lifecycle action");

package/dist/migration-pull.d.ts

@@ -1,5 +1,6 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 export type MigrationNetwork = 'private-lan' | 'cloudflare-warp';
+export type MigrationEvidenceProfile = 'forgezero-platform' | 'tenant-managed';
 export type MigrationAction = 'network-ready' | 'database-member-ready' | 'api-ready' | 'source-drained' | 'source-stopped';
 export interface MigrationEvidence {
     targetAgentReady?: boolean;
@@ -14,6 +15,7 @@ export interface RemoteMigrationClaim {
     migrationKey: string;
     action: MigrationAction;
     network: MigrationNetwork;
+    evidenceProfile?: MigrationEvidenceProfile;
     claimToken: string;
     claimExpiresAtTs: number;
     attempt: number;

package/dist/node-vault.js

@@ -10,30 +10,44 @@ class CacheError extends Error {
 var DEFAULT_TTL_MS = 60000;
 var DEFAULT_MAX_STALE_MS = 300000;
 function createSecretCache(options) {
-  const entries = new Map;
+  let entries = new Map;
   const now = options.now ?? (() => Date.now());
   const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
   const maxStaleMs = options.maxStaleMs ?? DEFAULT_MAX_STALE_MS;
   let cursor = 0;
   let replicated = false;
   let lastSyncOkMs = now();
-  const loadScope = async () => {
+  const fetchScope = async () => {
+    const next = new Map;
     if (!options.list)
-      return { loaded: 0, failed: [] };
+      return { entries: next, loaded: 0, failed: [] };
     const names = await options.list();
     const failed = [];
-    let loaded = 0;
     for (const name of names) {
       try {
         const result = await options.fetch(name);
-        entries.set(name, { value: result.value, version: result.version, fetchedAtMs: now() });
-        loaded += 1;
+        next.set(name, { value: result.value, version: result.version, fetchedAtMs: now() });
       } catch {
         failed.push(name);
       }
     }
+    return { entries: next, loaded: next.size, failed };
+  };
+  const loadScope = async () => {
+    if (!options.list)
+      return { loaded: 0, failed: [] };
+    const snapshot = await fetchScope();
+    entries = snapshot.entries;
+    replicated = snapshot.failed.length === 0;
+    return { loaded: snapshot.loaded, failed: snapshot.failed };
+  };
+  const refreshScope = async () => {
+    const snapshot = await fetchScope();
+    if (snapshot.failed.length > 0) {
+      throw new CacheError("FETCH_FAILED", `Could not refresh ${snapshot.failed.length} assigned vault ${snapshot.failed.length === 1 ? "entry" : "entries"}.`);
+    }
+    entries = snapshot.entries;
     replicated = true;
-    return { loaded, failed };
   };
   return {
     names: () => [...entries.keys()],
@@ -67,13 +81,26 @@ function createSecretCache(options) {
       const result = await options.changes(cursor);
       if (result.resync) {
         const dropped = [...entries.keys()];
-        entries.clear();
+        if (options.list) {
+          await refreshScope();
+        } else {
+          entries.clear();
+        }
         cursor = 0;
         lastSyncOkMs = now();
-        if (options.list)
-          await loadScope();
         return { invalidated: dropped, cursor: 0, resync: true };
       }
+      if (options.list && result.changed.length > 0) {
+        const held = new Set(entries.keys());
+        await refreshScope();
+        cursor = result.version;
+        lastSyncOkMs = now();
+        return {
+          invalidated: result.changed.filter((name) => held.has(name) || entries.has(name)),
+          cursor,
+          resync: false
+        };
+      }
       const invalidated = [];
       for (const name of result.changed) {
         if (entries.delete(name))

package/dist/provision.d.ts

@@ -119,6 +119,8 @@ export interface UnitOptions {
     enrolTokenCredentialPath?: string;
     enrolStatePath?: string;
     nodeLabel?: string;
+    /** Stable API ingress identity bound by the signed one-time enrolment. */
+    nodeHostname?: string;
 }
 export declare const DEPLOYMENT_RUNNER_USER = "forgezero-runner";
 export declare const DEPLOYMENT_GROUP = "forgezero-deploy";

package/dist/provision.js

@@ -55,6 +55,7 @@ var systemdPath = (value, label) => {
     throw new Error(`invalid ${label} path`);
   return value;
 };
+var validNodeHostname = (value) => !value || value.length <= 253 && value === value.toLowerCase() && value.split(".").length >= 3 && value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
 function warpConfigUnit(options) {
   if (!options.warpOrganization || !/^[a-z0-9][a-z0-9-]{0,62}$/i.test(options.warpOrganization)) {
     throw new Error("WARP organization is invalid");
@@ -144,10 +145,14 @@ function agentEnrolmentUnit(options) {
   if (!options.apiUrl || !options.enrolTokenCredentialPath || !options.enrolStatePath) {
     throw new Error("direct enrolment needs API, credential and state paths");
   }
+  if (!validNodeHostname(options.nodeHostname))
+    throw new Error("node hostname is invalid");
   const bin = options.binPath ?? "fz-agent";
   const user = options.user ?? "forgezero";
   const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
   const label = options.nodeLabel ? `Environment=FZ_NODE_LABEL=${options.nodeLabel}
+` : "";
+  const hostname = options.nodeHostname ? `Environment=FZ_NODE_HOSTNAME=${options.nodeHostname}
 ` : "";
   const gitPublicKey = options.gitPublicKeyPath ? `Environment=FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}
 ` : "";
@@ -179,7 +184,7 @@ Environment=FZ_SEED_CREDENTIAL=agent-seed
 Environment=FZ_ENROL_TOKEN_CREDENTIAL=enrol-token
 Environment=FZ_ENROL_STATE_FILE=${options.enrolStatePath}
 Environment=FZ_API=${options.apiUrl}
-${label}${gitPublicKey}${networkAttachment}ExecStart=${bin} enrol
+${label}${hostname}${gitPublicKey}${networkAttachment}ExecStart=${bin} enrol
 # A '+' fixed command runs as root solely to remove the host-bound one-time
 # ciphertext. Tenant code and the agent never receive a privilege boundary.
 ExecStartPost=+/usr/bin/rm -f ${options.enrolTokenCredentialPath}
@@ -238,6 +243,8 @@ WantedBy=multi-user.target
 `;
 }
 function agentUnit(options) {
+  if (!validNodeHostname(options.nodeHostname))
+    throw new Error("node hostname is invalid");
   const bin = options.binPath ?? "fz-agent";
   const user = options.user ?? "forgezero";
   const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
@@ -295,6 +302,7 @@ function agentUnit(options) {
     options.environment ? `FZ_ENVIRONMENT=${options.environment}` : null,
     options.enrolStatePath ? `FZ_ENROL_STATE_FILE=${options.enrolStatePath}` : null,
     options.nodeLabel ? `FZ_NODE_LABEL=${options.nodeLabel}` : null,
+    options.nodeHostname ? `FZ_NODE_HOSTNAME=${options.nodeHostname}` : null,
     options.gitPublicKeyPath ? `FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}` : null,
     options.repository ? `FZ_DEPLOY_REPO=${options.repository}` : null,
     options.branch ? `FZ_DEPLOY_BRANCH=${options.branch}` : null,

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.24";
+export declare const VERSION = "0.1.26";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/agent",
-	"version": "0.1.24",
+	"version": "0.1.26",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",