@forgezero/agent 0.1.11 → 0.1.13

package/dist/metal-helper-socket.js

@@ -181,6 +181,7 @@ var modeFor = (capabilities) => capabilities.snpGuest ? "attested" : "enrolled";
 var reasonFor = (mode) => mode === "attested" ? "SEV-SNP guest device present, so the agent can prove what it is running and the platform can refuse it if the measurement is wrong." : "No SEV-SNP guest device. The agent authenticates with its enrolment token and hybrid Ed25519 + ML-DSA signature — weaker than attestation, stronger than an API key in the application.";
 var DEPLOYMENT_RUNNER_USER = "forgezero-runner";
 var DEPLOYMENT_GROUP = "forgezero-deploy";
+var VAULT_GROUP = "forgezero-vault";
 var DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
 var DEPLOYMENT_RUNNER_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.socket";
 var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
@@ -350,7 +351,7 @@ function agentUnit(options) {
 `);
   const snpDevice = options.mode === "attested" ? `DevicePolicy=closed
 DeviceAllow=/dev/sev-guest rw` : "";
-  const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${user} /dev/sev-guest
+  const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${VAULT_GROUP} /dev/sev-guest
 ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
 ` : "";
   return `[Unit]
@@ -361,7 +362,7 @@ ${deploymentDependency}
 [Service]
 Type=simple
 User=${user}
-Group=${user}
+Group=${VAULT_GROUP}
 ${deploymentGroup}
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
 ${gitCredential}${projectCredentials}${projectCredentials ? `
@@ -380,8 +381,8 @@ LimitCORE=0
 # scope. So it lives in a directory systemd creates with a known owner rather
 # than wherever the process happened to have write access.
 RuntimeDirectory=forgezero
-RuntimeDirectoryMode=0710
-UMask=0077
+RuntimeDirectoryMode=0750
+UMask=0007
 
 # Tenant-controlled commands execute in forgezero-deploy-runner.service. This
 # credential-bearing process never needs to cross a privilege boundary.
@@ -448,6 +449,10 @@ function planProvision(options) {
     socketPath: options.socketPath,
     user,
     steps: [
+      {
+        label: "vault socket access group",
+        command: `groupadd --system ${VAULT_GROUP} || true`
+      },
       ...sourceBinPath && binPath ? [{
         label: "root-owned agent runtime",
         command: `install -d -o root -g root -m 0755 ${binPath.replace(/\/[^/]+$/, "")}; ` + `install -o root -g root -m 0755 ${sourceBinPath} ${binPath}`
@@ -460,6 +465,10 @@ function planProvision(options) {
         label: "service account",
         command: `useradd --system --no-create-home --shell /usr/sbin/nologin ${user} || true`
       },
+      {
+        label: "bind service account to vault group",
+        command: `usermod -g ${VAULT_GROUP} ${user}`
+      },
       ...deploymentEnabled ? [{
         label: "credential-free deployment account",
         command: `useradd --system --no-create-home --shell /usr/sbin/nologin --gid ${DEPLOYMENT_GROUP} ${DEPLOYMENT_RUNNER_USER} || true; ` + `usermod -a -G ${DEPLOYMENT_GROUP} ${user}`
@@ -523,6 +532,21 @@ function planProvision(options) {
   };
 }
 
+// src/ubuntu.ts
+var SUPPORTED_GUEST_IMAGE = Object.freeze({
+  key: "ubuntu-resolute-20260731",
+  family: "ubuntu-26.04",
+  version: "2026-07-31",
+  label: "Ubuntu 26.04 LTS Resolute",
+  url: "https://cloud-images.ubuntu.com/releases/resolute/release-20260731/ubuntu-26.04-server-cloudimg-amd64.img",
+  sha256: "9dc7c5363c0146a08ba0c9aa834d82c2c6dfbb1c471ad9a2f0aba1189e21be05"
+});
+function assertSupportedGuestImage(imageKey) {
+  if (imageKey !== SUPPORTED_GUEST_IMAGE.key) {
+    throw new Error(`unsupported guest image ${imageKey}; ForgeZero currently supports only ${SUPPORTED_GUEST_IMAGE.key}`);
+  }
+}
+
 // src/metal-provision.ts
 import { createHash } from "node:crypto";
 import {
@@ -530,6 +554,7 @@ import {
   mkdirSync,
   readFileSync,
   readdirSync,
+  rmSync,
   statSync,
   unlinkSync,
   writeFileSync
@@ -584,6 +609,10 @@ function validateMetalProfile(profile) {
       throw new MetalProvisionError("metal paths must be absolute");
   }
   new URL(profile.apiUrl);
+  const imageKeys = Object.keys(profile.images);
+  if (imageKeys.length !== 1 || imageKeys[0] !== SUPPORTED_GUEST_IMAGE.key || profile.images[SUPPORTED_GUEST_IMAGE.key]?.sha256 !== SUPPORTED_GUEST_IMAGE.sha256) {
+    throw new MetalProvisionError(`metal profile must contain only the pinned ${SUPPORTED_GUEST_IMAGE.key} image contract`);
+  }
   if (!Array.isArray(profile.cpuPools) || profile.cpuPools.length === 0) {
     throw new MetalProvisionError("at least one exclusive CPU pool is required");
   }
@@ -649,6 +678,21 @@ function allocateAddress(profile, computeKey, rows) {
   }
   throw new MetalProvisionError("guest address range is full");
 }
+function requestedAddress(profile, claim, rows) {
+  if (!claim.spec.guestAddress)
+    return allocateAddress(profile, claim.computeKey, rows);
+  if (!claim.spec.guestAddress.startsWith(`${profile.subnetPrefix}.`)) {
+    throw new MetalProvisionError("requested guest address is outside the metal profile");
+  }
+  const last = Number(claim.spec.guestAddress.slice(profile.subnetPrefix.length + 1));
+  if (!Number.isInteger(last) || last < profile.addressStart || last > profile.addressEnd) {
+    throw new MetalProvisionError("requested guest address is outside the allocatable range");
+  }
+  const occupied = rows.find((row) => row.address === claim.spec.guestAddress && row.computeKey !== claim.computeKey);
+  if (occupied)
+    throw new MetalProvisionError("requested guest address is already allocated");
+  return claim.spec.guestAddress;
+}
 function allocateCpuPool(profile, claim, rows) {
   const prior = rows.find((row) => row.computeKey === claim.computeKey);
   if (prior) {
@@ -659,6 +703,15 @@ function allocateCpuPool(profile, claim, rows) {
     return retained;
   }
   const used = new Set(rows.map((row) => row.cpuPoolKey));
+  if (claim.spec.cpuPoolKey) {
+    const requested = profile.cpuPools.find((pool) => pool.key === claim.spec.cpuPoolKey);
+    if (!requested || used.has(requested.key)) {
+      throw new MetalProvisionError("requested CPU pool is unavailable");
+    }
+    if (requested.physicalCores < claim.spec.physicalCores || membersOfLinuxList(requested.cpus, "CPU").length < claim.spec.vcpu)
+      throw new MetalProvisionError("requested CPU pool cannot satisfy this guest");
+    return requested;
+  }
   const candidates = profile.cpuPools.filter((pool) => !used.has(pool.key) && pool.physicalCores >= claim.spec.physicalCores && membersOfLinuxList(pool.cpus, "CPU").length >= claim.spec.vcpu).sort((left, right) => left.physicalCores - right.physicalCores || membersOfLinuxList(left.cpus, "CPU").length - membersOfLinuxList(right.cpus, "CPU").length || left.key.localeCompare(right.key));
   const selected = candidates[0];
   if (!selected)
@@ -671,7 +724,7 @@ var yamlFile = (path, content, permissions) => `  - path: ${JSON.stringify(path)
     encoding: b64
     content: ${base64(content)}
 `;
-function guestBootstrapScript(profile, attested = Boolean(profile.confidential)) {
+function guestBootstrapScript(profile, attested = Boolean(profile.confidential), hasEnrolment = true) {
   const agentBun = "/usr/local/lib/forgezero/bun";
   const attestationSetup = attested ? `# The report device is not part of the encryption path, so a guest can appear
 # healthy and encrypted while attestation is silently impossible. Install and
@@ -684,7 +737,9 @@ test -c /dev/sev-guest
 ` : "";
   return `#!/usr/bin/env bash
 set -Eeuo pipefail
-${attestationSetup}useradd --system --no-create-home --shell /usr/sbin/nologin forgezero-agent 2>/dev/null || true
+${attestationSetup}groupadd --system ${VAULT_GROUP} 2>/dev/null || true
+useradd --system --no-create-home --shell /usr/sbin/nologin forgezero-agent 2>/dev/null || true
+usermod -g ${VAULT_GROUP} forgezero-agent
 groupadd --system ${DEPLOYMENT_GROUP} 2>/dev/null || true
 useradd --system --no-create-home --shell /usr/sbin/nologin --gid ${DEPLOYMENT_GROUP} ${DEPLOYMENT_RUNNER_USER} 2>/dev/null || true
 usermod -a -G ${DEPLOYMENT_GROUP} forgezero-agent
@@ -695,13 +750,13 @@ install -d -o root -g root -m 0755 /opt/forgezero
 install -d -o root -g ${DEPLOYMENT_GROUP} -m 3770 /opt/forgezero/releases
 install -d -o forgezero-agent -g forgezero-agent -m 0700 /opt/forgezero/cache /opt/forgezero/home
 install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0700 /opt/forgezero/runner-home /opt/forgezero/runner-home/cache
-if [[ -s /run/forgezero-enrol-token ]]; then
+${hasEnrolment ? `if [[ -s /run/forgezero-enrol-token ]]; then
   systemd-creds encrypt --name=enrol-token /run/forgezero-enrol-token /var/lib/forgezero/enrol-token.cred
   rm -f /run/forgezero-enrol-token
 fi
 chown root:root /var/lib/forgezero/enrol-token.cred
 chmod 0400 /var/lib/forgezero/enrol-token.cred
-if [[ ! -x /usr/local/bin/bun ]]; then
+` : ""}if [[ ! -x /usr/local/bin/bun ]]; then
   curl -fsSL https://bun.sh/install -o /run/fz-bun-install
   printf '%s  %s
 ' '${profile.bunInstallerSha256}' /run/fz-bun-install | sha256sum -c -
@@ -740,8 +795,8 @@ systemctl daemon-reload
 systemctl enable --now forgezero-deploy-runner.socket forgezero-deploy-runner.service forgezero-agent.service
 `;
 }
-function guestAgentUnit(profile, name, attested = Boolean(profile.confidential)) {
-  const attestationPrepare = attested ? `ExecStartPre=+/bin/chgrp forgezero-agent /dev/sev-guest
+function guestAgentUnit(profile, name, attested = Boolean(profile.confidential), pull = true) {
+  const attestationPrepare = attested ? `ExecStartPre=+/bin/chgrp ${VAULT_GROUP} /dev/sev-guest
 ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
 ` : "";
   const attestationDevice = attested ? `DevicePolicy=closed
@@ -756,7 +811,7 @@ Requires=forgezero-deploy-runner.service
 [Service]
 Type=simple
 User=forgezero-agent
-Group=forgezero-agent
+Group=${VAULT_GROUP}
 SupplementaryGroups=${DEPLOYMENT_GROUP}
 LoadCredentialEncrypted=agent-seed:/etc/forgezero/creds/agent-seed.cred
 LoadCredentialEncrypted=git-deploy-key:/etc/forgezero/creds/git-deploy-key.cred
@@ -767,15 +822,15 @@ Environment=FZ_ENROL_STATE_FILE=/var/lib/forgezero/enrolment.json
 Environment=FZ_NODE_LABEL=${name}
 Environment=FZ_SOCKET_PATH=/run/forgezero/vault.sock
 Environment=FZ_DEPLOY_ROOT=/opt/forgezero
-Environment=FZ_DEPLOY_PULL=true
+Environment=FZ_DEPLOY_PULL=${pull ? "true" : "false"}
 Environment=FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}
 Environment=HOME=/opt/forgezero/home
 ${attestationPrepare}ExecStart=/usr/local/bin/fz-agent
 Restart=on-failure
 RestartSec=5
 RuntimeDirectory=forgezero
-RuntimeDirectoryMode=0710
-UMask=0077
+RuntimeDirectoryMode=0750
+UMask=0007
 LimitCORE=0
 NoNewPrivileges=true
 PrivateTmp=true
@@ -825,24 +880,39 @@ WantedBy=multi-user.target
 `;
 }
 function cloudInit(profile, claim, manifest) {
-  const bootstrap = guestBootstrapScript(profile, claim.spec.confidential);
-  const agentUnit2 = guestAgentUnit(profile, manifest.name, claim.spec.confidential);
+  const enrolled = Boolean(claim.enrolment);
+  const bootstrap = guestBootstrapScript(profile, claim.spec.confidential, enrolled);
+  const agentUnit2 = guestAgentUnit(profile, manifest.name, claim.spec.confidential, enrolled);
   const enrolmentDropIn = guestEnrolmentDropIn();
   const cleanupScript = guestEnrolmentCleanupScript();
   const cleanupUnit = guestEnrolmentCleanupUnit();
   const runnerSocketUnit = deploymentRunnerSocketUnit("forgezero-agent");
   const runnerUnit = deploymentRunnerUnit({ binPath: "/usr/local/bin/fz-agent", deployRoot: "/opt/forgezero" });
+  const access = claim.access;
+  const users = access ? `users:
+  - default
+  - name: ${access.sshUser}
+    groups: [sudo]
+    shell: /bin/bash
+    sudo: ALL=(ALL) NOPASSWD:ALL
+    ssh_authorized_keys:
+${access.sshPublicKeys.map((key) => `      - ${JSON.stringify(key)}`).join(`
+`)}
+` : "";
+  const enrolmentFiles = enrolled ? `${yamlFile("/run/forgezero-enrol-token", `${claim.enrolment.token}
+`, "0600")}${yamlFile("/usr/local/sbin/forgezero-enrolment-cleanup", cleanupScript, "0700")}${yamlFile("/etc/systemd/system/forgezero-agent.service.d/enrolment.conf", enrolmentDropIn, "0644")}${yamlFile("/etc/systemd/system/forgezero-enrolment-cleanup.service", cleanupUnit, "0644")}` : "";
   return {
     userData: `#cloud-config
 package_update: true
+${users}disable_root: true
 # Git is part of the deployment transport, not a tenant-selected prerequisite:
 # every dynamically claimed repository must be cloneable on a clean image.
 packages: [curl, ca-certificates, openssl, openssh-client, git${claim.spec.confidential ? ", python3" : ""}]
 write_files:
-${yamlFile("/run/forgezero-enrol-token", `${claim.enrolment.token}
-`, "0600")}${yamlFile("/usr/local/sbin/forgezero-guest-bootstrap", bootstrap, "0700")}${yamlFile("/usr/local/sbin/forgezero-enrolment-cleanup", cleanupScript, "0700")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.socket", runnerSocketUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.service", runnerUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service", agentUnit2, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service.d/enrolment.conf", enrolmentDropIn, "0644")}${yamlFile("/etc/systemd/system/forgezero-enrolment-cleanup.service", cleanupUnit, "0644")}runcmd:
+${enrolmentFiles}${yamlFile("/usr/local/sbin/forgezero-guest-bootstrap", bootstrap, "0700")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.socket", runnerSocketUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.service", runnerUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service", agentUnit2, "0644")}runcmd:
   - [ bash, /usr/local/sbin/forgezero-guest-bootstrap ]
-  - [ systemctl, enable, --now, forgezero-enrolment-cleanup.service ]
+${enrolled ? `  - [ systemctl, enable, --now, forgezero-enrolment-cleanup.service ]
+` : ""}
 `,
     metaData: `instance-id: ${manifest.name}-${claim.attempt}
 local-hostname: ${manifest.name}
@@ -866,7 +936,8 @@ var checked = async (exec, argv) => {
 };
 async function provisionMetalGuest(profile, claim, exec) {
   validateMetalProfile(profile);
-  if (!claim.computeKey || !claim.spec.reference || !SAFE_NAME.test(claim.spec.imageKey) || !Number.isInteger(claim.spec.physicalCores) || claim.spec.physicalCores < 1 || claim.spec.physicalCores > 256 || !Number.isInteger(claim.spec.vcpu) || claim.spec.vcpu < 1 || claim.spec.vcpu > 512 || !Number.isInteger(claim.spec.memoryGib) || claim.spec.memoryGib < 1 || claim.spec.memoryGib > 8192 || !Number.isInteger(claim.spec.diskGib) || claim.spec.diskGib < 8 || claim.spec.diskGib > 65536 || !Number.isInteger(claim.spec.egressGuaranteedMbps) || claim.spec.egressGuaranteedMbps < 0 || !Number.isInteger(claim.spec.egressBurstMbps) || claim.spec.egressBurstMbps < claim.spec.egressGuaranteedMbps)
+  assertSupportedGuestImage(claim.spec.imageKey);
+  if (!claim.computeKey || !claim.spec.reference || !SAFE_NAME.test(claim.spec.imageKey) || claim.spec.guestName !== undefined && !SAFE_NAME.test(claim.spec.guestName) || claim.spec.cpuPoolKey !== undefined && !SAFE_NAME.test(claim.spec.cpuPoolKey) || !Number.isInteger(claim.spec.physicalCores) || claim.spec.physicalCores < 1 || claim.spec.physicalCores > 256 || !Number.isInteger(claim.spec.vcpu) || claim.spec.vcpu < 1 || claim.spec.vcpu > 512 || !Number.isInteger(claim.spec.memoryGib) || claim.spec.memoryGib < 1 || claim.spec.memoryGib > 8192 || !Number.isInteger(claim.spec.diskGib) || claim.spec.diskGib < 8 || claim.spec.diskGib > 65536 || !Number.isInteger(claim.spec.egressGuaranteedMbps) || claim.spec.egressGuaranteedMbps < 0 || !Number.isInteger(claim.spec.egressBurstMbps) || claim.spec.egressBurstMbps < claim.spec.egressGuaranteedMbps)
     throw new MetalProvisionError("invalid compute claim");
   const image = profile.images[claim.spec.imageKey];
   if (!image || !isAbsolute(image.path) || !SHA256.test(image.sha256)) {
@@ -880,12 +951,22 @@ async function provisionMetalGuest(profile, claim, exec) {
   for (const path of [profile.stateDir, profile.seedDir, profile.unitDir])
     mkdirSync(path, { recursive: true, mode: 448 });
   const manifests = readManifests(profile.stateDir);
-  const name = guestNameFor(claim.computeKey);
+  if (claim.access) {
+    if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(claim.access.sshUser)) {
+      throw new MetalProvisionError("invalid SSH user");
+    }
+    if (claim.access.sshPublicKeys.length < 1 || claim.access.sshPublicKeys.length > 16 || claim.access.sshPublicKeys.some((key) => typeof key !== "string" || key.length > 16384 || !/^ssh-(?:ed25519|rsa)\s+[A-Za-z0-9+/]+={0,3}(?:\s+.*)?$/.test(key.trim())))
+      throw new MetalProvisionError("invalid SSH public key list");
+  }
+  const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
+  const conflictingName = manifests.find((row) => row.name === name && row.computeKey !== claim.computeKey);
+  if (conflictingName)
+    throw new MetalProvisionError("requested guest name is already allocated");
   const manifestPath = join(profile.stateDir, `${name}.json`);
   const prior = manifests.find((row) => row.computeKey === claim.computeKey);
   if (prior && prior.reference !== claim.spec.reference)
     throw new MetalProvisionError("compute identity conflicts with host inventory");
-  const address = allocateAddress(profile, claim.computeKey, manifests);
+  const address = requestedAddress(profile, claim, manifests);
   const cpuPool = allocateCpuPool(profile, claim, manifests);
   const manifest = prior ?? {
     computeKey: claim.computeKey,
@@ -960,22 +1041,59 @@ async function provisionMetalGuest(profile, claim, exec) {
   save();
   return { guestAddress: address };
 }
+function legacyPlatformManifest(profile, claim, name) {
+  if (claim.bootstrap?.kind !== "platform-genesis" || claim.computeKey !== `platform:${name}` || claim.spec.reference !== `platform:${name}` || claim.spec.guestAddress === undefined)
+    return;
+  const legacyDir = profile.legacyStateDir ?? "/etc/forgezero/guests";
+  const legacyPath = join(legacyDir, `${name}.conf`);
+  if (!existsSync(legacyPath))
+    return;
+  const values = new Map;
+  for (const line of readFileSync(legacyPath, "utf8").split(/\r?\n/)) {
+    if (!line || line.startsWith("#"))
+      continue;
+    const match = /^([A-Z][A-Z0-9_]*)=([^\s'"`$;|&<>]+)$/.exec(line);
+    if (!match)
+      throw new MetalProvisionError("legacy guest inventory contains unsafe syntax");
+    values.set(match[1], match[2]);
+  }
+  const disk = `/dev/${profile.volumeGroup}/${name}`;
+  if (values.get("NAME") !== name || values.get("DISK") !== disk || values.get("IP") !== claim.spec.guestAddress)
+    throw new MetalProvisionError("legacy guest inventory does not match the platform claim");
+  return {
+    computeKey: claim.computeKey,
+    reference: claim.spec.reference,
+    name,
+    address: claim.spec.guestAddress,
+    mac: values.get("MAC") ?? "",
+    cpuPoolKey: claim.spec.cpuPoolKey ?? "",
+    allowedCpus: values.get("CPUSET") ?? "",
+    allowedMemoryNodes: values.get("NUMA"),
+    phase: "running",
+    disk,
+    unit: `forgezero-guest@${name}.service`
+  };
+}
 async function removeMetalGuest(profile, claim, exec) {
   validateMetalProfile(profile);
   if (claim.action !== "delete")
     throw new MetalProvisionError("create claim cannot remove a guest");
-  const name = guestNameFor(claim.computeKey);
+  const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
   const manifestPath = join(profile.stateDir, `${name}.json`);
-  if (!existsSync(manifestPath))
+  const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : legacyPlatformManifest(profile, claim, name);
+  if (!manifest)
     return {};
-  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-  if (manifest.computeKey !== claim.computeKey || manifest.reference !== claim.spec.reference || manifest.name !== name) {
+  const currentIdentity = manifest.computeKey === claim.computeKey && manifest.reference === claim.spec.reference && manifest.name === name;
+  const legacyPlatformIdentity = claim.bootstrap?.kind === "platform-genesis" && claim.computeKey === `platform:${name}` && claim.spec.reference === `platform:${name}` && manifest.name === name && manifest.disk === `/dev/${profile.volumeGroup}/${name}` && manifest.address === claim.spec.guestAddress && (manifest.unit === `fz-guest@${name}.service` || manifest.unit === `forgezero-guest@${name}.service`);
+  if (!currentIdentity && !legacyPlatformIdentity) {
     throw new MetalProvisionError("compute identity conflicts with host inventory");
   }
   const service = `forgezero-guest@${name}.service`;
   const unitPath = join(profile.unitDir, service);
   if (existsSync(unitPath))
     await checked(exec, ["systemctl", "disable", "--now", service]);
+  else if (legacyPlatformIdentity)
+    await checked(exec, ["systemctl", "disable", "--now", service]);
   else if ((await exec(["systemctl", "is-active", service])).exitCode === 0) {
     throw new MetalProvisionError("guest unit is active but its owned unit file is missing");
   }
@@ -992,6 +1110,14 @@ async function removeMetalGuest(profile, claim, exec) {
   ])
     if (existsSync(path))
       unlinkSync(path);
+  if (legacyPlatformIdentity) {
+    const legacyConfig = join(profile.legacyStateDir ?? "/etc/forgezero/guests", `${name}.conf`);
+    const legacyDropIn = join(profile.unitDir, `${service}.d`);
+    if (existsSync(legacyConfig))
+      unlinkSync(legacyConfig);
+    if (existsSync(legacyDropIn))
+      rmSync(legacyDropIn, { recursive: true });
+  }
   await checked(exec, ["systemctl", "daemon-reload"]);
   return {};
 }

package/dist/metal-provision.d.ts

@@ -24,6 +24,8 @@ export interface MetalProvisionProfile {
     stateDir: string;
     seedDir: string;
     unitDir: string;
+    /** One-time compatibility source for pre-Agent platform guests. */
+    legacyStateDir?: string;
     apiUrl: string;
     images: Record<string, MetalImage>;
     /** Explicit host-observed pools. No pool means no dynamic guest authority. */
@@ -68,8 +70,8 @@ export declare function validateMetalProfile(profile: MetalProvisionProfile): vo
 export declare function allocateAddress(profile: MetalProvisionProfile, computeKey: string, rows: GuestManifest[]): string;
 /** Stable tight-fit allocation of one exclusive CPU/NUMA pool. */
 export declare function allocateCpuPool(profile: MetalProvisionProfile, claim: Pick<RemoteProvisionClaim, 'computeKey' | 'spec'>, rows: GuestManifest[]): MetalCpuPool;
-export declare function guestBootstrapScript(profile: MetalProvisionProfile, attested?: boolean): string;
-export declare function guestAgentUnit(profile: MetalProvisionProfile, name: string, attested?: boolean): string;
+export declare function guestBootstrapScript(profile: MetalProvisionProfile, attested?: boolean, hasEnrolment?: boolean): string;
+export declare function guestAgentUnit(profile: MetalProvisionProfile, name: string, attested?: boolean, pull?: boolean): string;
 /** Removed by the root cleanup service once the non-secret binding is durable. */
 export declare function guestEnrolmentDropIn(): string;
 export declare function guestEnrolmentCleanupScript(): string;
@@ -81,5 +83,4 @@ export declare function cloudInit(profile: MetalProvisionProfile, claim: CreateR
 };
 /** The only root operation the metal agent may request. */
 export declare function provisionMetalGuest(profile: MetalProvisionProfile, claim: CreateRemoteProvisionClaim, exec: MetalExec): Promise<ProvisionResult>;
-/** Idempotently remove every host-owned artifact before capacity is returned. */
 export declare function removeMetalGuest(profile: MetalProvisionProfile, claim: RemoteProvisionClaim, exec: MetalExec): Promise<ProvisionResult>;