@forgezero/agent 0.1.63 → 0.1.65

package/README.md

@@ -281,14 +281,15 @@ import type { AgentUpdateOutcome, AgentUpdateReceipt, AgentUpdateRequest, AgentU
 <a id="forgezero-agent-bootstrap"></a>
 ## @forgezero/agent/bootstrap
 
-Typed one-time platform bootstrap and internal API-driven enrolled-compute activation contracts. Named value imports: BOOTSTRAP_STATE_PATH, PLATFORM_BOOTSTRAP_PROFILES, applyBootstrap, bootstrapIdentityDigest, bootstrapStatus, localBootstrapHost, planBootstrap, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig, validateEnrolledComputeBootstrapSecrets, validatePlatformBootstrapSecrets. Named type imports: BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult, BootstrapSecrets, BootstrapStatus, BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig, EnrolledComputeBootstrapSecrets, InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapProfile, PlatformBootstrapSecrets, PlatformEnrolmentSource. Import only the names used by this file.
+Typed one-time platform bootstrap and internal API-driven enrolled-compute activation contracts. Named value imports: BOOTSTRAP_STATE_PATH, PLATFORM_BOOTSTRAP_PROFILES, applyBootstrap, bootstrapIdentityDigest, bootstrapStatus, localBootstrapHost, planBootstrap, planBootstrapAgentInstall, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig, validateEnrolledComputeBootstrapSecrets, validatePlatformBootstrapSecrets. Named type imports: BootstrapAgentInstallPhase, BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult, BootstrapSecrets, BootstrapStatus, BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig, EnrolledComputeBootstrapSecrets, InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapProfile, PlatformBootstrapSecrets, PlatformEnrolmentSource. Import only the names used by this file.
 
 ```text
 import { BOOTSTRAP_STATE_PATH, PLATFORM_BOOTSTRAP_PROFILES, applyBootstrap, bootstrapIdentityDigest, bootstrapStatus, localBootstrapHost } from '@forgezero/agent/bootstrap';
-import { planBootstrap, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig, validateEnrolledComputeBootstrapSecrets, validatePlatformBootstrapSecrets } from '@forgezero/agent/bootstrap';
-import type { BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult, BootstrapSecrets } from '@forgezero/agent/bootstrap';
-import type { BootstrapStatus, BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig, EnrolledComputeBootstrapSecrets } from '@forgezero/agent/bootstrap';
-import type { InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapProfile, PlatformBootstrapSecrets, PlatformEnrolmentSource } from '@forgezero/agent/bootstrap';
+import { planBootstrap, planBootstrapAgentInstall, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig, validateEnrolledComputeBootstrapSecrets } from '@forgezero/agent/bootstrap';
+import { validatePlatformBootstrapSecrets } from '@forgezero/agent/bootstrap';
+import type { BootstrapAgentInstallPhase, BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult } from '@forgezero/agent/bootstrap';
+import type { BootstrapSecrets, BootstrapStatus, BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig } from '@forgezero/agent/bootstrap';
+import type { EnrolledComputeBootstrapSecrets, InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapProfile, PlatformBootstrapSecrets, PlatformEnrolmentSource } from '@forgezero/agent/bootstrap';
 ```
 
 <a id="forgezero-agent-bootstrap-bundle"></a>
@@ -319,12 +320,15 @@ 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. Named value imports: applyOperatorMetalBootstrap, applyOperatorPlatformBootstrap, planOperatorMetalBootstrap, planOperatorPlatformBootstrap, readOperatorMetalBootstrapRequest, readOperatorPlatformBootstrapRequest. Named type imports: OperatorCommand, OperatorCommandResult, OperatorMetalBootstrapMode, OperatorMetalBootstrapPlan, OperatorMetalBootstrapRequest, OperatorPlatformBootstrapMode, OperatorPlatformBootstrapOptions, OperatorPlatformBootstrapPlan, OperatorPlatformBootstrapRequest, OperatorSshHop. Import only the names used by this file.
+Pinned-host operator transport that stages owner-only handoffs and invokes the same typed platform bootstrap through the caller-approved SSH agent. Named value imports: applyOperatorMetalBootstrap, applyOperatorPlatformBootstrap, applyOperatorPlatformFleetBootstrap, createOperatorSshHop, planOperatorMetalBootstrap, planOperatorPlatformBootstrap, planOperatorPlatformFleetBootstrap, readOperatorMetalBootstrapRequest, readOperatorPlatformBootstrapFleetRequest, readOperatorPlatformBootstrapRequest, writeOperatorMetalBootstrapRequest, writeOperatorPlatformBootstrapFleetRequest, writeOperatorPlatformBootstrapRequest. Named type imports: OperatorCommand, OperatorCommandResult, OperatorMetalBootstrapMode, OperatorMetalBootstrapPlan, OperatorMetalBootstrapRequest, OperatorPlatformBootstrapFleetOutcome, OperatorPlatformBootstrapFleetPlan, OperatorPlatformBootstrapFleetRequest, OperatorPlatformBootstrapFleetResult, OperatorPlatformBootstrapMode, OperatorPlatformBootstrapOptions, OperatorPlatformBootstrapPlan, OperatorPlatformBootstrapRequest, OperatorSshHop. Import only the names used by this file.
 
 ```text
-import { applyOperatorMetalBootstrap, applyOperatorPlatformBootstrap, planOperatorMetalBootstrap, planOperatorPlatformBootstrap, readOperatorMetalBootstrapRequest, readOperatorPlatformBootstrapRequest } from '@forgezero/agent/operator-bootstrap';
-import type { OperatorCommand, OperatorCommandResult, OperatorMetalBootstrapMode, OperatorMetalBootstrapPlan, OperatorMetalBootstrapRequest, OperatorPlatformBootstrapMode } from '@forgezero/agent/operator-bootstrap';
-import type { OperatorPlatformBootstrapOptions, OperatorPlatformBootstrapPlan, OperatorPlatformBootstrapRequest, OperatorSshHop } from '@forgezero/agent/operator-bootstrap';
+import { applyOperatorMetalBootstrap, applyOperatorPlatformBootstrap, applyOperatorPlatformFleetBootstrap, createOperatorSshHop, planOperatorMetalBootstrap, planOperatorPlatformBootstrap } from '@forgezero/agent/operator-bootstrap';
+import { planOperatorPlatformFleetBootstrap, readOperatorMetalBootstrapRequest, readOperatorPlatformBootstrapFleetRequest, readOperatorPlatformBootstrapRequest, writeOperatorMetalBootstrapRequest, writeOperatorPlatformBootstrapFleetRequest } from '@forgezero/agent/operator-bootstrap';
+import { writeOperatorPlatformBootstrapRequest } from '@forgezero/agent/operator-bootstrap';
+import type { OperatorCommand, OperatorCommandResult, OperatorMetalBootstrapMode, OperatorMetalBootstrapPlan, OperatorMetalBootstrapRequest, OperatorPlatformBootstrapFleetOutcome } from '@forgezero/agent/operator-bootstrap';
+import type { OperatorPlatformBootstrapFleetPlan, OperatorPlatformBootstrapFleetRequest, OperatorPlatformBootstrapFleetResult, OperatorPlatformBootstrapMode, OperatorPlatformBootstrapOptions, OperatorPlatformBootstrapPlan } from '@forgezero/agent/operator-bootstrap';
+import type { OperatorPlatformBootstrapRequest, OperatorSshHop } from '@forgezero/agent/operator-bootstrap';
 ```
 
 ## @forgezero/agent/operator-bootstrap — Run the same typed platform bootstrap from an operator laptop

package/dist/agent-heartbeat.js

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

package/dist/bootstrap.d.ts

@@ -1,6 +1,8 @@
 import { type ProvisionPlan } from './cli/agent-install';
+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';
 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';
@@ -149,6 +151,7 @@ export interface BootstrapStatus {
     problems: string[];
 }
 export type InstalledBootstrapKind = 'compute' | 'metal';
+export type BootstrapAgentInstallPhase = 'bootstrap' | 'enrol' | 'bound';
 /** One host has one bootstrap authority. Dual state is never resolved by precedence. */
 export declare function resolveInstalledBootstrapKind(states: {
     compute: boolean;
@@ -174,7 +177,7 @@ export interface BootstrapHost {
     }): Promise<SoftwareCommandResult>;
     sleep?(milliseconds: number): Promise<void>;
     ensureSoftware(requirements: readonly SoftwareRequirement[]): Promise<unknown>;
-    installAgent(config: BootstrapConfig): Promise<ProvisionPlan>;
+    installAgent(config: BootstrapConfig, phase: BootstrapAgentInstallPhase): Promise<ProvisionPlan>;
 }
 export declare const BOOTSTRAP_STATE_PATH = "/var/lib/forgezero/bootstrap.json";
 export declare function validateBootstrapConfig(value: BootstrapConfig): BootstrapConfig;
@@ -185,4 +188,17 @@ export declare function applyBootstrap(input: BootstrapConfig, host?: BootstrapH
     fetcher?: typeof fetch;
 }): Promise<BootstrapResult>;
 export declare function readBootstrapConfig(path: string): BootstrapConfig;
+interface BootstrapAgentInitialBundle {
+    path: string;
+    manifestPath: string;
+    manifest: BootstrapBundleManifest;
+}
+/** Compose one real local Agent convergence without consulting mutable globals. */
+export declare function planBootstrapAgentInstall(config: BootstrapConfig, phase: BootstrapAgentInstallPhase, context: {
+    capabilities: Capabilities;
+    hasBinding: boolean;
+    hasEnrolCredential: boolean;
+    initialBundle?: BootstrapAgentInitialBundle;
+}): ProvisionPlan;
 export declare function localBootstrapHost(): BootstrapHost;
+export {};

package/dist/bootstrap.js

@@ -1396,7 +1396,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.63";
+var VERSION = "0.1.65";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -2045,17 +2045,16 @@ function agentUnit(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
-  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapSshPublicKeyPath && options.bootstrapTargetTelemetryEndpoint);
-  if ([
-    options.pullBootstrap,
-    options.bootstrapSshCredentialPath,
-    options.bootstrapSshPublicKeyPath,
-    options.bootstrapTargetTelemetryEndpoint
-  ].some(Boolean) && !bootstrapEnabled) {
-    throw new Error("bootstrap pull, SSH credential, public key and target telemetry endpoint must be supplied together");
+  const bootstrapIdentityEnabled = Boolean(options.bootstrapSshCredentialPath && options.bootstrapSshPublicKeyPath);
+  if (Boolean(options.bootstrapSshCredentialPath) !== Boolean(options.bootstrapSshPublicKeyPath)) {
+    throw new Error("bootstrap SSH credential and public key paths must be supplied together");
+  }
+  const bootstrapEnabled = Boolean(options.pullBootstrap);
+  if (bootstrapEnabled && (!bootstrapIdentityEnabled || !options.bootstrapTargetTelemetryEndpoint) || !bootstrapEnabled && options.bootstrapTargetTelemetryEndpoint) {
+    throw new Error("bootstrap pull, SSH identity and target telemetry endpoint must be supplied together");
   }
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
-  const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
+  const bootstrapSshCredentialPath = bootstrapIdentityEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
   const warpValues = [
     options.warpOrganization,
     options.warpClientIdCredentialPath,
@@ -2294,15 +2293,13 @@ function planProvision(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
-  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapSshPublicKeyPath && options.bootstrapTargetTelemetryEndpoint);
-  if ([
-    options.pullBootstrap,
-    options.bootstrapSshCredentialPath,
-    options.bootstrapSshPublicKeyPath,
-    options.bootstrapSshSourcePath,
-    options.bootstrapTargetTelemetryEndpoint
-  ].some(Boolean) && !bootstrapEnabled) {
-    throw new Error("bootstrap pull, SSH credential, public key and target telemetry endpoint must be supplied together");
+  const bootstrapIdentityEnabled = Boolean(options.bootstrapSshCredentialPath && options.bootstrapSshPublicKeyPath);
+  if (Boolean(options.bootstrapSshCredentialPath) !== Boolean(options.bootstrapSshPublicKeyPath) || options.bootstrapSshSourcePath && !bootstrapIdentityEnabled) {
+    throw new Error("bootstrap SSH credential and public key paths must be supplied together");
+  }
+  const bootstrapEnabled = Boolean(options.pullBootstrap);
+  if (bootstrapEnabled && (!bootstrapIdentityEnabled || !options.bootstrapTargetTelemetryEndpoint) || !bootstrapEnabled && options.bootstrapTargetTelemetryEndpoint) {
+    throw new Error("bootstrap pull, SSH identity and target telemetry endpoint must be supplied together");
   }
   const warpValues = [
     options.warpOrganization,
@@ -2312,13 +2309,13 @@ function planProvision(options) {
   const warpEnabled = warpValues.every(Boolean);
   if (warpValues.some(Boolean) && !warpEnabled)
     throw new Error("WARP configuration must be supplied together");
-  const enrolmentEnabled = Boolean(options.enrolTokenCredentialPath && options.enrolStatePath);
-  if (Boolean(options.enrolTokenCredentialPath) !== Boolean(options.enrolStatePath) || options.enrolTokenSourcePath && !enrolmentEnabled) {
-    throw new Error("direct enrolment credential and state paths must be supplied together");
+  const enrolmentEnabled = Boolean(options.enrolTokenCredentialPath);
+  if (options.enrolTokenCredentialPath && !options.enrolStatePath || options.enrolTokenSourcePath && (!options.enrolTokenCredentialPath || !options.enrolStatePath)) {
+    throw new Error("direct enrolment credential requires its durable state path");
   }
   const enrolTokenSourcePath = options.enrolTokenSourcePath ? systemdPath(options.enrolTokenSourcePath, "enrolment source") : undefined;
   const enrolTokenCredentialPath = enrolmentEnabled ? systemdPath(options.enrolTokenCredentialPath, "enrolment credential") : undefined;
-  const enrolStatePath = enrolmentEnabled ? systemdPath(options.enrolStatePath, "enrolment state") : undefined;
+  const enrolStatePath = options.enrolStatePath ? systemdPath(options.enrolStatePath, "enrolment state") : undefined;
   const enrolStateDir = enrolStatePath?.replace(/\/[^/]+$/, "");
   const sourceBinPath = options.sourceBinPath ? systemdPath(options.sourceBinPath, "agent source binary") : undefined;
   const binPath = options.binPath ? systemdPath(options.binPath, "agent binary") : undefined;
@@ -2330,8 +2327,8 @@ function planProvision(options) {
   const gitPublicKeyDir = gitPublicKeyPath?.replace(/\/[^/]+$/, "");
   const lifecycleProfilePath = lifecycleEnabled ? systemdPath(options.lifecycleProfilePath, "lifecycle profile") : undefined;
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
-  const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
-  const bootstrapSshPublicKeyPath = bootstrapEnabled ? systemdPath(options.bootstrapSshPublicKeyPath, "bootstrap SSH public key") : undefined;
+  const bootstrapSshCredentialPath = bootstrapIdentityEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
+  const bootstrapSshPublicKeyPath = bootstrapIdentityEnabled ? systemdPath(options.bootstrapSshPublicKeyPath, "bootstrap SSH public key") : undefined;
   const bootstrapSshSourcePath = options.bootstrapSshSourcePath ? systemdPath(options.bootstrapSshSourcePath, "bootstrap SSH private-key source") : undefined;
   const bootstrapSshPublicKeyDir = bootstrapSshPublicKeyPath?.replace(/\/[^/]+$/, "");
   const warpClientIdCredentialPath = warpEnabled ? systemdPath(options.warpClientIdCredentialPath, "WARP client-id credential") : undefined;
@@ -2431,7 +2428,7 @@ function planProvision(options) {
         step("Git deploy identity directory", { kind: "directories", directories: [{ path: gitPublicKeyDir, mode: 493, owner: "root", group: "root" }] }),
         step("unique encrypted Git deploy identity", { kind: "ensure-git-identity", credential: gitCredentialPath, publicKey: gitPublicKeyPath })
       ] : [],
-      ...bootstrapEnabled ? [
+      ...bootstrapIdentityEnabled ? [
         step("bootstrap SSH public identity directory", { kind: "directories", directories: [
           { path: bootstrapSshPublicKeyDir, mode: 493, owner: "root", group: "root" }
         ] }),
@@ -2467,6 +2464,10 @@ function planProvision(options) {
         { argv: ["/usr/bin/rm", "-f", "/etc/systemd/system/forgezero-deploy-runner.socket"] },
         { argv: ["/usr/bin/systemctl", "daemon-reload"] }
       ] })] : [],
+      ...enrolStatePath && !enrolmentEnabled ? [step("retire consumed enrolment unit", { kind: "commands", commands: [
+        { argv: ["/usr/bin/systemctl", "disable", "--now", "forgezero-agent-enrol.service"], acceptedExitCodes: [0, 1, 5] },
+        { argv: ["/usr/bin/rm", "-f", ENROLMENT_UNIT_PATH] }
+      ] })] : [],
       step("enable and converge services", { kind: "commands", commands: [
         { argv: ["/usr/bin/systemctl", "enable", ...enabledUnits] },
         { argv: ["/usr/bin/systemctl", "reset-failed", "forgezero-agent.service"], acceptedExitCodes: [0, 1] },
@@ -4181,7 +4182,15 @@ async function applyBootstrap(input, host = localBootstrapHost(), secrets, depen
   if (connectorCapabilities?.meshConnectorToken && !host.exists(WARP_CONNECTOR_CREDENTIAL)) {
     await seal(host, "CF_WARP_CONNECTOR_TOKEN", WARP_CONNECTOR_CREDENTIAL, connectorCapabilities.meshConnectorToken);
   }
-  await host.installAgent(config);
+  if (alreadyEnrolled) {
+    await host.installAgent(config, "bound");
+  } else if (config.kind === "platform") {
+    if (bootstrapManifest)
+      await host.installAgent(config, "bootstrap");
+  } else {
+    await host.installAgent(config, "enrol");
+    await host.installAgent(config, "bound");
+  }
   if (config.kind === "platform" && config.firewall.enabled) {
     await host.ensureSoftware(plan.software.filter(({ id }) => id === "ufw"));
   } else
@@ -4331,7 +4340,19 @@ async function applyBootstrap(input, host = localBootstrapHost(), secrets, depen
 `, 384);
       host.remove(config.bootstrapBundle.bundleFile);
       host.remove(config.bootstrapBundle.manifestFile);
-      await host.installAgent(config);
+    }
+    if (!alreadyEnrolled) {
+      await checked3(host, [
+        "curl",
+        "--fail",
+        "--silent",
+        "--show-error",
+        "--max-time",
+        "10",
+        `http://127.0.0.1:3000${runtime.healthPath}`
+      ], "release-one API health");
+      await host.installAgent(config, "enrol");
+      await host.installAgent(config, "bound");
     }
   }
   if (config.cloudflareHandoff) {
@@ -4500,6 +4521,65 @@ function readBootstrapConfig(path) {
   }
   return validateBootstrapConfig(strictBootstrapDocument(JSON.parse(readFileSync5(path, "utf8"))));
 }
+function planBootstrapAgentInstall(config, phase, context) {
+  const { capabilities, hasBinding, hasEnrolCredential, initialBundle } = context;
+  if (phase === "bootstrap") {
+    if (config.kind !== "platform" || hasBinding || !initialBundle) {
+      throw new Error("release-one Agent install requires an unbound platform host and verified bootstrap bundle");
+    }
+  } else if (phase === "enrol") {
+    if (hasBinding || !hasEnrolCredential) {
+      throw new Error("Agent enrolment requires one unbound host and its sealed one-use credential");
+    }
+  } else if (!hasBinding) {
+    throw new Error("bound Agent convergence requires durable enrolment state");
+  }
+  const bound = phase === "bound";
+  const enrolling = phase === "enrol";
+  const authenticated = enrolling || bound;
+  const bootstrapRunner = platformBootstrapRunner(config) || config.kind === "enrolled-compute" && Boolean(config.bootstrapRunner);
+  const options = {
+    capabilities,
+    socketPath: DEFAULT_SOCKET2,
+    seedPath: "/var/lib/forgezero/node.seed",
+    controlSocketPath: CONTROL_SOCKET,
+    repository: phase === "bootstrap" ? initialBundle.path : bound && config.kind === "enrolled-compute" ? config.repository : undefined,
+    branch: phase === "bootstrap" ? initialBundle.manifest.branch : bound && config.kind === "enrolled-compute" ? config.branch : undefined,
+    bootstrapBundlePath: phase === "bootstrap" ? initialBundle.path : undefined,
+    bootstrapBundleManifestPath: phase === "bootstrap" ? initialBundle.manifestPath : undefined,
+    profile: config.profile,
+    deployRoot: config.deployRoot ?? "/opt/forgezero",
+    deploymentCredentials: config.deploymentCredentials,
+    publicApiUrl: config.apiUrl,
+    gitCredentialPath: authenticated && config.kind === "enrolled-compute" && config.gitDeployKey ? "/etc/forgezero/creds/git-deploy-key.cred" : undefined,
+    gitPublicKeyPath: authenticated && config.kind === "enrolled-compute" && config.gitDeployKey ? "/etc/forgezero/git/deploy.pub" : undefined,
+    generateGitIdentity: authenticated && config.kind === "enrolled-compute" && config.gitDeployKey === true,
+    pullDeployments: bound,
+    pullMigrations: bound && config.kind === "platform",
+    pullBootstrap: bound && bootstrapRunner,
+    bootstrapSshCredentialPath: authenticated && bootstrapRunner ? BOOTSTRAP_SSH_CREDENTIAL : undefined,
+    bootstrapSshSourcePath: enrolling && config.kind === "enrolled-compute" ? config.bootstrapRunner?.sshPrivateKeyFile : undefined,
+    bootstrapSshPublicKeyPath: authenticated && bootstrapRunner ? BOOTSTRAP_SSH_PUBLIC_KEY : undefined,
+    bootstrapTargetTelemetryEndpoint: bound && bootstrapRunner ? platformBootstrapRunner(config) ? config.telemetryEndpoint : config.kind === "enrolled-compute" ? config.bootstrapRunner?.targetTelemetryEndpoint : undefined : undefined,
+    lifecycleProfilePath: bound && config.kind === "platform" ? LIFECYCLE_PROFILE : undefined,
+    enforceEgress: true,
+    nodeHostname: config.nodeHostname,
+    telemetryEndpoint: config.telemetryEndpoint,
+    binPath: "/usr/local/lib/forgezero/agent/fz-agent",
+    sourceBinPath: PACKAGED_AGENT_BIN,
+    ...enrolling ? {
+      enrolTokenCredentialPath: ENROL_CREDENTIAL,
+      enrolStatePath: "/var/lib/forgezero/enrolment.json"
+    } : bound ? { enrolStatePath: "/var/lib/forgezero/enrolment.json" } : {},
+    ...authenticated ? {
+      apiUrl: config.apiUrl,
+      project: config.kind === "enrolled-compute" ? config.realm : "platform",
+      environment: config.kind === "enrolled-compute" ? undefined : config.environment,
+      nodeLabel: config.kind === "enrolled-compute" ? config.nodeHostname : config.computeReference
+    } : {}
+  };
+  return planInstall(options);
+}
 function localBootstrapHost() {
   const execute = async (argv, options = {}) => {
     const child = Bun.spawn([...argv], { stdin: options.stdin === undefined ? "ignore" : "pipe", stdout: "pipe", stderr: "pipe" });
@@ -4547,10 +4627,10 @@ function localBootstrapHost() {
         throw new Error(`Agent software requirements failed: ${result.output.trim()}`);
       return result;
     },
-    async installAgent(config) {
+    async installAgent(config, phase) {
       const capabilities = await readCapabilities(localRunner);
-      const deployRoot = config.deployRoot ?? "/opt/forgezero";
       const hasBinding = existsSync5("/var/lib/forgezero/enrolment.json");
+      const hasEnrolCredential = existsSync5(ENROL_CREDENTIAL);
       const initialBundle = config.kind === "platform" && !existsSync5(BOOTSTRAP_RELEASE_EVIDENCE) ? {
         path: config.bootstrapBundle.bundleFile,
         manifestPath: config.bootstrapBundle.manifestFile,
@@ -4571,45 +4651,11 @@ function localBootstrapHost() {
         writeFileSync5(LIFECYCLE_PROFILE, `${JSON.stringify(lifecycle, null, 2)}
 `, { mode: 256 });
       }
-      const plan = planInstall({
+      const plan = planBootstrapAgentInstall(config, phase, {
         capabilities,
-        socketPath: DEFAULT_SOCKET2,
-        seedPath: "/var/lib/forgezero/node.seed",
-        controlSocketPath: "/run/forgezero/control.sock",
-        repository: initialBundle?.path ?? (config.kind === "enrolled-compute" ? config.repository : undefined),
-        branch: initialBundle?.manifest.branch ?? (config.kind === "enrolled-compute" ? config.branch : undefined),
-        bootstrapBundlePath: initialBundle?.path,
-        bootstrapBundleManifestPath: initialBundle?.manifestPath,
-        profile: config.kind === "platform" ? config.profile : config.profile,
-        deployRoot,
-        deploymentCredentials: config.deploymentCredentials,
-        publicApiUrl: config.apiUrl,
-        gitCredentialPath: config.kind === "enrolled-compute" && config.gitDeployKey ? "/etc/forgezero/creds/git-deploy-key.cred" : undefined,
-        gitPublicKeyPath: config.kind === "enrolled-compute" && config.gitDeployKey ? "/etc/forgezero/git/deploy.pub" : undefined,
-        generateGitIdentity: config.kind === "enrolled-compute" && config.gitDeployKey === true,
-        pullDeployments: hasBinding,
-        pullMigrations: config.kind === "platform" && hasBinding,
-        pullBootstrap: platformBootstrapRunner(config) || config.kind === "enrolled-compute" && Boolean(config.bootstrapRunner),
-        bootstrapSshCredentialPath: platformBootstrapRunner(config) || config.kind === "enrolled-compute" && config.bootstrapRunner ? BOOTSTRAP_SSH_CREDENTIAL : undefined,
-        bootstrapSshSourcePath: config.kind === "enrolled-compute" ? config.bootstrapRunner?.sshPrivateKeyFile : undefined,
-        bootstrapSshPublicKeyPath: platformBootstrapRunner(config) || config.kind === "enrolled-compute" && config.bootstrapRunner ? BOOTSTRAP_SSH_PUBLIC_KEY : undefined,
-        bootstrapTargetTelemetryEndpoint: platformBootstrapRunner(config) ? config.telemetryEndpoint : config.kind === "enrolled-compute" ? config.bootstrapRunner?.targetTelemetryEndpoint : undefined,
-        lifecycleProfilePath: config.kind === "platform" ? LIFECYCLE_PROFILE : undefined,
-        enforceEgress: true,
-        nodeHostname: config.nodeHostname,
-        telemetryEndpoint: config.telemetryEndpoint,
-        binPath: "/usr/local/lib/forgezero/agent/fz-agent",
-        sourceBinPath: PACKAGED_AGENT_BIN,
-        ...existsSync5(ENROL_CREDENTIAL) || hasBinding ? {
-          enrolTokenCredentialPath: existsSync5(ENROL_CREDENTIAL) ? ENROL_CREDENTIAL : undefined,
-          enrolStatePath: "/var/lib/forgezero/enrolment.json"
-        } : {},
-        ...hasBinding ? {
-          apiUrl: config.apiUrl,
-          project: config.kind === "enrolled-compute" ? config.realm : "platform",
-          environment: config.kind === "enrolled-compute" ? undefined : config.environment,
-          nodeLabel: config.kind === "enrolled-compute" ? config.nodeHostname : config.computeReference
-        } : {}
+        hasBinding,
+        hasEnrolCredential,
+        initialBundle
       });
       for (const unit of [{ path: plan.unitPath, unit: plan.unit }, ...plan.auxiliaryUnits]) {
         mkdirSync5(dirname6(unit.path), { recursive: true, mode: 493 });
@@ -4626,6 +4672,7 @@ export {
   validateBootstrapConfig,
   resolveInstalledBootstrapKind,
   readBootstrapConfig,
+  planBootstrapAgentInstall,
   planBootstrap,
   localBootstrapHost,
   bootstrapStatus,

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

@@ -84,6 +84,15 @@ export interface InstallOptions {
     nodeHostname?: string;
     telemetryEndpoint?: string;
 }
+export type GitIdentityInstallOptions = Pick<InstallOptions, 'gitCredentialPath' | 'gitPublicKeyPath' | 'generateGitIdentity'>;
+/**
+ * Resolve the optional compatibility Git identity from the explicit install
+ * environment. An ordinary Agent install must not load a credential merely
+ * because the CLI knows its conventional pathname: systemd treats every
+ * LoadCredentialEncrypted entry as required and refuses to start when that
+ * file does not exist.
+ */
+export declare function resolveGitIdentityInstallOptions(environment: Readonly<Record<string, string | undefined>>): GitIdentityInstallOptions;
 export declare function planInstall(options: InstallOptions): ProvisionPlan;
 /** Execute the same ordered plan the control plane executes over SSH. */
 export declare function applyPlan(plan: ProvisionPlan, run: (operation: CapabilityOperation | ProvisionOperation) => Promise<{

package/dist/deployment.d.ts

@@ -34,6 +34,8 @@ export interface DeploymentResult {
     definitionDigest: string;
     definitionVersion: number;
     profile: string;
+    /** Resolved only from the validated plan and its bounded inputs at this revision. */
+    resolvedTargets?: readonly ResolvedDeploymentTarget[];
     release: string;
     ok: boolean;
     phases: readonly RunResult[];
@@ -44,6 +46,15 @@ export interface DeploymentResult {
         };
     };
 }
+export interface ResolvedDeploymentTarget {
+    name: string;
+    profiles: readonly string[];
+    confidentialCompute: 'required' | 'preferred' | 'disabled';
+    labels: Readonly<Record<string, string>>;
+    minimum: number;
+    desired: number;
+    maximum: number;
+}
 /**
  * How the credential-bearing agent may read one server-owned Git source.
  * Secret values never appear in a deployment claim or checked-in pipeline.