@forgezero/agent 0.1.62 → 0.1.64

package/dist/platform-bootstrap-runtime.d.ts

@@ -60,8 +60,6 @@ export interface PlatformSharedEnvironment {
         endpoint: string;
         producer: string;
     };
-    repository: string;
-    branch: string;
     deployProfile: string;
 }
 export declare function validatePlatformSharedEnvironment(input: PlatformSharedEnvironment): PlatformSharedEnvironment;

package/dist/platform-bootstrap-runtime.js

@@ -100,8 +100,6 @@ function validatePlatformSharedEnvironment(input) {
     databaseUser: input.databaseUser,
     sharedDirectory: input.sharedDirectory,
     seedSyncEpoch: input.seedSyncEpoch,
-    repository: input.repository,
-    branch: input.branch,
     deployProfile: input.deployProfile
   }))
     safeAtom(name, value);
@@ -184,8 +182,6 @@ function renderPlatformSharedEnvironment(input) {
     FZ_AGENT_OTLP_ENDPOINT: value.agentOtlpEndpoint,
     FZ_CUSTODIAN_EMAIL: value.custodianEmail ?? "",
     FZ_PROFILE: value.deployProfile,
-    FZ_REPO: value.repository,
-    FZ_BRANCH: value.branch,
     FZ_EMAIL_PROVIDER: value.email?.provider ?? "",
     FZ_SMTP_HOST: value.email?.provider === "smtp" ? value.email.host : "",
     FZ_SMTP_PORT: value.email?.provider === "smtp" ? String(value.email.port) : "",

package/dist/platform-fleet-verification.js

@@ -709,7 +709,8 @@ var SOFTWARE_CATALOG = [
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflare-warp", version: "2026.6.822.0-min", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
-  { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+  { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "git", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
   { requirement: { id: "bun", version: "1.3.14" } },
@@ -719,7 +720,8 @@ var UBUNTU_2604_X64 = [
   { requirement: { id: "cloudflared", version: "2026.7.3" } },
   { requirement: { id: "cloudflare-warp", version: "2026.6.822.0-min" } },
   { requirement: { id: "ufw", version: "ubuntu-26.04" } },
-  { requirement: { id: "openssh-client", version: "ubuntu-26.04" } }
+  { requirement: { id: "openssh-client", version: "ubuntu-26.04" } },
+  { requirement: { id: "git", version: "ubuntu-26.04" } }
 ];
 var path = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
 var DOCKER_DAEMON_PATH = "/etc/docker/daemon.json";
@@ -806,7 +808,7 @@ async function executeSoftwareOperation(operation) {
         const supported = observed && observed.some((part, index) => part > minimum[index] && observed.slice(0, index).every((prior, priorIndex) => prior === minimum[priorIndex])) || observed?.every((part, index) => part === minimum[index]);
         return { ...result, exitCode: result.exitCode === 0 && supported ? 0 : 1 };
       });
-    const binaries = software === "ufw" ? ["/usr/sbin/ufw"] : ["/usr/bin/ssh", "/usr/bin/scp", "/usr/bin/ssh-keyscan", "/usr/bin/ssh-keygen"];
+    const binaries = software === "ufw" ? ["/usr/sbin/ufw"] : software === "git" ? ["/usr/bin/git"] : ["/usr/bin/ssh", "/usr/bin/scp", "/usr/bin/ssh-keyscan", "/usr/bin/ssh-keygen"];
     try {
       binaries.forEach((binary) => accessSync(binary));
       return { exitCode: 0, output: "" };
@@ -814,7 +816,7 @@ async function executeSoftwareOperation(operation) {
       return { exitCode: 1, output: cause instanceof Error ? cause.message : String(cause) };
     }
   }
-  if (software === "docker" || software === "nginx" || software === "ufw" || software === "openssh-client") {
+  if (software === "docker" || software === "nginx" || software === "ufw" || software === "openssh-client" || software === "git") {
     const packageName = software === "openssh-client" ? "openssh-client" : software === "docker" ? "docker.io" : software;
     const installed = await aptInstall(packageName);
     if (installed.exitCode !== 0 || software !== "nginx" && software !== "docker")
@@ -914,7 +916,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "docker", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "docker", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client", "git"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };
@@ -2086,7 +2088,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.62";
+var VERSION3 = "0.1.64";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";
@@ -2215,7 +2217,11 @@ function agentEgressUnit(options) {
   const user = options.user ?? "forgezero";
   if (!/^[a-z_][a-z0-9_-]{0,30}$/.test(user))
     throw new Error("invalid Agent service user");
-  const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const bootstrapBundleEnabled = Boolean(options.bootstrapBundlePath && options.bootstrapBundleManifestPath);
+  if (Boolean(options.bootstrapBundlePath) !== Boolean(options.bootstrapBundleManifestPath) || bootstrapBundleEnabled && ![options.bootstrapBundlePath, options.bootstrapBundleManifestPath].every((path2) => path2.startsWith("/") && !/[\r\n\0:]/.test(path2))) {
+    throw new Error("bootstrap bundle and manifest must be supplied together as absolute paths");
+  }
+  const deploymentEnabled = Boolean(options.repository || bootstrapBundleEnabled || options.pullDeployments);
   const runnerLoopbackPorts = normalizeEgressTcpPorts(options.runnerLoopbackPorts ?? []);
   const runnerPublicTcpPorts = normalizeEgressTcpPorts(options.runnerPublicTcpPorts ?? DEFAULT_RUNNER_PUBLIC_TCP_PORTS);
   if (deploymentEnabled && runnerPublicTcpPorts.length < 1) {
@@ -2621,17 +2627,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,
@@ -2685,6 +2690,8 @@ function agentUnit(options) {
     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,
+    options.bootstrapBundlePath ? `FZ_BOOTSTRAP_BUNDLE=${options.bootstrapBundlePath}` : null,
+    options.bootstrapBundleManifestPath ? `FZ_BOOTSTRAP_BUNDLE_MANIFEST=${options.bootstrapBundleManifestPath}` : null,
     options.profile ? `FZ_DEPLOY_PROFILE=${options.profile}` : null,
     options.repository && options.branch ? `FZ_DEPLOY_KEY=${options.project ?? "platform"}:${options.environment ?? "production"}` : null,
     deploymentEnabled ? `FZ_DEPLOY_ROOT=${deployRoot}` : null,
@@ -2868,15 +2875,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,
@@ -2886,13 +2891,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;
@@ -2904,8 +2909,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;
@@ -3005,7 +3010,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" }
         ] }),
@@ -3041,6 +3046,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] },
@@ -3168,8 +3177,6 @@ function validatePlatformSharedEnvironment(input) {
     databaseUser: input.databaseUser,
     sharedDirectory: input.sharedDirectory,
     seedSyncEpoch: input.seedSyncEpoch,
-    repository: input.repository,
-    branch: input.branch,
     deployProfile: input.deployProfile
   }))
     safeAtom(name, value);
@@ -3252,8 +3259,6 @@ function renderPlatformSharedEnvironment(input) {
     FZ_AGENT_OTLP_ENDPOINT: value.agentOtlpEndpoint,
     FZ_CUSTODIAN_EMAIL: value.custodianEmail ?? "",
     FZ_PROFILE: value.deployProfile,
-    FZ_REPO: value.repository,
-    FZ_BRANCH: value.branch,
     FZ_EMAIL_PROVIDER: value.email?.provider ?? "",
     FZ_SMTP_HOST: value.email?.provider === "smtp" ? value.email.host : "",
     FZ_SMTP_PORT: value.email?.provider === "smtp" ? String(value.email.port) : "",
@@ -3592,21 +3597,21 @@ function planLocalOtlpProof(endpoint, collectorUnit) {
 }
 
 // src/platform-fleet-verification.ts
-import { lstatSync as lstatSync4 } from "node:fs";
+import { lstatSync as lstatSync5 } from "node:fs";
 
 // src/bootstrap.ts
-import { createHash as createHash5, createHmac as createHmac2, randomBytes as randomBytes2 } from "node:crypto";
+import { createHash as createHash6, createHmac as createHmac2, randomBytes as randomBytes3 } from "node:crypto";
 import {
-  chmodSync as chmodSync7,
-  existsSync as existsSync9,
-  lstatSync as lstatSync3,
-  mkdirSync as mkdirSync9,
-  readFileSync as readFileSync8,
-  renameSync as renameSync8,
-  rmSync as rmSync8,
-  writeFileSync as writeFileSync8
+  chmodSync as chmodSync8,
+  existsSync as existsSync10,
+  lstatSync as lstatSync4,
+  mkdirSync as mkdirSync10,
+  readFileSync as readFileSync9,
+  renameSync as renameSync9,
+  rmSync as rmSync9,
+  writeFileSync as writeFileSync9
 } from "node:fs";
-import { dirname as dirname8 } from "node:path";
+import { dirname as dirname9 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/cli/agent-install.ts
@@ -3918,6 +3923,58 @@ var UNIT = `/etc/systemd/system/${FORGEZERO_OTEL_COLLECTOR_UNIT}`;
 
 // src/bootstrap.ts
 import { DEFAULT_SOCKET as DEFAULT_SOCKET2 } from "@forgezero/vault";
+
+// src/bootstrap-bundle.ts
+import { createHash as createHash5, randomBytes as randomBytes2 } from "node:crypto";
+import {
+  chmodSync as chmodSync7,
+  createReadStream,
+  existsSync as existsSync9,
+  lstatSync as lstatSync3,
+  mkdirSync as mkdirSync9,
+  readFileSync as readFileSync8,
+  renameSync as renameSync8,
+  rmSync as rmSync8,
+  writeFileSync as writeFileSync8
+} from "node:fs";
+import { dirname as dirname8, isAbsolute, resolve as resolve6 } from "node:path";
+var BOOTSTRAP_BUNDLE_FORMAT = 1;
+var BOOTSTRAP_BUNDLE_KIND = "forgezero-api-git-bundle";
+var MAX_BOOTSTRAP_BUNDLE_BYTES = 512 * 1024 * 1024;
+var branchName = (value) => {
+  if (typeof value !== "string" || !/^[A-Za-z0-9](?:[A-Za-z0-9._/-]{0,126}[A-Za-z0-9])?$/.test(value) || value.includes("..") || value.includes("//") || value.startsWith("-")) {
+    throw new Error("bootstrap bundle branch is malformed");
+  }
+  return value;
+};
+function parseBootstrapBundleManifest(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("bootstrap bundle manifest must be an object");
+  const source = value;
+  const allowed = ["format", "kind", "branch", "revision", "sha256", "bytes", "createdAt"];
+  const unknown = Object.keys(source).filter((key) => !allowed.includes(key));
+  if (unknown.length)
+    throw new Error(`bootstrap bundle manifest contains unknown field ${unknown[0]}`);
+  if (source.format !== BOOTSTRAP_BUNDLE_FORMAT || source.kind !== BOOTSTRAP_BUNDLE_KIND) {
+    throw new Error("bootstrap bundle manifest format is unsupported");
+  }
+  branchName(source.branch);
+  if (typeof source.revision !== "string" || !/^[a-f0-9]{40}$/.test(source.revision)) {
+    throw new Error("bootstrap bundle revision must be an exact lowercase Git commit");
+  }
+  if (typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256)) {
+    throw new Error("bootstrap bundle digest is malformed");
+  }
+  if (!Number.isSafeInteger(source.bytes) || Number(source.bytes) < 1 || Number(source.bytes) > MAX_BOOTSTRAP_BUNDLE_BYTES) {
+    throw new Error("bootstrap bundle size is outside the supported boundary");
+  }
+  if (typeof source.createdAt !== "string" || Number.isNaN(Date.parse(source.createdAt))) {
+    throw new Error("bootstrap bundle creation time is malformed");
+  }
+  return source;
+}
+
+// src/bootstrap.ts
 var platformBootstrapRunner = (config) => config.kind === "platform" && config.database.role === "master";
 var BOOTSTRAP_STATE_PATH = "/var/lib/forgezero/bootstrap.json";
 var STATE_PATH = BOOTSTRAP_STATE_PATH;
@@ -3934,6 +3991,7 @@ var SEED_CREDENTIAL = `${CREDS}/seed-sync-root.cred`;
 var BACKUP_RECOVERY_CREDENTIAL = `${CREDS}/backup-recovery-root.cred`;
 var BOOTSTRAP_SSH_CREDENTIAL = `${CREDS}/bootstrap-ssh-key.cred`;
 var BOOTSTRAP_SSH_PUBLIC_KEY = "/etc/forgezero/bootstrap/runner.pub";
+var BOOTSTRAP_RELEASE_EVIDENCE = "/var/lib/forgezero/bootstrap-release.json";
 var LIFECYCLE_PROFILE = "/etc/forgezero/lifecycle.json";
 var CONTROL_SOCKET = "/run/forgezero/control.sock";
 var CLOUDFLARED_METRICS_ADDRESS = "127.0.0.1:20241";
@@ -4110,6 +4168,65 @@ async function bootstrapStatus(host = localBootstrapHost()) {
     problems.push("durable Agent enrolment state is missing");
   return { initialized: problems.length === 0, kind: state.kind, profile: state.profile, services, problems };
 }
+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 (argv2, options = {}) => {
     const child = Bun.spawn([...argv2], { stdin: options.stdin === undefined ? "ignore" : "pipe", stdout: "pipe", stderr: "pipe" });
@@ -4126,19 +4243,19 @@ function localBootstrapHost() {
   };
   return {
     uid: () => process.getuid?.() ?? -1,
-    exists: existsSync9,
-    read: (path2) => readFileSync8(path2, "utf8"),
+    exists: existsSync10,
+    read: (path2) => readFileSync9(path2, "utf8"),
     write(path2, content, mode) {
-      mkdirSync9(dirname8(path2), { recursive: true, mode: 493 });
+      mkdirSync10(dirname9(path2), { recursive: true, mode: 493 });
       const temporary = `${path2}.next.${process.pid}`;
-      writeFileSync8(temporary, content, { mode });
-      chmodSync7(temporary, mode);
-      renameSync8(temporary, path2);
+      writeFileSync9(temporary, content, { mode });
+      chmodSync8(temporary, mode);
+      renameSync9(temporary, path2);
     },
-    mkdir: (path2, mode) => mkdirSync9(path2, { recursive: true, mode }),
-    remove: (path2) => rmSync8(path2, { force: true }),
+    mkdir: (path2, mode) => mkdirSync10(path2, { recursive: true, mode }),
+    remove: (path2) => rmSync9(path2, { force: true }),
     inspect(path2) {
-      const value = lstatSync3(path2);
+      const value = lstatSync4(path2);
       return { regular: value.isFile(), symbolic: value.isSymbolicLink(), uid: value.uid, mode: value.mode, links: value.nlink, size: value.size };
     },
     exec: execute,
@@ -4157,10 +4274,15 @@ 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 = config.kind === "enrolled-compute" || existsSync9(ENROL_CREDENTIAL) || existsSync9("/var/lib/forgezero/enrolment.json");
+      const hasBinding = existsSync10("/var/lib/forgezero/enrolment.json");
+      const hasEnrolCredential = existsSync10(ENROL_CREDENTIAL);
+      const initialBundle = config.kind === "platform" && !existsSync10(BOOTSTRAP_RELEASE_EVIDENCE) ? {
+        path: config.bootstrapBundle.bundleFile,
+        manifestPath: config.bootstrapBundle.manifestFile,
+        manifest: parseBootstrapBundleManifest(JSON.parse(readFileSync9(config.bootstrapBundle.manifestFile, "utf8")))
+      } : undefined;
       if (config.kind === "platform") {
         const lifecycle = config.database.role === "none" ? {
           apiUnits: ["forgezero@blue.service", "forgezero@green.service"],
@@ -4172,49 +4294,19 @@ function localBootstrapHost() {
           databaseHealthUrl: `http://${config.database.address}:8529/_api/version`,
           databasePorts: [8529]
         };
-        mkdirSync9(dirname8(LIFECYCLE_PROFILE), { recursive: true, mode: 493 });
-        writeFileSync8(LIFECYCLE_PROFILE, `${JSON.stringify(lifecycle, null, 2)}
+        mkdirSync10(dirname9(LIFECYCLE_PROFILE), { recursive: true, mode: 493 });
+        writeFileSync9(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: config.repository,
-        branch: config.branch,
-        profile: config.kind === "platform" ? config.profile : config.profile,
-        deployRoot,
-        deploymentCredentials: config.deploymentCredentials,
-        publicApiUrl: config.apiUrl,
-        gitCredentialPath: "/etc/forgezero/creds/git-deploy-key.cred",
-        gitPublicKeyPath: "/etc/forgezero/git/deploy.pub",
-        generateGitIdentity: 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,
-        ...hasBinding ? {
-          enrolTokenCredentialPath: ENROL_CREDENTIAL,
-          enrolStatePath: "/var/lib/forgezero/enrolment.json",
-          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 unit2 of [{ path: plan.unitPath, unit: plan.unit }, ...plan.auxiliaryUnits]) {
-        mkdirSync9(dirname8(unit2.path), { recursive: true, mode: 493 });
-        writeFileSync8(unit2.path, unit2.unit, { mode: 420 });
+        mkdirSync10(dirname9(unit2.path), { recursive: true, mode: 493 });
+        writeFileSync9(unit2.path, unit2.unit, { mode: 420 });
       }
       await applyPlan(plan, localRunner);
       return plan;
@@ -4228,7 +4320,7 @@ var localRuntime = () => ({
   bootstrapStatus: () => bootstrapStatus(),
   characterDevice(path2) {
     try {
-      return lstatSync4(path2).isCharacterDevice();
+      return lstatSync5(path2).isCharacterDevice();
     } catch {
       return false;
     }

package/dist/provision.d.ts

@@ -92,6 +92,9 @@ export interface UnitOptions {
     controlSocketPath?: string;
     repository?: string;
     branch?: string;
+    /** Attended release-generation-one artifact; both coordinates are required together. */
+    bootstrapBundlePath?: string;
+    bootstrapBundleManifestPath?: string;
     profile?: string;
     deployRoot?: string;
     publicApiUrl?: string;
@@ -164,7 +167,7 @@ export declare const WARP_SERVICE_DROP_IN_PATH = "/etc/systemd/system/warp-svc.s
 export declare const AGENT_EGRESS_UNIT_PATH = "/etc/systemd/system/forgezero-agent-egress.service";
 export declare const DEFAULT_RUNNER_PUBLIC_TCP_PORTS: readonly [443];
 /** Root-owned policy monitor. The credential-bearing Agent is bound to it. */
-export declare function agentEgressUnit(options: Pick<UnitOptions, 'binPath' | 'user' | 'repository' | 'pullDeployments' | 'runnerLoopbackPorts' | 'runnerPublicTcpPorts'>): string;
+export declare function agentEgressUnit(options: Pick<UnitOptions, 'binPath' | 'user' | 'repository' | 'pullDeployments' | 'bootstrapBundlePath' | 'bootstrapBundleManifestPath' | 'runnerLoopbackPorts' | 'runnerPublicTcpPorts'>): string;
 /** Root may execute only package-owned OS strategies selected by id + version. */
 export declare function softwareHelperUnit(options: Pick<UnitOptions, 'binPath' | 'deployRoot'>): string;
 /** Fixed root boundary for verified, health-gated Agent replacement. */