@forgezero/agent 0.1.38 → 0.1.39

package/README.md

@@ -15,7 +15,10 @@ fz --help
 
 The one public package installs both commands. Keeping bootstrap and the daemon
 in one version prevents a newly installed `fz` from provisioning a different
-agent protocol.
+agent protocol. Both executable artifacts bundle their ForgeZero runtime
+dependencies, so the constrained SSH bootstrap can transfer the reviewed pair
+to a new host without relying on a checkout, `node_modules`, or a second remote
+package-resolution step. Library subpath exports remain modular packages.
 
 The operator command starts browser-first platform genesis, inspects status,
 wraps processes, and installs the daemon. Genesis opens the one-use founder
@@ -43,13 +46,33 @@ script and no second implementation for tenant or platform machines:
 
 ```bash
 fz bootstrap platform                         # interactive plan, no mutation
-sudo fz bootstrap platform --apply            # initial DB+API or API-only host
+sudo fz bootstrap platform prepare --bootstrap-config ./platform.json --apply
+# Register the printed read-only deploy key. For genesis, run --apply on all
+# three Agency members concurrently; later agency:none joiners run alone.
+sudo fz bootstrap platform --bootstrap-config ./platform.json --apply
 sudo fz bootstrap tenant --bootstrap-config ./tenant.json --apply
 sudo fz bootstrap metal --bootstrap-config ./metal.json --apply
 sudo fz bootstrap status
 sudo fz bootstrap repair --bootstrap-config ./original.json --apply
 ```
 
+Platform database participation is explicit in the private JSON configuration.
+The three genesis nodes use `database.agency: "member"`; later DB+API joiners
+normally use `database.agency: "none"`, which starts a Coordinator and DBServer
+without adding a fourth Agency member. Enrolment is likewise explicit:
+`enrolment.source: "genesis-derived"` only for the offline genesis fleet, or
+`"api-token"` with `tokenFile` for every API-authorized later node. No behavior
+is inferred from a hostname or numeric suffix.
+
+Repair is not a second installation path: the CLI detects the installed
+platform/tenant or metal state and dispatches to that profile's validator. It
+fails closed if both state formats are present or neither is present. A private
+intent journal binds an interrupted first apply, and later repair refuses a
+config whose immutable host identity differs from the installed profile. Status checks the persisted
+identity record, both Agent sockets, profile-owned systemd units and, for a
+platform host, the active API health endpoint, nginx configuration and live
+Coordinator-mode evidence.
+
 Platform bootstrap supports an elastic Community ArangoDB 3.11.14 fleet. The
 first three database-capable computes establish the writable cluster; later
 database joiners and API-only computes use the same command with their typed
@@ -73,6 +96,8 @@ enters the API or Agent service environment:
 chmod 600 cloudflare-bootstrap.json cloudflare-management.token
 fz bootstrap platform cloudflare --bootstrap-config ./cloudflare-bootstrap.json
 fz bootstrap platform cloudflare --bootstrap-config ./cloudflare-bootstrap.json --apply
+# After every host is bootstrapped and publishing healthy KV state:
+fz bootstrap platform cloudflare verify --bootstrap-config ./cloudflare-handoff.json
 ```
 
 The reviewed JSON has `format: 1`, kind
@@ -83,8 +108,16 @@ and Access application name. Relative token, checkpoint and Worker project
 paths resolve beside the config file. Plan is offline. Apply creates/reuses one
 shared KV namespace, Worker and Access service token plus one Tunnel, Access
 application, ingress rule and DNS record per node. The command prints only
-resource IDs; connector, Access and requested runtime-token values stay in the
-atomically updated owner-only checkpoint for direct systemd-credential handoff.
+resource IDs and per-node handoff paths. The complete owner-only checkpoint
+stays on the operator laptop; `<checkpoint>.hosts/<node>.json` contains only
+that node's connector and required runtime capabilities and is the file copied
+to the host for `fz bootstrap platform`. Management tokens are never persisted.
+Each host pins cloudflared diagnostics to loopback and bootstrap/status requires
+the expected Tunnel UUID, a connector UUID, and all four documented edge
+connections—not merely an active process. The final `verify` is read-only: it
+uses the checkpoint's Access service credential only on the operator laptop to
+probe every origin, then probes every stable Worker domain without privileged
+headers. Its printed evidence contains hostnames and HTTP status codes only.
 
 ## What changes for an application
 

package/dist/agent-heartbeat.d.ts

@@ -11,6 +11,11 @@ export interface AgentObservation {
     architecture: string;
     mode: 'attested' | 'enrolled';
     update?: AgentUpdateReceipt;
+    deploymentIntake?: {
+        generation: number;
+        state: 'running' | 'paused';
+        appliedAtTs: number;
+    };
 }
 export interface AgentHeartbeatResponse {
     ok: true;
@@ -22,6 +27,10 @@ export interface AgentHeartbeatResponse {
         leaseExpiresAtTs: number;
         release: AgentRelease;
     };
+    deploymentIntake?: {
+        generation: number;
+        state: 'running' | 'paused';
+    };
 }
 export interface AgentHeartbeatOptions {
     apiUrl: string;
@@ -33,6 +42,10 @@ export interface AgentHeartbeatOptions {
     fetch?: (input: URL, init: RequestInit) => Promise<Response>;
     requestTimeoutMs?: number;
     observation?: () => AgentObservation;
+    /** Last applied server-owned deployment-intake generation, reported on the next heartbeat. */
+    deploymentIntakeObservation?: () => AgentObservation['deploymentIntake'];
+    /** Apply the authenticated desired state before any new deployment claim is allowed. */
+    applyDeploymentIntake?: (directive: NonNullable<AgentHeartbeatResponse['deploymentIntake']>) => Promise<void> | void;
     receiptPath?: string;
     now?: () => number;
     /** Stop new lifecycle/deploy claims and await current jobs before replacement. */

package/dist/agent-heartbeat.js

@@ -744,7 +744,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.38";
+var VERSION3 = "0.1.39";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");
@@ -770,7 +770,15 @@ async function heartbeatAgentOnce(options) {
   const update = observation.update ?? readAgentUpdateReceipt(options.receiptPath ?? AGENT_UPDATE_RECEIPT);
   if (update)
     observation = { ...observation, update };
+  const deploymentIntake = options.deploymentIntakeObservation?.();
+  if (deploymentIntake)
+    observation = { ...observation, deploymentIntake };
   const response = await postSignedNode(options, "v1/node/heartbeat", observation);
+  if (response.deploymentIntake !== undefined) {
+    if (!Number.isSafeInteger(response.deploymentIntake.generation) || response.deploymentIntake.generation < 0 || response.deploymentIntake.state !== "running" && response.deploymentIntake.state !== "paused")
+      throw new Error("agent heartbeat deployment-intake directive is invalid");
+    await options.applyDeploymentIntake?.(response.deploymentIntake);
+  }
   const desired = response.desiredAgentUpdate ?? (response.desiredAgentRelease ? {
     attemptId: `legacy:${response.desiredAgentRelease.version}`,
     leaseExpiresAtTs: Number.MAX_SAFE_INTEGER,

package/dist/bootstrap.d.ts

@@ -4,6 +4,8 @@ import { type PlatformSharedEnvironment } from './platform-bootstrap-runtime';
 export declare const PLATFORM_BOOTSTRAP_PROFILES: readonly ["platform-db-api", "platform-api"];
 export type PlatformBootstrapProfile = (typeof PLATFORM_BOOTSTRAP_PROFILES)[number];
 export type DatabaseBootstrapRole = 'master' | 'joiner' | 'none';
+export type DatabaseAgencyParticipation = 'member' | 'none';
+export type PlatformEnrolmentSource = 'genesis-derived' | 'api-token';
 export type BootstrapEnvironment = 'production' | 'development';
 export interface PlatformBootstrapConfig {
     kind: 'platform';
@@ -19,6 +21,8 @@ export interface PlatformBootstrapConfig {
     telemetryEndpoint: string;
     database: {
         role: DatabaseBootstrapRole;
+        /** Genesis master/joiners are Agency members; elastic joiners normally use `none`. */
+        agency: DatabaseAgencyParticipation;
         /** Cluster mode must remain default. Bootstrap verifies it and never mutates it. */
         serverMode: 'default';
         address?: string;
@@ -27,8 +31,12 @@ export interface PlatformBootstrapConfig {
         /** Owner/root-only file containing the shared 64-hex bootstrap code. */
         bootstrapSecretFile: string;
     };
-    /** Required for every post-genesis compute; initial n1..n3 derive their one-use capability. */
-    platformEnrolTokenFile?: string;
+    /** Explicit authority source; never inferred from a node number. */
+    enrolment: {
+        source: PlatformEnrolmentSource;
+        /** Required only for an API-issued post-genesis capability. */
+        tokenFile?: string;
+    };
     runtime: {
         environment: PlatformSharedEnvironment;
         serviceUser: string;
@@ -49,9 +57,9 @@ export interface PlatformBootstrapConfig {
     };
     /** Install the connector binary only. Resource creation belongs to attended Cloudflare bootstrap. */
     installCloudflared?: boolean;
-    /** Completed attended resource checkpoint; root seals only this node's runtime capabilities. */
+    /** Node-specific attended handoff; a host must never receive the fleet checkpoint. */
     cloudflareHandoff?: {
-        checkpointFile: string;
+        handoffFile: string;
         nodeName: string;
     };
 }
@@ -97,6 +105,13 @@ export interface BootstrapResult {
         inviteUrl: string;
     };
 }
+export interface PlatformBootstrapPreparation {
+    kind: 'platform';
+    prepared: true;
+    identityDigest: string;
+    gitPublicKey: string;
+    next: 'register this read-only deploy key, then run --apply concurrently on all three genesis Agency members';
+}
 export interface BootstrapStatus {
     initialized: boolean;
     kind?: BootstrapConfig['kind'];
@@ -104,6 +119,12 @@ export interface BootstrapStatus {
     services: Record<string, boolean>;
     problems: string[];
 }
+export type InstalledBootstrapKind = 'compute' | 'metal';
+/** One host has one bootstrap authority. Dual state is never resolved by precedence. */
+export declare function resolveInstalledBootstrapKind(states: {
+    compute: boolean;
+    metal: boolean;
+}): InstalledBootstrapKind | undefined;
 export interface BootstrapHost {
     uid(): number;
     exists(path: string): boolean;
@@ -122,11 +143,22 @@ export interface BootstrapHost {
     exec(argv: readonly string[], options?: {
         stdin?: string;
     }): Promise<SoftwareCommandResult>;
+    sleep?(milliseconds: number): Promise<void>;
     ensureSoftware(requirements: readonly SoftwareRequirement[]): Promise<unknown>;
     installAgent(config: BootstrapConfig, enrolTokenSourcePath?: string): Promise<ProvisionPlan>;
 }
+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;
+/**
+ * Install only the common Agent boundary and generate its machine-local Git
+ * identity. Private repositories cannot be deployed until the owner registers
+ * this public key, so pretending one monolithic first command can do both is a
+ * sequencing bug. The bound intent makes the later apply resumable and refuses
+ * a different config after this first privileged mutation.
+ */
+export declare function preparePlatformBootstrap(input: PlatformBootstrapConfig, host?: BootstrapHost): Promise<PlatformBootstrapPreparation>;
 export declare function bootstrapStatus(host?: BootstrapHost): Promise<BootstrapStatus>;
 export declare function applyBootstrap(input: BootstrapConfig, host?: BootstrapHost): Promise<BootstrapResult>;
 export declare function readBootstrapConfig(path: string): BootstrapConfig;