@forgezero/agent 0.1.22 → 0.1.23

package/dist/fz-agent.js

@@ -3,7 +3,7 @@
 
 // src/index.ts
 import { randomBytes } from "crypto";
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync5, existsSync as existsSync9, mkdirSync as mkdirSync5, chmodSync as chmodSync7 } from "fs";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync6, existsSync as existsSync10, mkdirSync as mkdirSync6, chmodSync as chmodSync9 } from "fs";
 import { dirname as dirname4, join as join4 } from "path";
 import { deriveKeysFromSeed } from "@forgezero/runtime/identity";
 import { DEFAULT_SOCKET } from "@forgezero/vault";
@@ -1373,6 +1373,132 @@ function startProvisioningPull(options) {
   };
 }
 
+// src/migration-pull.ts
+class MigrationClaimLostError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MigrationClaimLostError";
+  }
+}
+var post2 = (options, operation, body) => postSignedNode(options, `v1/node/migrations/${operation}`, body);
+async function complete2(options, body) {
+  const attempts = Math.max(1, Math.min(options.completionAttempts ?? 5, 10));
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let last;
+  for (let attempt = 1;attempt <= attempts; attempt += 1) {
+    try {
+      await post2(options, "complete", body);
+      return;
+    } catch (cause) {
+      last = cause;
+      if (cause instanceof SignedNodeHttpError && cause.status < 500)
+        throw cause;
+      if (attempt < attempts)
+        await sleep(Math.min(2000, 250 * 2 ** (attempt - 1)));
+    }
+  }
+  throw last;
+}
+async function pullMigrationOnce(options) {
+  const response = await post2(options, "claim", {});
+  if (!response.claim)
+    return { status: "idle" };
+  const claim = response.claim;
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  const now = options.now ?? Date.now;
+  let expires = claim.claimExpiresAtTs;
+  let stopped = false;
+  let timer;
+  let renewal = null;
+  let lost = null;
+  const schedule = (override) => {
+    if (stopped)
+      return;
+    const delay = override ?? Math.max(1000, Math.min(5 * 60000, Math.floor(Math.max(0, expires - now()) / 3)));
+    timer = setTimer(() => {
+      if (stopped || renewal)
+        return;
+      let retry;
+      renewal = post2(options, "renew", {
+        migrationKey: claim.migrationKey,
+        claimToken: claim.claimToken
+      }).then((value) => {
+        expires = value.claimExpiresAtTs;
+      }).catch((cause) => {
+        if (cause instanceof SignedNodeHttpError && cause.status < 500) {
+          lost = new MigrationClaimLostError(cause.message);
+          stopped = true;
+        } else
+          retry = Math.max(1000, options.renewRetryMs ?? 5000);
+      }).finally(() => {
+        renewal = null;
+        if (!stopped)
+          schedule(retry);
+      });
+    }, delay);
+  };
+  schedule();
+  let evidence;
+  try {
+    evidence = await options.run(claim);
+  } catch (cause) {
+    stopped = true;
+    clearTimer(timer);
+    await renewal;
+    if (lost)
+      throw lost;
+    const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
+    await complete2(options, {
+      migrationKey: claim.migrationKey,
+      claimToken: claim.claimToken,
+      ok: false,
+      detail: reason
+    });
+    return { status: "failed", claim, reason };
+  }
+  stopped = true;
+  clearTimer(timer);
+  await renewal;
+  if (lost)
+    throw lost;
+  await complete2(options, {
+    migrationKey: claim.migrationKey,
+    claimToken: claim.claimToken,
+    ok: true,
+    evidence
+  });
+  return { status: "completed", claim, evidence };
+}
+function startMigrationPull(options) {
+  const interval = Math.max(1000, options.intervalMs ?? 5000);
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  let stopped = false;
+  let timer;
+  let active = null;
+  const tick = () => {
+    if (stopped || active)
+      return;
+    active = pullMigrationOnce(options).then((result) => options.onEvent?.(result.status, result)).catch((cause) => options.onEvent?.("poll-failed", cause)).finally(() => {
+      active = null;
+      if (!stopped)
+        timer = setTimer(tick, interval);
+    });
+  };
+  tick();
+  return {
+    async stop() {
+      stopped = true;
+      clearTimer(timer);
+      await active;
+    },
+    get active() {
+      return !stopped;
+    }
+  };
+}
+
 // src/metal-helper-socket.ts
 import { chmodSync as chmodSync5, existsSync as existsSync6, unlinkSync as unlinkSync5 } from "fs";
 import { connect as connect2, createServer as createServer3 } from "net";
@@ -1489,55 +1615,6 @@ function shapeEgressUnitDirectives(tap, guaranteedMbps, burstMbps) {
   ];
 }
 
-// src/provision.ts
-var DEPLOYMENT_RUNNER_USER = "forgezero-runner";
-var DEPLOYMENT_GROUP = "forgezero-deploy";
-var VAULT_GROUP = "forgezero-vault";
-var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
-function deploymentRunnerUnit(options) {
-  const bin = options.binPath ?? "fz-agent";
-  const root = options.deployRoot ?? "/opt/forgezero";
-  const agentUser = options.user ?? "forgezero-agent";
-  return `[Unit]
-Description=ForgeZero credential-free project command runner
-Documentation=https://www.forgezero.net/docs/agent
-
-[Service]
-Type=notify
-NotifyAccess=all
-User=${DEPLOYMENT_RUNNER_USER}
-Group=${DEPLOYMENT_GROUP}
-Environment=FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}
-RuntimeDirectory=forgezero-deploy
-RuntimeDirectoryMode=0710
-ExecStartPre=+/usr/bin/install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0710 /run/forgezero-deploy
-ExecStartPre=+/usr/bin/rm -f ${DEPLOYMENT_RUNNER_SOCKET}
-ExecStart=${bin} deploy-runner --root=${root} --home=${root}/runner-home
-ExecStartPost=+/usr/bin/chown ${agentUser}:${agentUser} ${DEPLOYMENT_RUNNER_SOCKET}
-ExecStartPost=+/usr/bin/chmod 0600 ${DEPLOYMENT_RUNNER_SOCKET}
-ExecStartPost=+/usr/bin/chown root:${VAULT_GROUP} /run/forgezero-deploy
-ExecStopPost=+/usr/bin/rm -f ${DEPLOYMENT_RUNNER_SOCKET}
-Restart=always
-RestartSec=2
-UMask=0007
-LimitCORE=0
-NoNewPrivileges=false
-PrivateTmp=true
-ProtectSystem=strict
-ProtectHome=true
-ProtectKernelTunables=true
-ProtectKernelModules=true
-ProtectControlGroups=true
-RestrictRealtime=true
-MemoryDenyWriteExecute=true
-LockPersonality=true
-ReadWritePaths=${root}/releases ${root}/runner-home
-
-[Install]
-WantedBy=multi-user.target
-`;
-}
-
 // src/ubuntu.ts
 var SUPPORTED_GUEST_IMAGE = Object.freeze({
   key: "ubuntu-resolute-20260731",
@@ -1718,7 +1795,7 @@ var yamlFile = (path, content, permissions) => `  - path: ${JSON.stringify(path)
     encoding: b64
     content: ${base64(content)}
 `;
-function guestBootstrapScript(profile, attested = Boolean(profile.confidential), hasEnrolment = true) {
+function guestBootstrapScript(profile, attested = Boolean(profile.confidential), hasEnrolment = true, nodeLabel = "compute") {
   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
@@ -1732,26 +1809,7 @@ printf 'sev-guest
 ` : "";
   return `#!/usr/bin/env bash
 set -Eeuo pipefail
-${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
-install -d -o root -g root -m 0700 /etc/forgezero/creds
-install -d -o root -g root -m 0755 /etc/forgezero/git
-install -d -o forgezero-agent -g forgezero-agent -m 0700 /var/lib/forgezero
-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
-${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
+${attestationSetup}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 -
@@ -1759,132 +1817,16 @@ chmod 0400 /var/lib/forgezero/enrol-token.cred
   install -m 0755 ${agentBun}/bin/bun /usr/local/bin/bun
   rm -f /run/fz-bun-install
 fi
-if [[ ! -x /usr/local/bin/fz-agent ]]; then
+if [[ ! -x /usr/local/bin/fz-agent ]] || [[ "$(/usr/local/bin/fz-agent --version 2>/dev/null || true)" != "${profile.agentVersion}" ]]; then
   env BUN_INSTALL=${agentBun} /usr/local/bin/bun add -g --no-cache --force @forgezero/agent@${profile.agentVersion}
   ln -sfn ${agentBun}/bin/fz-agent /usr/local/bin/fz-agent
 fi
-if [[ ! -s /etc/forgezero/creds/agent-seed.cred ]]; then
-  umask 077
-  openssl rand -base64 32 | tr '+/' '-_' | tr -d '=
-' >/run/fz-agent-seed
-  systemd-creds encrypt --name=agent-seed /run/fz-agent-seed /etc/forgezero/creds/agent-seed.cred
-  rm -f /run/fz-agent-seed
-fi
-chmod 0400 /etc/forgezero/creds/agent-seed.cred
-if [[ ! -s /etc/forgezero/creds/git-deploy-key.cred ]]; then
-  umask 077
-  rm -f /run/fz-git-deploy-key /run/fz-git-deploy-key.pub
-  ssh-keygen -q -t ed25519 -N '' -C forgezero-compute -f /run/fz-git-deploy-key
-  systemd-creds encrypt --name=git-deploy-key /run/fz-git-deploy-key /etc/forgezero/creds/git-deploy-key.cred
-  install -o root -g root -m 0444 /run/fz-git-deploy-key.pub /etc/forgezero/git/deploy.pub
-  rm -f /run/fz-git-deploy-key /run/fz-git-deploy-key.pub
-fi
-if [[ ! -s /etc/forgezero/git/deploy.pub ]]; then
-  systemd-creds decrypt --name=git-deploy-key /etc/forgezero/creds/git-deploy-key.cred /run/fz-git-deploy-key
-  ssh-keygen -y -f /run/fz-git-deploy-key | sed 's/$/ forgezero-compute/' >/run/fz-git-deploy-key.pub
-  install -o root -g root -m 0444 /run/fz-git-deploy-key.pub /etc/forgezero/git/deploy.pub
-  rm -f /run/fz-git-deploy-key /run/fz-git-deploy-key.pub
-fi
-chmod 0400 /etc/forgezero/creds/git-deploy-key.cred
-systemctl daemon-reload
-systemctl disable --now forgezero-deploy-runner.socket 2>/dev/null || true
-rm -f /etc/systemd/system/forgezero-deploy-runner.socket
-systemctl daemon-reload
-systemctl enable --now forgezero-deploy-runner.service forgezero-agent.service
-`;
-}
-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
-DeviceAllow=/dev/sev-guest rw
-` : "";
-  return `[Unit]
-Description=ForgeZero compute agent (${name})
-After=network-online.target forgezero-deploy-runner.service
-Wants=network-online.target
-Requires=forgezero-deploy-runner.service
-
-[Service]
-Type=simple
-User=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
-Environment=FZ_SEED_CREDENTIAL=agent-seed
-Environment=FZ_GIT_PUBLIC_KEY_FILE=/etc/forgezero/git/deploy.pub
-Environment=FZ_API=${profile.apiUrl}
-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=${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=0750
-UMask=0007
-LimitCORE=0
-NoNewPrivileges=true
-PrivateTmp=true
-ProtectSystem=strict
-ProtectHome=true
-ReadWritePaths=/var/lib/forgezero /opt/forgezero
-${attestationDevice}
-
-[Install]
-WantedBy=multi-user.target
-`;
-}
-function guestEnrolmentDropIn() {
-  return `[Service]
-LoadCredentialEncrypted=enrol-token:/var/lib/forgezero/enrol-token.cred
-Environment=FZ_ENROL_TOKEN_CREDENTIAL=enrol-token
-`;
-}
-function guestEnrolmentCleanupScript() {
-  return `#!/usr/bin/env bash
-set -Eeuo pipefail
-for _ in $(seq 1 180); do
-  [[ -s /var/lib/forgezero/enrolment.json ]] && break
-  sleep 1
-done
-[[ -s /var/lib/forgezero/enrolment.json ]] || { echo 'guest enrolment did not become durable' >&2; exit 1; }
-rm -f /var/lib/forgezero/enrol-token.cred
-rm -f /etc/systemd/system/forgezero-agent.service.d/enrolment.conf
-systemctl daemon-reload
-systemctl disable forgezero-enrolment-cleanup.service
-`;
-}
-function guestEnrolmentCleanupUnit() {
-  return `[Unit]
-Description=Remove the consumed ForgeZero guest enrolment credential
-After=forgezero-agent.service
-Requires=forgezero-agent.service
-ConditionPathExists=/var/lib/forgezero/enrol-token.cred
-
-[Service]
-Type=oneshot
-ExecStart=/usr/local/sbin/forgezero-enrolment-cleanup
-TimeoutStartSec=4min
-
-[Install]
-WantedBy=multi-user.target
+env   FZ_API=${profile.apiUrl}   FZ_AGENT_BIN=/usr/local/bin/fz-agent   FZ_AGENT_USER=forgezero-agent   FZ_SOCKET_PATH=/run/forgezero/vault.sock   FZ_SEED_CREDENTIAL_PATH=/etc/forgezero/creds/agent-seed.cred   FZ_GIT_CREDENTIAL_PATH=/etc/forgezero/creds/git-deploy-key.cred   FZ_GIT_PUBLIC_KEY_PATH=/etc/forgezero/git/deploy.pub   FZ_DEPLOY_ROOT=/opt/forgezero   FZ_DEPLOY_PULL=${hasEnrolment ? "true" : "false"}   FZ_NODE_LABEL=${nodeLabel}   ${agentBun}/bin/fz agent install --apply${hasEnrolment ? " --enrol" : ""}
 `;
 }
 function cloudInit(profile, claim, manifest) {
   const enrolled = Boolean(claim.enrolment);
-  const bootstrap = guestBootstrapScript(profile, claim.spec.confidential, enrolled);
-  const agentUnit = guestAgentUnit(profile, manifest.name, claim.spec.confidential, enrolled);
-  const enrolmentDropIn = guestEnrolmentDropIn();
-  const cleanupScript = guestEnrolmentCleanupScript();
-  const cleanupUnit = guestEnrolmentCleanupUnit();
-  const runnerUnit = deploymentRunnerUnit({ binPath: "/usr/local/bin/fz-agent", deployRoot: "/opt/forgezero", user: "forgezero-agent" });
+  const bootstrap = guestBootstrapScript(profile, claim.spec.confidential, enrolled, manifest.name);
   const access = claim.access;
   const users = access ? `users:
   - default
@@ -1896,8 +1838,8 @@ function cloudInit(profile, claim, manifest) {
 ${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")}` : "";
+  const enrolmentFiles = enrolled ? yamlFile("/run/forgezero-enrol-token", `${claim.enrolment.token}
+`, "0600") : "";
   return {
     userData: `#cloud-config
 package_update: true
@@ -1906,10 +1848,8 @@ ${users}disable_root: true
 # every dynamically claimed repository must be cloneable on a clean image.
 packages: [curl, ca-certificates, openssl, openssh-client, git, unzip${claim.spec.confidential ? ", python3" : ""}]
 write_files:
-${enrolmentFiles}${yamlFile("/usr/local/sbin/forgezero-guest-bootstrap", bootstrap, "0700")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.service", runnerUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service", agentUnit, "0644")}runcmd:
+${enrolmentFiles}${yamlFile("/usr/local/sbin/forgezero-guest-bootstrap", bootstrap, "0700")}runcmd:
   - [ bash, /usr/local/sbin/forgezero-guest-bootstrap ]
-${enrolled ? `  - [ systemctl, enable, --now, forgezero-enrolment-cleanup.service ]
-` : ""}
 `,
     metaData: `instance-id: ${manifest.name}-${claim.attempt}
 local-hostname: ${manifest.name}
@@ -2732,22 +2672,268 @@ async function closeServerWithin(server, timeoutMs) {
   return closed;
 }
 
+// src/lifecycle-helper.ts
+import { chmodSync as chmodSync7, existsSync as existsSync9, readFileSync as readFileSync4, unlinkSync as unlinkSync7 } from "fs";
+import { connect as connect4, createConnection, createServer as createServer5, isIP } from "net";
+var DEFAULT_LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
+var MAX_REQUEST_BYTES4 = 16 * 1024;
+var REQUEST_TIMEOUT_MS = 5000;
+var ACTION_TIMEOUT_MS = 10 * 60000;
+var unitPattern = /^[A-Za-z0-9_.@-]+\.service$/;
+var privateIp = (value) => {
+  const address = value.replace(/^\[|\]$/g, "").toLowerCase();
+  if (isIP(address) === 4) {
+    const [a, b] = address.split(".").map(Number);
+    return a === 10 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
+  }
+  if (isIP(address) === 6) {
+    const first = Number.parseInt(address.split(":", 1)[0], 16);
+    return Number.isFinite(first) && (first & 65024) === 64512;
+  }
+  return false;
+};
+function validateLifecycleProfile(profile) {
+  if (!Array.isArray(profile.apiUnits) || profile.apiUnits.length < 1 || profile.apiUnits.some((unit) => !unitPattern.test(unit))) {
+    throw new Error("lifecycle profile needs one or more valid API service units");
+  }
+  if (!unitPattern.test(profile.databaseUnit))
+    throw new Error("lifecycle profile database unit is invalid");
+  const apiUrl = new URL(profile.apiHealthUrl);
+  if (apiUrl.protocol !== "http:" || !["127.0.0.1", "[::1]", "::1", "localhost"].includes(apiUrl.hostname)) {
+    throw new Error("API health URL must be loopback HTTP");
+  }
+  const databaseUrl = new URL(profile.databaseHealthUrl);
+  if (databaseUrl.protocol !== "http:" || !(["127.0.0.1", "[::1]", "::1", "localhost"].includes(databaseUrl.hostname) || privateIp(databaseUrl.hostname))) {
+    throw new Error("database health URL must be loopback or private HTTP");
+  }
+  if (!Array.isArray(profile.databasePorts) || profile.databasePorts.length < 1 || profile.databasePorts.some((port) => !Number.isInteger(port) || port < 1 || port > 65535)) {
+    throw new Error("lifecycle profile database ports are invalid");
+  }
+}
+function loadLifecycleProfile(path) {
+  const profile = JSON.parse(readFileSync4(path, "utf8"));
+  validateLifecycleProfile(profile);
+  return profile;
+}
+var spawnLifecycleCommand = async (argv) => {
+  const child = Bun.spawn([...argv], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+  }, ACTION_TIMEOUT_MS);
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  clearTimeout(timer);
+  return { exitCode: timedOut ? 124 : exitCode, stdout, stderr };
+};
+var requireSuccess = async (exec, argv, label) => {
+  const result = await exec(argv);
+  if (result.exitCode !== 0)
+    throw new Error(`${label} failed: ${(result.stderr || result.stdout).trim() || `exit ${result.exitCode}`}`);
+  return result.stdout;
+};
+var probeTcp = (host, port, timeoutMs = 5000) => new Promise((resolve2, reject) => {
+  const socket = createConnection({ host, port });
+  socket.setTimeout(timeoutMs);
+  socket.once("connect", () => {
+    socket.destroy();
+    resolve2();
+  });
+  socket.once("timeout", () => {
+    socket.destroy();
+    reject(new Error(`private peer ${host}:${port} timed out`));
+  });
+  socket.once("error", reject);
+});
+async function executeLifecycleAction(profile, claim, exec = spawnLifecycleCommand, tcpProbe = probeTcp, fetcher = fetch) {
+  validateLifecycleProfile(profile);
+  switch (claim.action) {
+    case "network-ready": {
+      if (!claim.peerPrivateAddresses?.length)
+        throw new Error("network claim has no private peers");
+      if (claim.network === "cloudflare-warp") {
+        const status = await requireSuccess(exec, ["/usr/bin/warp-cli", "--accept-tos", "status"], "WARP status");
+        if (!/\bconnected\b/i.test(status) || /\bdisconnected\b/i.test(status))
+          throw new Error("WARP is not connected");
+      }
+      for (const address of claim.peerPrivateAddresses) {
+        for (const port of profile.databasePorts)
+          await tcpProbe(address, port);
+      }
+      return {
+        targetAgentReady: true,
+        privateNetworkReady: true,
+        ...claim.network === "cloudflare-warp" ? { warpConnected: true } : {}
+      };
+    }
+    case "database-member-ready": {
+      await requireSuccess(exec, ["/usr/bin/systemctl", "is-active", profile.databaseUnit], "database service check");
+      const response = await fetcher(profile.databaseHealthUrl, { signal: AbortSignal.timeout(5000) });
+      if (!response.ok && response.status !== 401)
+        throw new Error(`database health returned HTTP ${response.status}`);
+      return { databaseMemberHealthy: true };
+    }
+    case "api-ready": {
+      const response = await fetcher(profile.apiHealthUrl, { signal: AbortSignal.timeout(5000) });
+      if (!response.ok)
+        throw new Error(`API health returned HTTP ${response.status}`);
+      return { apiHealthy: true };
+    }
+    case "source-drained":
+      await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits], "API drain");
+      return { sourceDrained: true };
+    case "source-stopped":
+      await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits, profile.databaseUnit], "source retirement");
+      return { sourceStopped: true };
+    default:
+      throw new Error("unknown lifecycle action");
+  }
+}
+function startLifecycleHelper(options) {
+  validateLifecycleProfile(options.profile);
+  const socketPath = options.socketPath ?? DEFAULT_LIFECYCLE_HELPER_SOCKET;
+  if (existsSync9(socketPath))
+    unlinkSync7(socketPath);
+  let tail = Promise.resolve();
+  const server = createServer5((socket) => {
+    let buffer = "";
+    socket.setTimeout(REQUEST_TIMEOUT_MS, () => socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request timed out" } })}
+`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (buffer.length > MAX_REQUEST_BYTES4)
+        return void socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request too large" } })}
+`);
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.setTimeout(0);
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      const work = async () => {
+        let request;
+        try {
+          request = JSON.parse(line);
+        } catch {
+          return { ok: false, error: { code: "REFUSED", message: "invalid request" } };
+        }
+        if (request?.op !== "apply" || !request.claim)
+          return { ok: false, error: { code: "REFUSED", message: "unknown operation" } };
+        try {
+          return { ok: true, evidence: await executeLifecycleAction(options.profile, request.claim, options.exec, options.tcpProbe, options.fetch) };
+        } catch (cause) {
+          return { ok: false, error: { code: "FAILED", message: cause instanceof Error ? cause.message : "lifecycle action failed" } };
+        }
+      };
+      const response = tail.then(work, work);
+      tail = response;
+      response.then((value) => socket.end(`${JSON.stringify(value)}
+`));
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(socketPath, () => chmodSync7(socketPath, 432));
+  return {
+    server,
+    async stop() {
+      await new Promise((resolve2) => server.close(() => resolve2()));
+      await tail;
+    }
+  };
+}
+function requestLifecycleAction(claim, socketPath = DEFAULT_LIFECYCLE_HELPER_SOCKET) {
+  return new Promise((resolve2, reject) => {
+    const socket = connect4(socketPath, () => socket.write(`${JSON.stringify({ op: "apply", claim })}
+`));
+    socket.setTimeout(ACTION_TIMEOUT_MS + 1e4, () => {
+      socket.destroy();
+      reject(new Error("lifecycle helper response timed out"));
+    });
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.end();
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        if (response.ok)
+          resolve2(response.evidence);
+        else
+          reject(new Error(response.error.message));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+
+// src/warp-config.ts
+import { chmodSync as chmodSync8, mkdirSync as mkdirSync5, renameSync as renameSync3, symlinkSync, unlinkSync as unlinkSync8, writeFileSync as writeFileSync5 } from "fs";
+var xml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+function renderWarpMdm(options) {
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/i.test(options.organization))
+    throw new Error("WARP organization is invalid");
+  if (!options.clientId.trim() || !options.clientSecret.trim())
+    throw new Error("WARP service-token credentials are empty");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<dict>
+  <key>auth_client_id</key><string>${xml(options.clientId.trim())}</string>
+  <key>auth_client_secret</key><string>${xml(options.clientSecret.trim())}</string>
+  <key>auto_connect</key><integer>1</integer>
+  <key>onboarding</key><false/>
+  <key>organization</key><string>${xml(options.organization)}</string>
+  <key>service_mode</key><string>warp</string>
+</dict>
+`;
+}
+function materializeWarpMdm(options) {
+  const runtimePath = options.runtimePath ?? "/run/forgezero-warp/mdm.xml";
+  const servicePath = options.servicePath ?? "/var/lib/cloudflare-warp/mdm.xml";
+  mkdirSync5(runtimePath.replace(/\/[^/]+$/, ""), { recursive: true, mode: 448 });
+  mkdirSync5(servicePath.replace(/\/[^/]+$/, ""), { recursive: true, mode: 448 });
+  const next = `${runtimePath}.next`;
+  writeFileSync5(next, renderWarpMdm(options), { mode: 384 });
+  chmodSync8(next, 384);
+  renameSync3(next, runtimePath);
+  try {
+    unlinkSync8(servicePath);
+  } catch (cause) {
+    if (cause.code !== "ENOENT")
+      throw cause;
+  }
+  symlinkSync(runtimePath, servicePath);
+  return { runtimePath, servicePath };
+}
+
 // src/version.ts
-var VERSION = "0.1.22";
+var VERSION = "0.1.23";
 
 // src/index.ts
 function loadOrCreateSeed(path) {
-  if (existsSync9(path)) {
-    const seed2 = new Uint8Array(Buffer.from(readFileSync4(path, "utf8").trim(), "base64url"));
+  if (existsSync10(path)) {
+    const seed2 = new Uint8Array(Buffer.from(readFileSync5(path, "utf8").trim(), "base64url"));
     if (seed2.length < 32) {
       throw new Error(`agent: the seed at ${path} is too short to derive a key from.`);
     }
     return seed2;
   }
-  mkdirSync5(dirname4(path), { recursive: true });
+  mkdirSync6(dirname4(path), { recursive: true });
   const seed = new Uint8Array(randomBytes(32));
-  writeFileSync5(path, Buffer.from(seed).toString("base64url"), { mode: 384 });
-  chmodSync7(path, 384);
+  writeFileSync6(path, Buffer.from(seed).toString("base64url"), { mode: 384 });
+  chmodSync9(path, 384);
   return seed;
 }
 var DEFAULT_SOCKET_PATH = DEFAULT_SOCKET;
@@ -2758,9 +2944,9 @@ function loadSeedCredential(name = DEFAULT_SEED_CREDENTIAL, directory = process.
   if (!directory)
     throw new Error("agent: CREDENTIALS_DIRECTORY is missing; systemd did not load the node identity.");
   const path = `${directory}/${name}`;
-  if (!existsSync9(path))
+  if (!existsSync10(path))
     throw new Error(`agent: the systemd credential ${name} is missing at ${path}.`);
-  const seed = new Uint8Array(Buffer.from(readFileSync4(path, "utf8").trim(), "base64url"));
+  const seed = new Uint8Array(Buffer.from(readFileSync5(path, "utf8").trim(), "base64url"));
   if (seed.length < 32)
     throw new Error(`agent: the systemd credential ${name} is too short to derive a key from.`);
   return seed;
@@ -2770,7 +2956,7 @@ function loadTextCredential(name, directory = process.env.CREDENTIALS_DIRECTORY)
     throw new Error("agent: CREDENTIALS_DIRECTORY is missing; systemd did not load the credential.");
   if (!/^[A-Za-z0-9_.-]+$/.test(name))
     throw new Error("agent: invalid systemd credential name.");
-  const value = readFileSync4(`${directory}/${name}`, "utf8").trim();
+  const value = readFileSync5(`${directory}/${name}`, "utf8").trim();
   if (!value)
     throw new Error(`agent: systemd credential ${name} is empty.`);
   return value;
@@ -2876,7 +3062,7 @@ if (import.meta.main) {
       nodeKey: nodeKey2,
       keys: keys2,
       label: process.env.FZ_NODE_LABEL,
-      gitDeployPublicKey: process.env.FZ_GIT_PUBLIC_KEY_FILE ? readFileSync4(process.env.FZ_GIT_PUBLIC_KEY_FILE, "utf8").trim() : undefined
+      gitDeployPublicKey: process.env.FZ_GIT_PUBLIC_KEY_FILE ? readFileSync5(process.env.FZ_GIT_PUBLIC_KEY_FILE, "utf8").trim() : undefined
     });
     console.log(`[agent] enrolled ${binding2.computeReference} in project ${binding2.projectKey}/${binding2.environmentKey}`);
     process.exit(0);
@@ -2885,7 +3071,7 @@ if (import.meta.main) {
     const profilePath = args.find((arg) => arg.startsWith("--profile="))?.slice("--profile=".length);
     if (!profilePath)
       throw new Error("metal-helper requires --profile=/absolute/path.json");
-    const profile = JSON.parse(readFileSync4(profilePath, "utf8"));
+    const profile = JSON.parse(readFileSync5(profilePath, "utf8"));
     const helper = startMetalHelper({
       profile,
       socketPath: process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET
@@ -2903,11 +3089,53 @@ if (import.meta.main) {
     process.on("SIGINT", () => void stop());
     await new Promise(() => {});
   }
+  if (command === "lifecycle-helper") {
+    const profilePath = args.find((arg) => arg.startsWith("--profile="))?.slice("--profile=".length);
+    if (!profilePath?.startsWith("/"))
+      throw new Error("lifecycle-helper requires --profile=/absolute/path.json");
+    if (typeof process.getuid !== "function" || process.getuid() !== 0) {
+      throw new Error("lifecycle-helper must run as root");
+    }
+    const helper = startLifecycleHelper({
+      profile: loadLifecycleProfile(profilePath),
+      socketPath: process.env.FZ_LIFECYCLE_HELPER_SOCKET ?? DEFAULT_LIFECYCLE_HELPER_SOCKET
+    });
+    console.log(`[lifecycle-helper] listening on ${process.env.FZ_LIFECYCLE_HELPER_SOCKET ?? DEFAULT_LIFECYCLE_HELPER_SOCKET}`);
+    let stopping = false;
+    const stop = async () => {
+      if (stopping)
+        return;
+      stopping = true;
+      await helper.stop();
+      process.exit(0);
+    };
+    process.on("SIGTERM", () => void stop());
+    process.on("SIGINT", () => void stop());
+    await new Promise(() => {});
+  }
+  if (command === "warp-config") {
+    const organization = args.find((arg) => arg.startsWith("--organization="))?.slice("--organization=".length);
+    if (!organization)
+      throw new Error("warp-config requires --organization=<team-name>");
+    if (typeof process.getuid !== "function" || process.getuid() !== 0)
+      throw new Error("warp-config must run as root");
+    const clientIdCredential = process.env.FZ_WARP_CLIENT_ID_CREDENTIAL;
+    const clientSecretCredential = process.env.FZ_WARP_CLIENT_SECRET_CREDENTIAL;
+    if (!clientIdCredential || !clientSecretCredential)
+      throw new Error("warp-config requires systemd service-token credentials");
+    materializeWarpMdm({
+      organization,
+      clientId: loadTextCredential(clientIdCredential),
+      clientSecret: loadTextCredential(clientSecretCredential)
+    });
+    console.log("[warp-config] enrollment materialized in tmpfs");
+    process.exit(0);
+  }
   if (command === "metal-isolation") {
     const profilePath = args.find((arg) => arg.startsWith("--profile="))?.slice("--profile=".length);
     if (!profilePath)
       throw new Error("metal-isolation requires --profile=/absolute/path.json");
-    const profile = JSON.parse(readFileSync4(profilePath, "utf8"));
+    const profile = JSON.parse(readFileSync5(profilePath, "utf8"));
     await applyMetalIsolation(profile);
     console.log("[metal-isolation] host and guest cgroup boundaries active");
     process.exit(0);
@@ -2952,7 +3180,7 @@ if (import.meta.main) {
     if (claimArg !== "-" && !claimArg.startsWith("/")) {
       throw new Error("metal-apply claim path must be absolute");
     }
-    const raw = readFileSync4(claimArg === "-" ? "/dev/stdin" : claimArg, "utf8");
+    const raw = readFileSync5(claimArg === "-" ? "/dev/stdin" : claimArg, "utf8");
     if (Buffer.byteLength(raw) > 32 * 1024)
       throw new Error("metal-apply claim exceeds 32 KiB");
     const claim = JSON.parse(raw);
@@ -2978,9 +3206,9 @@ if (import.meta.main) {
       metalHostname: process.env.FZ_METAL_HOSTNAME,
       run: (claim) => requestMetalProvision(claim, process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET),
       metalPreflight: () => ({
-        snpHost: existsSync9("/dev/sev"),
-        kvm: existsSync9("/dev/kvm"),
-        helper: existsSync9(process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET)
+        snpHost: existsSync10("/dev/sev"),
+        kvm: existsSync10("/dev/kvm"),
+        helper: existsSync10(process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET)
       }),
       onEvent: (event, detail) => console.log(`[metal-agent] ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
     });
@@ -3027,7 +3255,7 @@ if (import.meta.main) {
       process.exit(1);
     }
   }
-  const attestationSource = existsSync9("/dev/sev-guest") ? createSnpAttestationSource() : undefined;
+  const attestationSource = existsSync10("/dev/sev-guest") ? createSnpAttestationSource() : undefined;
   const running = runAgent({
     socketPath: process.env.FZ_SOCKET_PATH ?? DEFAULT_SOCKET_PATH,
     seedCredential: process.env.FZ_SEED_CREDENTIAL,
@@ -3041,8 +3269,8 @@ if (import.meta.main) {
   const enrolmentStatePath = process.env.FZ_ENROL_STATE_FILE ?? DEFAULT_ENROLMENT_STATE_PATH;
   let binding = loadGuestBinding(enrolmentStatePath, nodeKey);
   const enrolmentCredential = process.env.FZ_ENROL_TOKEN_CREDENTIAL;
-  const enrolmentCredentialAvailable = Boolean(enrolmentCredential && process.env.CREDENTIALS_DIRECTORY && existsSync9(`${process.env.CREDENTIALS_DIRECTORY}/${enrolmentCredential}`));
-  const legacyEnrolmentFileAvailable = Boolean(process.env.FZ_ENROL_TOKEN_FILE && existsSync9(process.env.FZ_ENROL_TOKEN_FILE));
+  const enrolmentCredentialAvailable = Boolean(enrolmentCredential && process.env.CREDENTIALS_DIRECTORY && existsSync10(`${process.env.CREDENTIALS_DIRECTORY}/${enrolmentCredential}`));
+  const legacyEnrolmentFileAvailable = Boolean(process.env.FZ_ENROL_TOKEN_FILE && existsSync10(process.env.FZ_ENROL_TOKEN_FILE));
   if (!binding && (enrolmentCredentialAvailable || legacyEnrolmentFileAvailable) && process.env.FZ_API) {
     binding = await enrolGuestIdentity({
       apiUrl: process.env.FZ_API,
@@ -3052,7 +3280,7 @@ if (import.meta.main) {
       nodeKey,
       keys,
       label: process.env.FZ_NODE_LABEL,
-      gitDeployPublicKey: process.env.FZ_GIT_PUBLIC_KEY_FILE ? readFileSync4(process.env.FZ_GIT_PUBLIC_KEY_FILE, "utf8").trim() : undefined
+      gitDeployPublicKey: process.env.FZ_GIT_PUBLIC_KEY_FILE ? readFileSync5(process.env.FZ_GIT_PUBLIC_KEY_FILE, "utf8").trim() : undefined
     });
     console.log(`[agent] enrolled ${binding.computeReference} in project ${binding.projectKey}/${binding.environmentKey}`);
   }
@@ -3090,6 +3318,19 @@ if (import.meta.main) {
   }) : undefined;
   if (attestationLoop)
     console.log("[agent] periodic SEV-SNP attestation enabled");
+  const migrationEnabled = process.env.FZ_MIGRATION_PULL === "true";
+  if (migrationEnabled && (!binding || !nodeApiUrl)) {
+    throw new Error("agent: outbound lifecycle work requires a persisted compute enrolment binding");
+  }
+  const migrationPull = migrationEnabled ? startMigrationPull({
+    apiUrl: nodeApiUrl,
+    nodeKey,
+    keys,
+    run: (claim) => requestLifecycleAction(claim, process.env.FZ_LIFECYCLE_HELPER_SOCKET ?? DEFAULT_LIFECYCLE_HELPER_SOCKET),
+    onEvent: (event, detail) => console.log(`[agent] migration ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
+  }) : undefined;
+  if (migrationPull)
+    console.log("[agent] PQ-authenticated outbound lifecycle claims enabled");
   const systemdDeploymentSecrets = createSystemdDeploymentSecrets(process.env.FZ_DEPLOY_SYSTEMD_SECRETS);
   const deploymentSecrets = secretCache ? {
     async get(name) {
@@ -3175,8 +3416,9 @@ if (import.meta.main) {
       const pullDrain = pull?.stop() ?? Promise.resolve();
       const vaultDrain = vaultSync?.stop() ?? Promise.resolve();
       const attestationDrain = attestationLoop?.stop() ?? Promise.resolve();
+      const migrationDrain = migrationPull?.stop() ?? Promise.resolve();
       const pullDrained = pull ? await settleWithin(pullDrain, remaining()) : true;
-      const backgroundDrained = await settleWithin(Promise.all([vaultDrain, attestationDrain]), remaining());
+      const backgroundDrained = await settleWithin(Promise.all([vaultDrain, attestationDrain, migrationDrain]), remaining());
       const managerReports = await Promise.all([...new Set(managers.values())].map((manager) => manager.stop(remaining())));
       const socketClosed = await closeServerWithin(server, remaining());
       const timedOut = managerReports.some((report) => report.timedOut);
@@ -3193,7 +3435,7 @@ if (import.meta.main) {
     process.on("SIGINT", () => void shutdown("SIGINT"));
   } else {
     console.log("[agent] signing/vault mode only; deployment root and pull are not configured");
-    if (vaultSync || attestationLoop) {
+    if (vaultSync || attestationLoop || migrationPull) {
       let stopping = false;
       const stop = async (signal) => {
         if (stopping)
@@ -3205,7 +3447,8 @@ if (import.meta.main) {
         console.log(`[agent] ${signal}: stopping background intake and draining`);
         const backgroundDrained = await settleWithin(Promise.all([
           vaultSync?.stop() ?? Promise.resolve(),
-          attestationLoop?.stop() ?? Promise.resolve()
+          attestationLoop?.stop() ?? Promise.resolve(),
+          migrationPull?.stop() ?? Promise.resolve()
         ]), remaining());
         const socketClosed = await closeServerWithin(server, remaining());
         console.log(`[agent] drain ${JSON.stringify({ backgroundDrained, socketClosed })}`);
@@ -3218,34 +3461,43 @@ if (import.meta.main) {
 }
 export {
   validateMetalProfile,
+  validateLifecycleProfile,
   tenantNodeApiUrl,
   startProvisioningPull,
   startNodeVaultSync,
   startNodeAttestation,
+  startMigrationPull,
   startMetalHelper,
+  startLifecycleHelper,
   startDeploymentRunner,
   startDeploymentPull,
   startControlServer,
   startAgent,
   runAgent,
   requestMetalProvision,
+  requestLifecycleAction,
   requestDeploymentCommand,
   requestControl,
+  renderWarpMdm,
   removeMetalGuest,
   pullProvisioningOnce,
+  pullMigrationOnce,
   pullDeploymentOnce,
   provisionMetalGuest,
   projectVaultCoordinate,
   projectVaultCacheKey,
   metalHousekeepingDropIn,
   metalGuestSliceUnit,
+  materializeWarpMdm,
   loadTextCredential,
   loadSeedCredential,
   loadOrCreateSeed,
+  loadLifecycleProfile,
   loadGuestBinding,
   handleRequest,
   handleApplicationRequest,
   guestNameFor,
+  executeLifecycleAction,
   enrolGuestIdentity,
   createSystemdDeploymentSecrets,
   createSnpAttestationSource,
@@ -3265,6 +3517,7 @@ export {
   DEFAULT_SEED_PATH,
   DEFAULT_SEED_CREDENTIAL,
   DEFAULT_METAL_HELPER_SOCKET,
+  DEFAULT_LIFECYCLE_HELPER_SOCKET,
   DEFAULT_ENROLMENT_STATE_PATH,
   DEFAULT_DEPLOYMENT_RUNNER_SOCKET,
   DEFAULT_CONTROL_SOCKET,