@forgezero/agent 0.1.2 → 0.1.10

package/dist/fz-agent.js

@@ -3,8 +3,8 @@
 
 // src/index.ts
 import { randomBytes } from "crypto";
-import { readFileSync, writeFileSync, existsSync as existsSync2, mkdirSync, chmodSync as chmodSync2 } from "fs";
-import { dirname } from "path";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync6, existsSync as existsSync9, mkdirSync as mkdirSync6, chmodSync as chmodSync8 } from "fs";
+import { dirname as dirname5, join as join4 } from "path";
 import { deriveKeysFromSeed } from "@forgezero/runtime/identity";
 import { DEFAULT_SOCKET } from "@forgezero/vault";
 
@@ -12,85 +12,6 @@ import { DEFAULT_SOCKET } from "@forgezero/vault";
 import { createServer } from "net";
 import { chmodSync, existsSync, unlinkSync } from "fs";
 import { signRequest } from "@forgezero/runtime/identity";
-
-// src/pipeline.ts
-class PipelineError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = "PipelineError";
-  }
-}
-function redact(text, values) {
-  let out = text;
-  for (const value of [...values].sort((a, b) => b.length - a.length)) {
-    if (value.length < 8)
-      continue;
-    out = out.split(value).join("\u2022\u2022\u2022\u2022redacted\u2022\u2022\u2022\u2022");
-  }
-  return out;
-}
-async function runPipeline(options) {
-  const now = options.now ?? (() => Date.now());
-  const { pipeline } = options;
-  let assurance = "enrolled";
-  if (options.attest) {
-    try {
-      await options.attest();
-      assurance = "attested";
-    } catch (cause) {
-      if (pipeline.requireAttestation) {
-        throw new PipelineError("ATTESTATION_FAILED", `${pipeline.name} requires attestation and this machine could not produce one: ${cause.message}`);
-      }
-    }
-  } else if (pipeline.requireAttestation) {
-    throw new PipelineError("ATTESTATION_REQUIRED", `${pipeline.name} requires attestation. This agent has no attestation source, so it cannot run it.`);
-  }
-  const steps = [];
-  let failed = false;
-  for (const step of pipeline.steps) {
-    if (failed && !step.always) {
-      steps.push({ name: step.name, outcome: "skipped", exitCode: null, log: "", durationMs: 0 });
-      continue;
-    }
-    const env = {};
-    const values = [];
-    for (const name of step.secrets ?? []) {
-      try {
-        const value = await options.secret(name);
-        env[name] = value;
-        values.push(value);
-      } catch {
-        throw new PipelineError("SECRET_MISSING", `step "${step.name}" needs ${name}, which is not in this compute's scope.`);
-      }
-    }
-    const started = now();
-    let exitCode;
-    let output;
-    try {
-      const result = await options.exec({ command: step.run, env, timeoutMs: step.timeoutMs });
-      exitCode = result.exitCode;
-      output = result.output;
-    } catch (cause) {
-      exitCode = -1;
-      output = cause.message;
-    }
-    const outcome = exitCode === 0 ? "ok" : "failed";
-    if (outcome === "failed")
-      failed = true;
-    steps.push({
-      name: step.name,
-      outcome,
-      exitCode,
-      log: redact(output, values),
-      durationMs: now() - started
-    });
-  }
-  return { pipeline: pipeline.name, ok: !failed, assurance, steps };
-}
-
-// src/socket.ts
 var MAX_LINE_BYTES = 64 * 1024;
 function handleRequest(options, request) {
   switch (request?.op) {
@@ -151,22 +72,6 @@ function handleRequest(options, request) {
         staleForMs: options.cache.staleForMs()
       });
     }
-    case "run": {
-      if (!options.cache) {
-        return Promise.resolve(refuse("NO_SCOPE", "This agent holds no project scope, so it cannot run a pipeline."));
-      }
-      if (!options.exec) {
-        return Promise.resolve(refuse("PIPELINE_DISABLED", "This agent was not started with an executor, so it will not run pipelines."));
-      }
-      const cache = options.cache;
-      const attestation = options.attestation;
-      return runPipeline({
-        pipeline: request.pipeline,
-        secret: (name) => cache.get(name),
-        exec: options.exec,
-        attest: attestation ? async () => ({ report: await attestation.report(""), source: attestation.name }) : undefined
-      }).then((result) => ({ ok: true, op: "run", result })).catch((cause) => refuse(cause.code ?? "PIPELINE_FAILED", cause.message));
-    }
     case "attest": {
       if (!options.attestation) {
         return Promise.resolve(refuse("ATTESTATION_UNAVAILABLE", "No attestation source is configured on this guest. Attestation is refused rather " + "than faked, because a caller that believes it verified one when nothing did is " + "worse off than one told plainly it is unavailable."));
@@ -245,130 +150,2591 @@ function safeOp(line) {
     return JSON.stringify({ op: "unparseable" });
   }
 }
-// src/cache.ts
-class CacheError extends Error {
+
+// src/deployment.ts
+import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { randomUUID } from "crypto";
+import { dirname, join } from "path";
+import { createQueue } from "@forgezero/runtime/queue";
+
+// src/definition.ts
+var PIPELINE_VERSION = 1;
+
+class DefinitionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DefinitionError";
+  }
+}
+var record = (value, where) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new DefinitionError(`${where} must be an object.`);
+  }
+  return value;
+};
+var text = (value, where) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new DefinitionError(`${where} must be a non-empty string.`);
+  }
+  return value;
+};
+var exactKeys = (value, allowed, where) => {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0)
+    throw new DefinitionError(`${where} contains unknown field(s): ${unknown.join(", ")}.`);
+};
+var RESERVED_STEP_ENV = new Set([
+  "PATH",
+  "HOME",
+  "SHELL",
+  "PWD",
+  "BUN_INSTALL",
+  "NODE_OPTIONS",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "GIT_SSH",
+  "GIT_SSH_COMMAND"
+]);
+function parseDeployDefinition(value) {
+  const root = record(value, "pipeline");
+  exactKeys(root, ["version", "name", "requireAttestation", "roles", "steps"], "pipeline");
+  if (root.version !== PIPELINE_VERSION) {
+    throw new DefinitionError(`pipeline.version must be ${PIPELINE_VERSION}.`);
+  }
+  if (!Array.isArray(root.roles) || root.roles.length === 0) {
+    throw new DefinitionError("pipeline.roles must contain at least one role.");
+  }
+  if (!Array.isArray(root.steps) || root.steps.length === 0) {
+    throw new DefinitionError("pipeline.steps must contain at least one step.");
+  }
+  const roles = root.roles.map((raw, index) => {
+    const role = record(raw, `roles[${index}]`);
+    exactKeys(role, ["name", "count", "software"], `roles[${index}]`);
+    const count = Number(role.count);
+    if (!Number.isSafeInteger(count) || count < 1) {
+      throw new DefinitionError(`roles[${index}].count must be a positive integer.`);
+    }
+    if (!Array.isArray(role.software)) {
+      throw new DefinitionError(`roles[${index}].software must be an array.`);
+    }
+    return {
+      name: text(role.name, `roles[${index}].name`),
+      count,
+      software: role.software.map((rawSoftware, softwareIndex) => {
+        const software = record(rawSoftware, `roles[${index}].software[${softwareIndex}]`);
+        exactKeys(software, ["name", "check", "install"], `roles[${index}].software[${softwareIndex}]`);
+        return {
+          name: text(software.name, `roles[${index}].software[${softwareIndex}].name`),
+          check: text(software.check, `roles[${index}].software[${softwareIndex}].check`),
+          install: text(software.install, `roles[${index}].software[${softwareIndex}].install`)
+        };
+      })
+    };
+  });
+  if (new Set(roles.map((role) => role.name)).size !== roles.length) {
+    throw new DefinitionError("pipeline.roles must have unique names.");
+  }
+  const phases = new Set(["build", "release", "migrate", "health"]);
+  const steps = root.steps.map((raw, index) => {
+    const step = record(raw, `steps[${index}]`);
+    exactKeys(step, ["name", "run", "phase", "secrets", "once", "always", "timeoutMs", "when"], `steps[${index}]`);
+    const phase = text(step.phase, `steps[${index}].phase`);
+    if (!phases.has(phase))
+      throw new DefinitionError(`steps[${index}].phase is not supported.`);
+    if (step.secrets !== undefined && (!Array.isArray(step.secrets) || step.secrets.some((name) => typeof name !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name)))) {
+      throw new DefinitionError(`steps[${index}].secrets must contain names only.`);
+    }
+    if (Array.isArray(step.secrets) && new Set(step.secrets).size !== step.secrets.length) {
+      throw new DefinitionError(`steps[${index}].secrets must not contain duplicates.`);
+    }
+    if (Array.isArray(step.secrets) && step.secrets.some((name) => RESERVED_STEP_ENV.has(String(name)))) {
+      throw new DefinitionError(`steps[${index}].secrets may not replace process-control environment variables.`);
+    }
+    const timeoutMs = step.timeoutMs === undefined ? undefined : Number(step.timeoutMs);
+    if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 86400000)) {
+      throw new DefinitionError(`steps[${index}].timeoutMs must be an integer from 1 to 86400000.`);
+    }
+    let when;
+    if (step.when !== undefined) {
+      const conditions = record(step.when, `steps[${index}].when`);
+      when = {};
+      for (const [name, expected] of Object.entries(conditions)) {
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || typeof expected !== "string" || expected.length === 0) {
+          throw new DefinitionError(`steps[${index}].when must map environment names to non-empty strings.`);
+        }
+        when[name] = expected;
+      }
+      if (Object.keys(when).length === 0)
+        throw new DefinitionError(`steps[${index}].when must not be empty.`);
+    }
+    return {
+      name: text(step.name, `steps[${index}].name`),
+      run: text(step.run, `steps[${index}].run`),
+      phase,
+      secrets: step.secrets,
+      once: step.once === true,
+      always: step.always === true,
+      timeoutMs,
+      when
+    };
+  });
+  if (new Set(steps.map((step) => step.name)).size !== steps.length) {
+    throw new DefinitionError("pipeline.steps must have unique names.");
+  }
+  return {
+    version: PIPELINE_VERSION,
+    name: text(root.name, "pipeline.name"),
+    requireAttestation: root.requireAttestation === true,
+    roles,
+    steps
+  };
+}
+function prerequisitePipeline(definition, roleName) {
+  const role = definition.roles.find((candidate) => candidate.name === roleName);
+  if (!role)
+    throw new DefinitionError(`pipeline role does not exist: ${roleName}.`);
+  return {
+    name: `${definition.name}:prerequisites:${role.name}`,
+    requireAttestation: definition.requireAttestation,
+    steps: role.software.map((software) => ({
+      name: `prepare ${software.name}`,
+      run: `${software.check} >/dev/null 2>&1 || { ${software.install}; ${software.check}; }`
+    }))
+  };
+}
+
+// src/pipeline.ts
+class PipelineError extends Error {
   code;
   constructor(code, message) {
     super(message);
     this.code = code;
-    this.name = "CacheError";
+    this.name = "PipelineError";
   }
 }
-var DEFAULT_TTL_MS = 60000;
-var DEFAULT_MAX_STALE_MS = 300000;
-function createSecretCache(options) {
-  const entries = new Map;
+function redact(text2, values) {
+  let out = text2;
+  for (const value of [...values].sort((a, b) => b.length - a.length)) {
+    if (value.length < 8)
+      continue;
+    out = out.split(value).join("\u2022\u2022\u2022\u2022redacted\u2022\u2022\u2022\u2022");
+  }
+  return out;
+}
+async function runPipeline(options) {
   const now = options.now ?? (() => Date.now());
-  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
-  const maxStaleMs = options.maxStaleMs ?? DEFAULT_MAX_STALE_MS;
-  let cursor = 0;
-  let replicated = false;
-  let lastSyncOkMs = now();
-  const loadScope = async () => {
-    if (!options.list)
-      return { loaded: 0, failed: [] };
-    const names = await options.list();
-    const failed = [];
-    let loaded = 0;
-    for (const name of names) {
+  const { pipeline } = options;
+  let assurance = "enrolled";
+  if (options.attest) {
+    try {
+      await options.attest();
+      assurance = "attested";
+    } catch (cause) {
+      if (pipeline.requireAttestation) {
+        throw new PipelineError("ATTESTATION_FAILED", `${pipeline.name} requires attestation and this machine could not produce one: ${cause.message}`);
+      }
+    }
+  } else if (pipeline.requireAttestation) {
+    throw new PipelineError("ATTESTATION_REQUIRED", `${pipeline.name} requires attestation. This agent has no attestation source, so it cannot run it.`);
+  }
+  const steps = [];
+  let failed = false;
+  for (const step of pipeline.steps) {
+    if (failed && !step.always) {
+      steps.push({ name: step.name, outcome: "skipped", exitCode: null, log: "", durationMs: 0 });
+      continue;
+    }
+    const env = {};
+    const values = [];
+    for (const name of step.secrets ?? []) {
       try {
-        const result = await options.fetch(name);
-        entries.set(name, { value: result.value, version: result.version, fetchedAtMs: now() });
-        loaded += 1;
+        const value = await options.secret(name);
+        env[name] = value;
+        values.push(value);
       } catch {
-        failed.push(name);
+        throw new PipelineError("SECRET_MISSING", `step "${step.name}" needs ${name}, which is not in this compute's scope.`);
       }
     }
-    replicated = true;
-    return { loaded, failed };
+    const started = now();
+    let exitCode;
+    let output;
+    try {
+      const result = await options.exec({ command: step.run, env, timeoutMs: step.timeoutMs });
+      exitCode = result.exitCode;
+      output = result.output;
+    } catch (cause) {
+      exitCode = -1;
+      output = cause.message;
+    }
+    const outcome = exitCode === 0 ? "ok" : "failed";
+    if (outcome === "failed")
+      failed = true;
+    steps.push({
+      name: step.name,
+      outcome,
+      exitCode,
+      log: redact(output, values),
+      durationMs: now() - started
+    });
+  }
+  return { pipeline: pipeline.name, ok: !failed, assurance, steps };
+}
+
+// src/deployment.ts
+class DeploymentError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DeploymentError";
+  }
+}
+var shell = async (input) => {
+  const child = Bun.spawn(["bash", "-Eeuo", "pipefail", "-c", input.command], {
+    cwd: input.cwd,
+    env: { ...process.env, ...input.env },
+    detached: true,
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  let forceTimer;
+  const killGroup = (signal) => {
+    try {
+      process.kill(-child.pid, signal);
+    } catch (cause) {
+      if (cause.code !== "ESRCH")
+        throw cause;
+    }
   };
-  return {
-    names: () => [...entries.keys()],
-    get replica() {
-      return replicated;
-    },
-    load: loadScope,
-    get cursor() {
-      return cursor;
-    },
-    async get(name) {
-      const staleFor = now() - lastSyncOkMs;
-      if (staleFor > maxStaleMs) {
-        throw new CacheError("STALE", `Synchronisation has not succeeded for ${Math.round(staleFor / 1000)}s, so this ` + "cache can no longer vouch for what it holds. Refusing rather than serving a value " + "that may already be revoked.");
+  const timer = input.timeoutMs ? setTimeout(() => {
+    killGroup("SIGTERM");
+    forceTimer = setTimeout(() => killGroup("SIGKILL"), 2000);
+  }, input.timeoutMs) : undefined;
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  if (timer)
+    clearTimeout(timer);
+  if (forceTimer)
+    clearTimeout(forceTimer);
+  return { exitCode, output: `${stdout}${stderr}` };
+};
+var quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+function createDeploymentManager(options) {
+  const queue = createQueue({ width: options.width ?? 4 });
+  const activeRevisions = new Map;
+  const exec = options.exec ?? shell;
+  const projectExec = options.projectExec ?? exec;
+  const now = options.now ?? Date.now;
+  const readDefinition = options.readDefinition ?? ((path) => Bun.YAML.parse(readFileSync(path, "utf8")));
+  const credentialsDirectory = process.env.CREDENTIALS_DIRECTORY;
+  const gitCredentialPath = options.gitCredentialPath ?? (credentialsDirectory ? join(credentialsDirectory, "git-deploy-key") : undefined);
+  const knownHostsPath = options.knownHostsPath ?? "/etc/forgezero/git/known_hosts";
+  const persistKnownHosts = () => {
+    if (!options.knownHostsContent)
+      return;
+    const content = `${options.knownHostsContent.trim()}
+`;
+    if (content.length > 16385 || /\r|\0/.test(content)) {
+      throw new DeploymentError("SOURCE_FAILED", "The pinned Git host keys are malformed.");
+    }
+    if (existsSync2(knownHostsPath) && readFileSync(knownHostsPath, "utf8") === content)
+      return;
+    mkdirSync(dirname(knownHostsPath), { recursive: true, mode: 448 });
+    const next = `${knownHostsPath}.${process.pid}.${randomUUID()}.next`;
+    writeFileSync(next, content, { mode: 384, flag: "wx" });
+    renameSync(next, knownHostsPath);
+    chmodSync2(knownHostsPath, 384);
+  };
+  const gitEnvironment = async () => {
+    const https = /^https:\/\//i.test(options.repository);
+    const auth = options.sourceAuth ?? (https ? { kind: "public" } : { kind: "node-ssh" });
+    if (auth.kind === "public") {
+      if (!https)
+        throw new DeploymentError("SOURCE_FAILED", "Public Git sources must use HTTPS.");
+      return { GIT_TERMINAL_PROMPT: "0" };
+    }
+    if (auth.kind === "vault-token") {
+      if (!https)
+        throw new DeploymentError("SOURCE_FAILED", "Vault Git tokens may only be sent to HTTPS sources.");
+      if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(auth.secret)) {
+        throw new DeploymentError("SOURCE_FAILED", "The Git token secret name is invalid.");
       }
-      const cached = entries.get(name);
-      if (cached && now() - cached.fetchedAtMs < ttlMs)
-        return cached.value;
-      let fetched;
-      try {
-        fetched = await options.fetch(name);
-      } catch (cause) {
-        if (cached)
-          return cached.value;
-        throw new CacheError("FETCH_FAILED", cause instanceof Error ? cause.message : `Could not fetch ${name}.`);
+      if (!options.cache) {
+        throw new DeploymentError("SECRET_MISSING", `Git source credential ${auth.secret} is unavailable.`);
       }
-      entries.set(name, { ...fetched, fetchedAtMs: now() });
-      return fetched.value;
-    },
-    async sync() {
-      const result = await options.changes(cursor);
-      if (result.resync) {
-        const dropped = [...entries.keys()];
-        entries.clear();
-        cursor = 0;
-        lastSyncOkMs = now();
-        if (options.list)
-          await loadScope();
-        return { invalidated: dropped, cursor: 0, resync: true };
+      const username = auth.username ?? "x-access-token";
+      if (!/^[A-Za-z0-9._@+-]{1,128}$/.test(username)) {
+        throw new DeploymentError("SOURCE_FAILED", "The Git token username is invalid.");
       }
-      const invalidated = [];
+      const token = await options.cache.get(auth.secret);
+      if (!token || token.length > 8192 || /[\r\n\0]/.test(token)) {
+        throw new DeploymentError("SOURCE_FAILED", `Git source credential ${auth.secret} is malformed.`);
+      }
+      const origin = new URL(options.repository).origin;
+      return {
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: `http.${origin}/.extraHeader`,
+        GIT_CONFIG_VALUE_0: `Authorization: Basic ${Buffer.from(`${username}:${token}`).toString("base64")}`
+      };
+    }
+    if (!gitCredentialPath) {
+      throw new DeploymentError("SOURCE_FAILED", "No Git deploy-key credential was loaded for the agent.");
+    }
+    persistKnownHosts();
+    return {
+      GIT_TERMINAL_PROMPT: "0",
+      GIT_SSH_COMMAND: `ssh -i ${quote(gitCredentialPath)} -o IdentitiesOnly=yes -o BatchMode=yes ` + `-o ConnectTimeout=15 -o StrictHostKeyChecking=yes -o UserKnownHostsFile=${quote(knownHostsPath)}`
+    };
+  };
+  const checked = async (input, code) => {
+    const result = await exec(input);
+    if (result.exitCode !== 0) {
+      throw new DeploymentError(code, result.output.trim() || `${input.command} exited ${result.exitCode}.`);
+    }
+    return result;
+  };
+  const deploy = async (request) => {
+    if (request.revision && !/^[a-f0-9]{40}$/i.test(request.revision)) {
+      throw new DeploymentError("BAD_REVISION", "A deployment revision must be a full 40-character Git commit.");
+    }
+    const stamp = `${new Date(now()).toISOString().replace(/[-:.TZ]/g, "")}-${process.pid}-${randomUUID().slice(0, 8)}`;
+    const release = join(options.root, "releases", stamp);
+    const env = await gitEnvironment();
+    await checked({
+      command: `test -d ${quote(join(options.root, "releases"))} && test -w ${quote(join(options.root, "releases"))}`
+    }, "SOURCE_FAILED");
+    await checked({
+      command: `umask 0007 && git clone --quiet --no-checkout --branch ${quote(options.branch)} --depth 100 ` + `${quote(options.repository)} ${quote(release)}`,
+      env
+    }, "SOURCE_FAILED");
+    if (request.revision) {
+      let present = await exec({
+        command: `git cat-file -e ${quote(`${request.revision}^{commit}`)}`,
+        cwd: release,
+        env
+      });
+      if (present.exitCode !== 0) {
+        await checked({
+          command: `git fetch --quiet --deepen=1000 origin ${quote(options.branch)}`,
+          cwd: release,
+          env
+        }, "SOURCE_FAILED");
+        present = await exec({ command: `git cat-file -e ${quote(`${request.revision}^{commit}`)}`, cwd: release, env });
+      }
+      if (present.exitCode !== 0) {
+        throw new DeploymentError("SOURCE_FAILED", `${request.revision} is not available from ${options.branch}.`);
+      }
+      await checked({
+        command: `git merge-base --is-ancestor ${quote(request.revision)} ${quote(`origin/${options.branch}`)}`,
+        cwd: release,
+        env
+      }, "SOURCE_FAILED");
+    }
+    await checked({
+      command: `git checkout --quiet --detach ${quote(request.revision ?? `origin/${options.branch}`)}`,
+      cwd: release,
+      env
+    }, "SOURCE_FAILED");
+    const head = (await checked({ command: "git rev-parse HEAD", cwd: release, env }, "SOURCE_FAILED")).output.trim();
+    if (request.revision && head !== request.revision) {
+      throw new DeploymentError("SOURCE_FAILED", `Git checked out ${head}, not requested ${request.revision}.`);
+    }
+    const definition = parseDeployDefinition(readDefinition(join(release, ".fz", "deploy.yaml")));
+    const phaseEnvironment = {
+      ...options.environment ?? {},
+      FZ_RELEASE: release,
+      FZ_DEPLOY_REVISION: head,
+      FZ_DEPLOY_BRANCH: options.branch,
+      FZ_DEPLOY_ROLE: options.role,
+      ...options.publicApiUrl ? { PUBLIC_API_URL: options.publicApiUrl } : {}
+    };
+    const phaseExec = ({ command, env: secrets, timeoutMs }) => projectExec({ command, cwd: release, env: { ...phaseEnvironment, ...secrets }, timeoutMs });
+    const secret = async (name) => {
+      if (!options.cache) {
+        throw new DeploymentError("SECRET_MISSING", `${name} is not available on this platform-only agent.`);
+      }
+      return options.cache.get(name);
+    };
+    const attest = options.attestation ? async () => ({ report: await options.attestation.report(head), source: options.attestation.name }) : undefined;
+    const pipelines = [
+      prerequisitePipeline(definition, options.role),
+      ...["build", "migrate", "release", "health"].map((phase) => {
+        return {
+          name: `${definition.name}:${phase}`,
+          requireAttestation: definition.requireAttestation,
+          steps: definition.steps.filter((step) => step.phase === phase && (!step.once || request.coordinator === true) && (!step.when || Object.entries(step.when).every(([name, expected]) => phaseEnvironment[name] === expected)))
+        };
+      })
+    ].filter((pipeline) => pipeline.steps.length > 0);
+    const phases = [];
+    for (const pipeline of pipelines) {
+      const result = await runPipeline({ pipeline, secret, exec: phaseExec, attest });
+      phases.push(result);
+      if (!result.ok) {
+        const failedStep = result.steps.find((step) => step.outcome === "failed");
+        const detail = failedStep?.log.trim().slice(0, 2000);
+        throw new DeploymentError("PIPELINE_FAILED", `${pipeline.name} failed at ${failedStep?.name ?? "unknown step"}` + (detail ? `: ${detail}` : ` (exit ${failedStep?.exitCode ?? "unknown"}).`));
+      }
+    }
+    return {
+      key: options.key,
+      repository: options.repository,
+      branch: options.branch,
+      revision: head,
+      release,
+      ok: true,
+      phases
+    };
+  };
+  return {
+    async latestRevision() {
+      const result = await checked({
+        command: `git ls-remote --exit-code ${quote(options.repository)} ${quote(`refs/heads/${options.branch}`)}`,
+        env: await gitEnvironment()
+      }, "SOURCE_FAILED");
+      const revision = result.output.trim().split(/\s+/)[0] ?? "";
+      if (!/^[a-f0-9]{40}$/i.test(revision)) {
+        throw new DeploymentError("SOURCE_FAILED", `Could not resolve ${options.branch} to one exact commit.`);
+      }
+      return revision.toLowerCase();
+    },
+    deploy(request = {}) {
+      const revisionKey = request.revision ? `${request.revision.toLowerCase()}:${request.coordinator === true ? "coordinator" : "node"}` : undefined;
+      if (revisionKey) {
+        const existing = activeRevisions.get(revisionKey);
+        if (existing)
+          return existing;
+      }
+      const task = queue.run(options.key, () => deploy(request));
+      if (revisionKey) {
+        activeRevisions.set(revisionKey, task);
+        task.result.finally(() => {
+          if (activeRevisions.get(revisionKey) === task)
+            activeRevisions.delete(revisionKey);
+        }).catch(() => {
+          return;
+        });
+      }
+      return task;
+    },
+    snapshot: queue.snapshot,
+    pause: queue.pause,
+    resume: queue.resume,
+    pauseKey: queue.pauseKey,
+    resumeKey: queue.resumeKey,
+    stopKey: queue.stopKey,
+    startKey: queue.startKey,
+    cancel: queue.cancel,
+    stop(deadlineMs) {
+      return queue.stop(deadlineMs);
+    }
+  };
+}
+
+// src/control.ts
+import { chmodSync as chmodSync3, existsSync as existsSync3, unlinkSync as unlinkSync2 } from "fs";
+import { connect, createServer as createServer2 } from "net";
+var DEFAULT_CONTROL_SOCKET = "/run/forgezero/control.sock";
+var MAX_REQUEST_BYTES = 16 * 1024;
+var refused = (code, message) => ({
+  ok: false,
+  error: { code, message }
+});
+async function handleControl(manager, request) {
+  switch (request?.op) {
+    case "deploy": {
+      try {
+        const requested = request.request ?? {};
+        const revision = requested.revision ?? await manager.latestRevision();
+        const task = manager.deploy({ ...requested, revision });
+        return { ok: true, op: "deploy", taskId: task.id, result: await task.result };
+      } catch (cause) {
+        return refused(cause.code ?? "DEPLOY_FAILED", cause instanceof Error ? cause.message : "Deployment failed.");
+      }
+    }
+    case "status":
+      return { ok: true, op: "status", queue: manager.snapshot() };
+    case "pause":
+      manager.pause();
+      return { ok: true, op: "pause", changed: true };
+    case "resume":
+      manager.resume();
+      return { ok: true, op: "resume", changed: true };
+    case "pause-key":
+      if (!request.key)
+        return refused("BAD_REQUEST", "pause-key needs a key.");
+      manager.pauseKey(request.key);
+      return { ok: true, op: "pause-key", changed: true };
+    case "resume-key":
+      if (!request.key)
+        return refused("BAD_REQUEST", "resume-key needs a key.");
+      manager.resumeKey(request.key);
+      return { ok: true, op: "resume-key", changed: true };
+    case "stop-key": {
+      if (!request.key)
+        return refused("BAD_REQUEST", "stop-key needs a key.");
+      const removed = manager.stopKey(request.key);
+      return { ok: true, op: "stop-key", changed: true, removed };
+    }
+    case "start-key":
+      if (!request.key)
+        return refused("BAD_REQUEST", "start-key needs a key.");
+      return { ok: true, op: "start-key", changed: manager.startKey(request.key) };
+    case "cancel":
+      if (!request.id)
+        return refused("BAD_REQUEST", "cancel needs a task id.");
+      return { ok: true, op: "cancel", changed: manager.cancel(request.id) };
+    default:
+      return refused("UNKNOWN_OP", "Unknown agent control operation.");
+  }
+}
+function startControlServer(manager, socketPath = DEFAULT_CONTROL_SOCKET) {
+  if (existsSync3(socketPath))
+    unlinkSync2(socketPath);
+  const server = createServer2((socket) => {
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (buffer.length > MAX_REQUEST_BYTES) {
+        socket.end(`${JSON.stringify(refused("TOO_LARGE", "Control request too large."))}
+`);
+        return;
+      }
+      const newline = buffer.indexOf(`
+`);
+      if (newline === -1)
+        return;
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      Promise.resolve().then(() => JSON.parse(line)).then((request) => handleControl(manager, request)).catch((cause) => refused("BAD_JSON", cause instanceof Error ? cause.message : "Invalid request.")).then((response) => socket.end(`${JSON.stringify(response)}
+`));
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(socketPath, () => chmodSync3(socketPath, 384));
+  return server;
+}
+function requestControl(request, socketPath = DEFAULT_CONTROL_SOCKET) {
+  return new Promise((resolve, reject) => {
+    const socket = connect(socketPath, () => socket.write(`${JSON.stringify(request)}
+`));
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline === -1)
+        return;
+      socket.end();
+      try {
+        resolve(JSON.parse(buffer.slice(0, newline)));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+
+// src/signed-node-http.ts
+import { signRequest as signRequest2 } from "@forgezero/runtime/identity";
+
+class SignedNodeHttpError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "SignedNodeHttpError";
+  }
+}
+var signatureHeader = (envelope) => Buffer.from(JSON.stringify({
+  timestamp: envelope.timestamp,
+  nonce: envelope.nonce,
+  edSignature: envelope.edSignature,
+  mlDsaSignature: envelope.mlDsaSignature
+})).toString("base64url");
+async function postSignedNode(options, path, body) {
+  const url = new URL(options.apiUrl);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
+  url.search = "";
+  url.hash = "";
+  const raw = JSON.stringify(body);
+  const envelope = signRequest2(options.keys, options.nodeKey, {
+    method: "POST",
+    path: url.pathname,
+    query: "",
+    body: raw
+  });
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-fz-node": options.nodeKey,
+      "x-fz-signature": signatureHeader(envelope)
+    },
+    body: raw,
+    signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    const failure = payload;
+    const reason = failure ? failure.error?.message ?? failure.message : undefined;
+    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
+  }
+  return payload;
+}
+
+// src/deployment-pull.ts
+class DeploymentClaimLostError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DeploymentClaimLostError";
+  }
+}
+async function postSigned(options, operation, body) {
+  return postSignedNode(options, `v1/node/deployments/${operation}`, body);
+}
+async function deployClaim(options, claim) {
+  const manager = options.manager ?? options.managerFor?.(claim);
+  if (!manager)
+    throw new Error("deployment pull has no manager for this 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 claimLost = null;
+  const schedule = (overrideMs) => {
+    if (stopped)
+      return;
+    const remaining = Math.max(0, expires - now());
+    const delay = overrideMs ?? Math.max(1000, Math.min(5 * 60000, Math.floor(remaining / 3)));
+    timer = setTimer(() => {
+      if (stopped || renewal)
+        return;
+      let retryDelay;
+      renewal = postSigned(options, "renew", {
+        runKey: claim.runKey,
+        claimToken: claim.claimToken
+      }).then((response) => {
+        expires = response.claimExpiresAtTs;
+        options.onEvent?.("lease-renewed", { runKey: claim.runKey, claimExpiresAtTs: expires });
+      }).catch((cause) => {
+        if (cause instanceof SignedNodeHttpError && cause.status < 500) {
+          claimLost = new DeploymentClaimLostError(cause.message);
+          stopped = true;
+        } else {
+          retryDelay = Math.max(1000, options.renewRetryMs ?? 5000);
+          options.onEvent?.("lease-renew-failed", cause);
+        }
+      }).finally(() => {
+        renewal = null;
+        if (!stopped)
+          schedule(retryDelay);
+      });
+    }, delay);
+  };
+  schedule();
+  let result;
+  try {
+    result = await manager.deploy({ revision: claim.revision, coordinator: true }).result;
+  } finally {
+    stopped = true;
+    clearTimer(timer);
+    await renewal;
+  }
+  if (claimLost)
+    throw claimLost;
+  return result;
+}
+async function completeSigned(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 postSigned(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 pullDeploymentOnce(options) {
+  const claimed = await postSigned(options, "claim", {});
+  if (!claimed.claim)
+    return { status: "idle" };
+  const claim = claimed.claim;
+  let result;
+  try {
+    result = await deployClaim(options, claim);
+  } catch (cause) {
+    if (cause instanceof DeploymentClaimLostError)
+      throw cause;
+    const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
+    await completeSigned(options, {
+      runKey: claim.runKey,
+      claimToken: claim.claimToken,
+      ok: false,
+      detail: reason
+    });
+    return { status: "failed", claim, reason };
+  }
+  await completeSigned(options, {
+    runKey: claim.runKey,
+    claimToken: claim.claimToken,
+    ok: true,
+    detail: `Deployed ${result.revision}.`,
+    release: result.release
+  });
+  return { status: "deployed", claim, result };
+}
+function startDeploymentPull(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));
+  const emit = options.onEvent ?? (() => {});
+  const parallelism = Math.max(1, Math.min(options.parallelism ?? 4, 32));
+  let stopped = false;
+  const workers = Array.from({ length: parallelism }, () => ({ active: null }));
+  const schedule = (worker) => {
+    if (!stopped)
+      worker.timer = setTimer(() => tick(worker), interval);
+  };
+  const tick = (worker) => {
+    if (stopped || worker.active)
+      return;
+    worker.active = pullDeploymentOnce(options).then((result) => emit(result.status, result)).catch((cause) => emit("poll-failed", cause)).finally(() => {
+      worker.active = null;
+      schedule(worker);
+    });
+  };
+  for (const worker of workers)
+    tick(worker);
+  return {
+    async stop() {
+      stopped = true;
+      for (const worker of workers)
+        clearTimer(worker.timer);
+      await Promise.all(workers.map((worker) => worker.active));
+    },
+    get active() {
+      return !stopped;
+    }
+  };
+}
+
+// src/deployment-watch.ts
+import {
+  chmodSync as chmodSync4,
+  closeSync,
+  fsyncSync,
+  mkdirSync as mkdirSync2,
+  openSync,
+  readFileSync as readFileSync2,
+  renameSync as renameSync2,
+  unlinkSync as unlinkSync3,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname as dirname2 } from "path";
+var validState = (value) => {
+  const state = value;
+  return Boolean(state && /^[a-f0-9]{40}$/i.test(state.revision ?? "") && ["pending", "running", "deployed", "failed"].includes(state.outcome ?? "") && Number.isFinite(state.updatedAtTs));
+};
+function readStaticDeploymentState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return validState(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function writeStaticDeploymentState(path, state) {
+  const directory = dirname2(path);
+  mkdirSync2(directory, { recursive: true, mode: 448 });
+  const temporary = `${path}.new-${process.pid}`;
+  let file;
+  try {
+    file = openSync(temporary, "w", 384);
+    writeFileSync2(file, `${JSON.stringify(state)}
+`);
+    fsyncSync(file);
+    closeSync(file);
+    file = undefined;
+    chmodSync4(temporary, 384);
+    renameSync2(temporary, path);
+    const parent = openSync(directory, "r");
+    try {
+      fsyncSync(parent);
+    } finally {
+      closeSync(parent);
+    }
+  } catch (cause) {
+    if (file !== undefined)
+      closeSync(file);
+    try {
+      unlinkSync3(temporary);
+    } catch {}
+    throw cause;
+  }
+}
+function startStaticDeploymentWatch(options) {
+  const interval = Math.max(1000, options.intervalMs ?? 15000);
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  const now = options.now ?? Date.now;
+  const readState = options.readState ?? (() => readStaticDeploymentState(options.statePath));
+  const writeState = options.writeState ?? ((state) => writeStaticDeploymentState(options.statePath, state));
+  const emit = options.onEvent ?? (() => {
+    return;
+  });
+  let stopped = false;
+  let timer;
+  let inFlight = null;
+  const persist = (revision, outcome, detail) => {
+    writeState({ revision, outcome, updatedAtTs: now(), ...detail ? { detail: detail.slice(0, 2000) } : {} });
+  };
+  const schedule = () => {
+    if (!stopped)
+      timer = setTimer(tick, interval);
+  };
+  const run = async () => {
+    const prior = readState();
+    const revision = prior && (prior.outcome === "pending" || prior.outcome === "running") ? prior.revision : await options.manager.latestRevision();
+    const current = options.currentRevision?.();
+    if (prior?.outcome === "deployed" && prior.revision === revision) {
+      emit("unchanged", { revision });
+      return;
+    }
+    if (prior?.outcome === "failed" && prior.revision === revision) {
+      emit("failed-unchanged", { revision, detail: prior.detail });
+      return;
+    }
+    if (!prior && current === revision) {
+      persist(revision, "deployed", "Adopted the already active bootstrap release.");
+      emit("adopted", { revision });
+      return;
+    }
+    persist(revision, "pending", "Observed at the configured branch head.");
+    persist(revision, "running", "Submitted to the keyed deployment queue.");
+    let result;
+    try {
+      result = await options.manager.deploy({ revision, coordinator: options.coordinator }).result;
+    } catch (cause) {
+      const detail = cause instanceof Error ? cause.message : String(cause);
+      persist(revision, "failed", detail);
+      emit("failed", { revision, detail });
+      return;
+    }
+    persist(revision, "deployed", `Activated ${result.release}.`);
+    emit("deployed", { revision, release: result.release });
+  };
+  function tick() {
+    if (stopped || inFlight)
+      return;
+    inFlight = run().catch((cause) => emit("poll-failed", cause)).finally(() => {
+      inFlight = null;
+      schedule();
+    });
+  }
+  tick();
+  return {
+    async stop() {
+      stopped = true;
+      clearTimer(timer);
+      await inFlight;
+    },
+    get active() {
+      return !stopped;
+    }
+  };
+}
+
+// src/guest-enrolment.ts
+import {
+  chmodSync as chmodSync5,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync3,
+  renameSync as renameSync3,
+  statSync,
+  unlinkSync as unlinkSync4,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { dirname as dirname3 } from "path";
+var validBinding = (value, expectedNodeKey) => {
+  if (!value || typeof value !== "object")
+    return false;
+  const row = value;
+  return ["nodeKey", "computeReference", "projectKey", "environmentKey", "tenantSlug"].every((key) => typeof row[key] === "string" && row[key].length > 0) && (!expectedNodeKey || row.nodeKey === expectedNodeKey);
+};
+function loadGuestBinding(path, expectedNodeKey) {
+  if (!existsSync4(path))
+    return null;
+  const mode = statSync(path).mode & 511;
+  if ((mode & 63) !== 0) {
+    throw new Error(`guest enrolment state at ${path} is not private`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync3(path, "utf8"));
+  } catch {
+    throw new Error(`guest enrolment state at ${path} is malformed`);
+  }
+  if (!validBinding(parsed, expectedNodeKey)) {
+    throw new Error(`guest enrolment state at ${path} does not match this node identity`);
+  }
+  return parsed;
+}
+function persistGuestBinding(path, binding) {
+  mkdirSync3(dirname3(path), { recursive: true, mode: 448 });
+  const temporary = `${path}.next`;
+  writeFileSync3(temporary, `${JSON.stringify(binding)}
+`, { mode: 384 });
+  chmodSync5(temporary, 384);
+  renameSync3(temporary, path);
+}
+async function enrolGuestIdentity(options) {
+  const token = options.token?.trim() ?? (options.tokenPath ? readFileSync3(options.tokenPath, "utf8").trim() : "");
+  if (!token.startsWith("fze_"))
+    throw new Error("guest enrolment credential is malformed");
+  const url = new URL(options.apiUrl);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/v1/compute/enrol`.replace(/\/+/g, "/");
+  url.search = "";
+  url.hash = "";
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      token,
+      label: options.label,
+      gitDeployPublicKey: options.gitDeployPublicKey,
+      publicKeys: {
+        ed25519: options.keys.ed25519.publicKey,
+        mlDsa: options.keys.mlDsa.publicKey
+      }
+    }),
+    signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok || !payload?.ok || payload.nodeKey !== options.nodeKey || !payload.computeReference || !payload.projectKey || !payload.environmentKey || !payload.tenantSlug) {
+    throw new Error(payload?.error?.message || `guest enrolment returned HTTP ${response.status}`);
+  }
+  const binding = {
+    nodeKey: payload.nodeKey,
+    computeReference: payload.computeReference,
+    projectKey: payload.projectKey,
+    environmentKey: payload.environmentKey,
+    tenantSlug: payload.tenantSlug
+  };
+  persistGuestBinding(options.statePath, binding);
+  if (options.consume)
+    await options.consume();
+  else if (options.tokenPath)
+    unlinkSync4(options.tokenPath);
+  return binding;
+}
+
+// src/cache.ts
+class CacheError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CacheError";
+  }
+}
+var DEFAULT_TTL_MS = 60000;
+var DEFAULT_MAX_STALE_MS = 300000;
+function createSecretCache(options) {
+  const entries = new Map;
+  const now = options.now ?? (() => Date.now());
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const maxStaleMs = options.maxStaleMs ?? DEFAULT_MAX_STALE_MS;
+  let cursor = 0;
+  let replicated = false;
+  let lastSyncOkMs = now();
+  const loadScope = async () => {
+    if (!options.list)
+      return { loaded: 0, failed: [] };
+    const names = await options.list();
+    const failed = [];
+    let loaded = 0;
+    for (const name of names) {
+      try {
+        const result = await options.fetch(name);
+        entries.set(name, { value: result.value, version: result.version, fetchedAtMs: now() });
+        loaded += 1;
+      } catch {
+        failed.push(name);
+      }
+    }
+    replicated = true;
+    return { loaded, failed };
+  };
+  return {
+    names: () => [...entries.keys()],
+    get replica() {
+      return replicated;
+    },
+    load: loadScope,
+    get cursor() {
+      return cursor;
+    },
+    async get(name) {
+      const staleFor = now() - lastSyncOkMs;
+      if (staleFor > maxStaleMs) {
+        throw new CacheError("STALE", `Synchronisation has not succeeded for ${Math.round(staleFor / 1000)}s, so this ` + "cache can no longer vouch for what it holds. Refusing rather than serving a value " + "that may already be revoked.");
+      }
+      const cached = entries.get(name);
+      if (cached && now() - cached.fetchedAtMs < ttlMs)
+        return cached.value;
+      let fetched;
+      try {
+        fetched = await options.fetch(name);
+      } catch (cause) {
+        if (cached)
+          return cached.value;
+        throw new CacheError("FETCH_FAILED", cause instanceof Error ? cause.message : `Could not fetch ${name}.`);
+      }
+      entries.set(name, { ...fetched, fetchedAtMs: now() });
+      return fetched.value;
+    },
+    async sync() {
+      const result = await options.changes(cursor);
+      if (result.resync) {
+        const dropped = [...entries.keys()];
+        entries.clear();
+        cursor = 0;
+        lastSyncOkMs = now();
+        if (options.list)
+          await loadScope();
+        return { invalidated: dropped, cursor: 0, resync: true };
+      }
+      const invalidated = [];
       for (const name of result.changed) {
         if (entries.delete(name))
           invalidated.push(name);
       }
-      cursor = result.version;
-      lastSyncOkMs = now();
-      return { invalidated, cursor, resync: false };
-    },
-    clear() {
-      entries.clear();
-      cursor = 0;
+      cursor = result.version;
+      lastSyncOkMs = now();
+      return { invalidated, cursor, resync: false };
+    },
+    clear() {
+      entries.clear();
+      cursor = 0;
+    },
+    staleForMs: () => now() - lastSyncOkMs
+  };
+}
+
+// src/node-vault.ts
+function tenantNodeApiUrl(apiUrl, tenantSlug) {
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(tenantSlug))
+    throw new Error("tenant slug is malformed");
+  const url = new URL(apiUrl);
+  url.pathname = `/api/t/${encodeURIComponent(tenantSlug)}`;
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function createNodeVaultCache(options) {
+  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body);
+  return createSecretCache({
+    ttlMs: options.ttlMs,
+    maxStaleMs: options.maxStaleMs,
+    list: async () => {
+      const payload = await post("list", {});
+      if (!Array.isArray(payload.names) || payload.names.some((name) => typeof name !== "string")) {
+        throw new Error("node vault list response is malformed");
+      }
+      return payload.names;
+    },
+    fetch: async (name) => {
+      const payload = await post("read", { name });
+      if (typeof payload.value !== "string" || !Number.isSafeInteger(payload.version)) {
+        throw new Error("node vault read response is malformed");
+      }
+      return { value: payload.value, version: payload.version };
+    },
+    changes: async (since) => {
+      const payload = await post("changes", { since });
+      if (!Number.isSafeInteger(payload.version) || !Array.isArray(payload.changed) || payload.changed.some((name) => typeof name !== "string"))
+        throw new Error("node vault changes response is malformed");
+      return { version: payload.version, changed: payload.changed, resync: payload.resync };
+    }
+  });
+}
+function startNodeVaultSync(cache, options = {}) {
+  const interval = Math.max(1000, options.intervalMs ?? 30000);
+  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 schedule = () => {
+    if (!stopped)
+      timer = setTimer(tick, interval);
+  };
+  const tick = () => {
+    if (stopped || active)
+      return;
+    active = cache.sync().then((result) => options.onEvent?.("synced", result)).catch((cause) => options.onEvent?.("sync-failed", cause)).finally(() => {
+      active = null;
+      schedule();
+    });
+  };
+  schedule();
+  return {
+    async stop() {
+      stopped = true;
+      clearTimer(timer);
+      await active;
+    }
+  };
+}
+
+// src/provisioning-pull.ts
+class ProvisionClaimLostError extends Error {
+}
+var post = (options, operation, body) => postSignedNode(options, `v1/metal/computes/${operation}`, body);
+async function runClaim(options, 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.floor(Math.max(0, expires - now()) / 3));
+    timer = setTimer(() => {
+      if (stopped || renewal)
+        return;
+      let retry;
+      renewal = post(options, "renew", {
+        computeKey: claim.computeKey,
+        claimToken: claim.claimToken
+      }).then((response) => {
+        expires = response.claimExpiresAtTs;
+        options.onEvent?.("lease-renewed", { computeKey: claim.computeKey, claimExpiresAtTs: expires });
+      }).catch((cause) => {
+        if (cause instanceof SignedNodeHttpError && cause.status < 500) {
+          lost = new ProvisionClaimLostError(cause.message);
+          stopped = true;
+        } else {
+          retry = Math.max(1000, options.renewRetryMs ?? 5000);
+          options.onEvent?.("lease-renew-failed", cause);
+        }
+      }).finally(() => {
+        renewal = null;
+        if (!stopped)
+          schedule(retry);
+      });
+    }, delay);
+  };
+  schedule();
+  let result;
+  try {
+    result = await options.run(claim);
+  } finally {
+    stopped = true;
+    clearTimer(timer);
+    await renewal;
+  }
+  if (lost)
+    throw lost;
+  return result;
+}
+async function complete(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 post(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 pullProvisioningOnce(options) {
+  if (options.metalPreflight) {
+    const report = options.metalPreflight();
+    const accepted = await postSignedNode(options, "v1/metal/preflight", report);
+    options.onEvent?.("preflight", { ...report, ready: accepted.ready, state: accepted.state });
+    if (!accepted.ready)
+      return { status: "idle" };
+  }
+  const response = await post(options, "claim", {});
+  if (!response.claim)
+    return { status: "idle" };
+  const claim = response.claim;
+  let result;
+  try {
+    result = await runClaim(options, claim);
+  } catch (cause) {
+    if (cause instanceof ProvisionClaimLostError)
+      throw cause;
+    const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
+    await complete(options, {
+      computeKey: claim.computeKey,
+      claimToken: claim.claimToken,
+      ok: false,
+      detail: reason
+    });
+    return { status: "failed", claim, reason };
+  }
+  await complete(options, {
+    computeKey: claim.computeKey,
+    claimToken: claim.claimToken,
+    ok: true,
+    ...result.guestAddress ? { guestAddress: result.guestAddress } : {}
+  });
+  return { status: claim.action === "delete" ? "terminated" : "running", claim, result };
+}
+function startProvisioningPull(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 = pullProvisioningOnce(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 chmodSync6, existsSync as existsSync6, unlinkSync as unlinkSync6 } from "fs";
+import { connect as connect2, createServer as createServer3 } from "net";
+
+// src/metal-provision.ts
+import { createHash } from "crypto";
+import {
+  existsSync as existsSync5,
+  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync4,
+  readdirSync,
+  statSync as statSync2,
+  unlinkSync as unlinkSync5,
+  writeFileSync as writeFileSync4
+} from "fs";
+import { dirname as dirname4, isAbsolute, join as join2 } from "path";
+
+// src/compute.ts
+class ComputeError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ComputeError";
+  }
+}
+function qemuArgv(spec) {
+  if (spec.vcpu < 1 || spec.memoryGib < 1) {
+    throw new ComputeError("BAD_SPEC", "a guest needs at least 1 vCPU and 1 GiB");
+  }
+  const argv = [
+    "/usr/bin/qemu-system-x86_64",
+    "-name",
+    spec.name,
+    "-accel",
+    "kvm",
+    "-cpu",
+    "host",
+    "-m",
+    `${spec.memoryGib}G`,
+    "-smp",
+    String(spec.vcpu)
+  ];
+  if (spec.confidential) {
+    const { cbitpos, reducedPhysBits, policy } = spec.confidential;
+    argv.push("-machine", `q35,confidential-guest-support=snp,memory-backend=ram`, "-object", `memory-backend-memfd,id=ram,size=${spec.memoryGib}G,share=true`, "-object", `sev-snp-guest,id=snp,cbitpos=${cbitpos},reduced-phys-bits=${reducedPhysBits},policy=${policy}`, "-bios", "/usr/share/ovmf/OVMF.fd");
+  } else {
+    argv.push("-machine", "q35");
+  }
+  argv.push("-drive", `file=${spec.disk},format=raw,if=none,id=disk0,cache=none,aio=native`, "-device", "virtio-blk-pci,drive=disk0,iommu_platform=on", "-drive", `file=${spec.seed},format=raw,if=none,id=seed0,readonly=on`, "-device", "virtio-blk-pci,drive=seed0,iommu_platform=on", "-netdev", spec.tap ? `tap,id=net0,ifname=${spec.tap},script=no,downscript=no` : `bridge,id=net0,br=${spec.bridge}`, "-device", `virtio-net-pci,netdev=net0,mac=${spec.mac},iommu_platform=on`, "-display", "none");
+  if (spec.consoleLog)
+    argv.push("-serial", `file:${spec.consoleLog}`);
+  return argv;
+}
+function guestUnit(spec) {
+  const argv = qemuArgv(spec).map((part) => /[\s"']/.test(part) ? JSON.stringify(part) : part).join(" ");
+  if (spec.egress && !spec.tap) {
+    throw new ComputeError("BAD_SPEC", "shaped egress needs a stable tap device");
+  }
+  const tapSetup = spec.tap ? [
+    `ExecStartPre=-/usr/sbin/ip link del ${spec.tap}`,
+    `ExecStartPre=/usr/sbin/ip tuntap add dev ${spec.tap} mode tap`,
+    `ExecStartPre=/usr/sbin/ip link set ${spec.tap} master ${spec.bridge}`,
+    `ExecStartPre=/usr/sbin/ip link set ${spec.tap} up`,
+    ...spec.egress ? shapeEgressUnitDirectives(spec.tap, spec.egress.guaranteedMbps, spec.egress.burstMbps) : [],
+    `ExecStopPost=-/usr/sbin/ip link del ${spec.tap}`
+  ].join(`
+`) : "";
+  return `[Unit]
+Description=ForgeZero guest ${spec.name}
+Documentation=https://www.forgezero.net
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Slice=forgezero-guests.slice
+${tapSetup}
+ExecStart=${argv}
+Restart=always
+RestartSec=5
+${spec.allowedCpus ? `AllowedCPUs=${spec.allowedCpus}
+` : ""}${spec.allowedMemoryNodes ? `AllowedMemoryNodes=${spec.allowedMemoryNodes}
+` : ""}# The affinity belongs to the unit rather than only QEMU's vCPU threads. Its
+# emulator and IO threads can otherwise run on a different tenant's cores.
+# The agent is NOT the parent. Restarting or upgrading fz-agent must never stop
+# a tenant's compute, which is the whole reason this is a unit rather than a
+# child process.
+KillMode=mixed
+TimeoutStopSec=120
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function shapeEgressUnitDirectives(tap, guaranteedMbps, burstMbps) {
+  if (!/^[a-z][a-z0-9]{0,14}$/.test(tap)) {
+    throw new ComputeError("BAD_SPEC", `"${tap}" is not a device name`);
+  }
+  if (!Number.isInteger(guaranteedMbps) || guaranteedMbps < 0 || !Number.isInteger(burstMbps) || burstMbps < guaranteedMbps) {
+    throw new ComputeError("BAD_SPEC", "egress rates must be whole numbers and burst must cover the guarantee");
+  }
+  const clear = [
+    `ExecStartPre=-/usr/sbin/tc qdisc del dev ${tap} root`,
+    `ExecStartPre=-/usr/sbin/tc qdisc del dev ${tap} ingress`
+  ];
+  if (guaranteedMbps === 0)
+    return clear;
+  return [
+    ...clear,
+    `ExecStartPre=/usr/sbin/tc qdisc add dev ${tap} handle ffff: ingress`,
+    `ExecStartPre=/usr/sbin/tc filter add dev ${tap} parent ffff: protocol all u32 match u32 0 0 action police rate ${burstMbps}mbit burst 16mb conform-exceed drop`
+  ];
+}
+
+// src/provision.ts
+var DEPLOYMENT_RUNNER_USER = "forgezero-runner";
+var DEPLOYMENT_GROUP = "forgezero-deploy";
+var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
+function deploymentRunnerSocketUnit(agentUser) {
+  return `[Unit]
+Description=ForgeZero private project-command socket
+
+[Socket]
+ListenStream=${DEPLOYMENT_RUNNER_SOCKET}
+SocketUser=${agentUser}
+SocketGroup=${agentUser}
+SocketMode=0600
+DirectoryMode=0710
+RemoveOnStop=true
+
+[Install]
+WantedBy=sockets.target
+`;
+}
+function deploymentRunnerUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  const root = options.deployRoot ?? "/opt/forgezero";
+  return `[Unit]
+Description=ForgeZero credential-free project command runner
+Documentation=https://www.forgezero.net/docs/agent
+After=forgezero-deploy-runner.socket
+Requires=forgezero-deploy-runner.socket
+
+[Service]
+Type=simple
+User=${DEPLOYMENT_RUNNER_USER}
+Group=${DEPLOYMENT_GROUP}
+Environment=FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}
+Sockets=forgezero-deploy-runner.socket
+ExecStart=${bin} deploy-runner --root=${root} --home=${root}/runner-home
+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/metal-provision.ts
+var SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
+var DEVICE = /^[a-zA-Z][a-zA-Z0-9_.-]{0,14}$/;
+var SHA256 = /^[a-f0-9]{64}$/;
+var IPV4_PREFIX = /^(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d)$/;
+var LINUX_LIST = /^\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$/;
+
+class MetalProvisionError extends Error {
+}
+function membersOfLinuxList(value, label) {
+  if (!LINUX_LIST.test(value))
+    throw new MetalProvisionError(`invalid ${label} list`);
+  const members = [];
+  for (const part of value.split(",")) {
+    const [startText, endText = startText] = part.split("-");
+    const start = Number(startText);
+    const end = Number(endText);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end > 65535) {
+      throw new MetalProvisionError(`invalid ${label} list`);
+    }
+    for (let value2 = start;value2 <= end; value2 += 1)
+      members.push(value2);
+  }
+  if (new Set(members).size !== members.length)
+    throw new MetalProvisionError(`${label} list overlaps itself`);
+  return members;
+}
+var guestNameFor = (computeKey) => `fzg-${createHash("sha256").update(computeKey).digest("hex").slice(0, 16)}`;
+var tapNameFor = (computeKey) => `fzt${createHash("sha256").update(computeKey).digest("hex").slice(0, 12)}`;
+var macForAddress = (address) => {
+  const octets = address.split(".").map(Number);
+  if (octets.length !== 4 || octets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) {
+    throw new MetalProvisionError("invalid guest address");
+  }
+  return `52:54:00:f0:${octets[2].toString(16).padStart(2, "0")}:${octets[3].toString(16).padStart(2, "0")}`;
+};
+function validateMetalProfile(profile) {
+  if (!SAFE_NAME.test(profile.volumeGroup))
+    throw new MetalProvisionError("invalid volume group");
+  if (!DEVICE.test(profile.bridge))
+    throw new MetalProvisionError("invalid bridge");
+  if (!IPV4_PREFIX.test(profile.subnetPrefix))
+    throw new MetalProvisionError("invalid subnet prefix");
+  if (!Number.isInteger(profile.addressStart) || !Number.isInteger(profile.addressEnd) || profile.addressStart < 2 || profile.addressEnd > 254 || profile.addressStart > profile.addressEnd)
+    throw new MetalProvisionError("invalid guest address range");
+  for (const path of [profile.stateDir, profile.seedDir, profile.unitDir]) {
+    if (!isAbsolute(path))
+      throw new MetalProvisionError("metal paths must be absolute");
+  }
+  new URL(profile.apiUrl);
+  if (!Array.isArray(profile.cpuPools) || profile.cpuPools.length === 0) {
+    throw new MetalProvisionError("at least one exclusive CPU pool is required");
+  }
+  const keys = new Set;
+  const assigned = new Set;
+  const assignedMemory = new Set;
+  let poolsWithMemory = 0;
+  for (const pool of profile.cpuPools) {
+    if (!SAFE_NAME.test(pool.key) || keys.has(pool.key))
+      throw new MetalProvisionError("invalid or duplicate CPU pool key");
+    keys.add(pool.key);
+    const cpus = membersOfLinuxList(pool.cpus, "CPU");
+    if (!Number.isInteger(pool.physicalCores) || pool.physicalCores < 1 || pool.physicalCores > cpus.length) {
+      throw new MetalProvisionError("invalid CPU pool physical-core count");
+    }
+    for (const cpu of cpus) {
+      if (assigned.has(cpu))
+        throw new MetalProvisionError("CPU pools overlap");
+      assigned.add(cpu);
+    }
+    if (pool.memoryNodes) {
+      poolsWithMemory += 1;
+      for (const node of membersOfLinuxList(pool.memoryNodes, "memory-node")) {
+        if (assignedMemory.has(node))
+          throw new MetalProvisionError("guest memory-node pools overlap");
+        assignedMemory.add(node);
+      }
+    }
+  }
+  if (poolsWithMemory !== 0 && poolsWithMemory !== profile.cpuPools.length) {
+    throw new MetalProvisionError("every CPU pool must name memory nodes when NUMA isolation is enabled");
+  }
+  const housekeeping = membersOfLinuxList(profile.housekeepingCpus, "housekeeping CPU");
+  if (housekeeping.some((cpu) => assigned.has(cpu))) {
+    throw new MetalProvisionError("housekeeping CPUs overlap guest CPU pools");
+  }
+  if (profile.housekeepingMemoryNodes) {
+    const housekeepingMemory = membersOfLinuxList(profile.housekeepingMemoryNodes, "housekeeping memory-node");
+    if (housekeepingMemory.some((node) => assignedMemory.has(node))) {
+      throw new MetalProvisionError("housekeeping memory nodes overlap guest memory-node pools");
+    }
+  } else if (assignedMemory.size > 0) {
+    throw new MetalProvisionError("NUMA-isolated guest pools require housekeeping memory nodes");
+  }
+}
+var readManifests = (stateDir) => {
+  if (!existsSync5(stateDir))
+    return [];
+  return readdirSync(stateDir).filter((name) => name.endsWith(".json")).map((name) => JSON.parse(readFileSync4(join2(stateDir, name), "utf8")));
+};
+function allocateAddress(profile, computeKey, rows) {
+  const existing = rows.find((row) => row.computeKey === computeKey);
+  if (existing)
+    return existing.address;
+  const used = new Set(rows.map((row) => row.address));
+  const width = profile.addressEnd - profile.addressStart + 1;
+  const start = createHash("sha256").update(computeKey).digest().readUInt16BE(0) % width;
+  for (let offset = 0;offset < width; offset += 1) {
+    const last = profile.addressStart + (start + offset) % width;
+    const address = `${profile.subnetPrefix}.${last}`;
+    if (!used.has(address))
+      return address;
+  }
+  throw new MetalProvisionError("guest address range is full");
+}
+function allocateCpuPool(profile, claim, rows) {
+  const prior = rows.find((row) => row.computeKey === claim.computeKey);
+  if (prior) {
+    const retained = profile.cpuPools.find((pool) => pool.key === prior.cpuPoolKey);
+    if (!retained || retained.cpus !== prior.allowedCpus || retained.memoryNodes !== prior.allowedMemoryNodes) {
+      throw new MetalProvisionError("persisted guest CPU pool no longer matches the host profile");
+    }
+    return retained;
+  }
+  const used = new Set(rows.map((row) => row.cpuPoolKey));
+  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)
+    throw new MetalProvisionError("no exclusive CPU pool can satisfy this guest");
+  return selected;
+}
+var base64 = (value) => Buffer.from(value).toString("base64");
+var yamlFile = (path, content, permissions) => `  - path: ${JSON.stringify(path)}
+    permissions: '${permissions}'
+    encoding: b64
+    content: ${base64(content)}
+`;
+function guestBootstrapScript(profile, attested = Boolean(profile.confidential)) {
+  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
+# load the exact running-kernel module before the agent is allowed to start.
+DEBIAN_FRONTEND=noninteractive apt-get install -y linux-image-generic "linux-modules-extra-$(uname -r)"
+printf 'sev-guest
+' >/etc/modules-load.d/sev-guest.conf
+modprobe sev-guest
+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
+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
+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
+  curl -fsSL https://bun.sh/install -o /run/fz-bun-install
+  printf '%s  %s
+' '${profile.bunInstallerSha256}' /run/fz-bun-install | sha256sum -c -
+  BUN_INSTALL=${agentBun} BUN_VERSION=${profile.bunVersion} bash /run/fz-bun-install
+  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
+  env BUN_INSTALL=${agentBun} /usr/local/bin/bun add -g @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 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
+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=forgezero-agent
+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=true
+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
+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
+`;
+}
+function cloudInit(profile, claim, manifest) {
+  const bootstrap = guestBootstrapScript(profile, claim.spec.confidential);
+  const agentUnit = guestAgentUnit(profile, manifest.name, claim.spec.confidential);
+  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" });
+  return {
+    userData: `#cloud-config
+package_update: 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", agentUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service.d/enrolment.conf", enrolmentDropIn, "0644")}${yamlFile("/etc/systemd/system/forgezero-enrolment-cleanup.service", cleanupUnit, "0644")}runcmd:
+  - [ bash, /usr/local/sbin/forgezero-guest-bootstrap ]
+  - [ systemctl, enable, --now, forgezero-enrolment-cleanup.service ]
+`,
+    metaData: `instance-id: ${manifest.name}-${claim.attempt}
+local-hostname: ${manifest.name}
+`,
+    networkConfig: `version: 2
+ethernets:
+  primary:
+    match: { name: "en*" }
+    addresses: [ ${manifest.address}/24 ]
+    gateway4: ${profile.gateway}
+    nameservers: { addresses: [${(profile.nameservers ?? ["1.1.1.1", "9.9.9.9"]).join(", ")}] }
+`
+  };
+}
+var checked = async (exec, argv) => {
+  const result = await exec(argv);
+  if (result.exitCode !== 0) {
+    throw new MetalProvisionError(`${argv[0]} failed: ${(result.stderr || result.stdout).trim()}`);
+  }
+  return result;
+};
+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)
+    throw new MetalProvisionError("invalid compute claim");
+  const image = profile.images[claim.spec.imageKey];
+  if (!image || !isAbsolute(image.path) || !SHA256.test(image.sha256)) {
+    throw new MetalProvisionError(`image ${claim.spec.imageKey} is not configured locally`);
+  }
+  if (!statSync2(image.path).isFile())
+    throw new MetalProvisionError("configured image is not a file");
+  const digest = (await checked(exec, ["sha256sum", image.path])).stdout.trim().split(/\s+/)[0];
+  if (digest !== image.sha256)
+    throw new MetalProvisionError("configured image checksum mismatch");
+  for (const path of [profile.stateDir, profile.seedDir, profile.unitDir])
+    mkdirSync4(path, { recursive: true, mode: 448 });
+  const manifests = readManifests(profile.stateDir);
+  const name = guestNameFor(claim.computeKey);
+  const manifestPath = join2(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 cpuPool = allocateCpuPool(profile, claim, manifests);
+  const manifest = prior ?? {
+    computeKey: claim.computeKey,
+    reference: claim.spec.reference,
+    name,
+    address,
+    mac: macForAddress(address),
+    cpuPoolKey: cpuPool.key,
+    allowedCpus: cpuPool.cpus,
+    allowedMemoryNodes: cpuPool.memoryNodes,
+    phase: "allocating"
+  };
+  const save = () => writeFileSync4(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`, { mode: 384 });
+  save();
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
+  const exists = (await exec(["lvs", "--noheadings", lv])).exitCode === 0;
+  if (!exists)
+    await checked(exec, ["lvcreate", "-y", "-n", name, "-L", `${claim.spec.diskGib}G`, profile.volumeGroup]);
+  if (manifest.phase === "allocating") {
+    await checked(exec, ["qemu-img", "convert", "-O", "raw", image.path, lv]);
+    manifest.phase = "image-ready";
+    save();
+  }
+  const seedBase = join2(profile.seedDir, name);
+  const init = cloudInit(profile, claim, manifest);
+  writeFileSync4(`${seedBase}-user-data`, init.userData, { mode: 384 });
+  writeFileSync4(`${seedBase}-meta-data`, init.metaData, { mode: 384 });
+  writeFileSync4(`${seedBase}-network-config`, init.networkConfig, { mode: 384 });
+  const seed = `${seedBase}-seed.iso`;
+  await checked(exec, [
+    "cloud-localds",
+    "-N",
+    `${seedBase}-network-config`,
+    seed,
+    `${seedBase}-user-data`,
+    `${seedBase}-meta-data`
+  ]);
+  const spec = {
+    name,
+    vcpu: claim.spec.vcpu,
+    memoryGib: claim.spec.memoryGib,
+    allowedCpus: manifest.allowedCpus,
+    allowedMemoryNodes: manifest.allowedMemoryNodes,
+    disk: lv,
+    seed,
+    bridge: profile.bridge,
+    mac: manifest.mac,
+    tap: tapNameFor(claim.computeKey),
+    egress: {
+      guaranteedMbps: claim.spec.egressGuaranteedMbps,
+      burstMbps: claim.spec.egressBurstMbps
     },
-    staleForMs: () => now() - lastSyncOkMs
+    confidential: claim.spec.confidential ? profile.confidential : undefined,
+    consoleLog: `/var/log/forgezero/${name}.log`
+  };
+  if (claim.spec.confidential && !spec.confidential) {
+    throw new MetalProvisionError("confidential compute requested but host SNP profile is absent");
+  }
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join2(profile.unitDir, service);
+  mkdirSync4(dirname4(unitPath), { recursive: true });
+  writeFileSync4(unitPath, guestUnit(spec), { mode: 420 });
+  await checked(exec, ["systemctl", "daemon-reload"]);
+  if (prior?.phase === "running") {
+    await checked(exec, ["systemctl", "restart", service]);
+  } else {
+    await checked(exec, ["systemctl", "enable", "--now", service]);
+  }
+  await checked(exec, ["systemctl", "is-active", service]);
+  manifest.phase = "running";
+  save();
+  return { guestAddress: address };
+}
+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 manifestPath = join2(profile.stateDir, `${name}.json`);
+  if (!existsSync5(manifestPath))
+    return {};
+  const manifest = JSON.parse(readFileSync4(manifestPath, "utf8"));
+  if (manifest.computeKey !== claim.computeKey || manifest.reference !== claim.spec.reference || manifest.name !== name) {
+    throw new MetalProvisionError("compute identity conflicts with host inventory");
+  }
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join2(profile.unitDir, service);
+  if (existsSync5(unitPath))
+    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");
+  }
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
+  if ((await exec(["lvs", "--noheadings", lv])).exitCode === 0)
+    await checked(exec, ["lvremove", "-fy", lv]);
+  for (const path of [
+    unitPath,
+    join2(profile.seedDir, `${name}-seed.iso`),
+    join2(profile.seedDir, `${name}-user-data`),
+    join2(profile.seedDir, `${name}-meta-data`),
+    join2(profile.seedDir, `${name}-network-config`),
+    manifestPath
+  ])
+    if (existsSync5(path))
+      unlinkSync5(path);
+  await checked(exec, ["systemctl", "daemon-reload"]);
+  return {};
+}
+
+// src/metal-helper-socket.ts
+var DEFAULT_METAL_HELPER_SOCKET = "/run/forgezero-metal/helper.sock";
+var MAX_REQUEST_BYTES2 = 32 * 1024;
+var REQUEST_READ_TIMEOUT_MS = 5000;
+var COMMAND_TIMEOUT_MS = 30 * 60000;
+var spawnMetalCommand = async (argv) => {
+  const child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: "/usr/sbin:/usr/bin:/sbin:/bin" } });
+  let timedOut = false;
+  let forceTimer;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+    forceTimer = setTimeout(() => child.kill("SIGKILL"), 5000);
+  }, COMMAND_TIMEOUT_MS);
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  clearTimeout(timer);
+  if (forceTimer)
+    clearTimeout(forceTimer);
+  return {
+    exitCode: timedOut ? 124 : exitCode,
+    stdout,
+    stderr: timedOut ? `${stderr}
+command exceeded ${COMMAND_TIMEOUT_MS}ms`.trim() : stderr
+  };
+};
+function startMetalHelper(options) {
+  validateMetalProfile(options.profile);
+  const socketPath = options.socketPath ?? DEFAULT_METAL_HELPER_SOCKET;
+  if (existsSync6(socketPath))
+    unlinkSync6(socketPath);
+  let tail = Promise.resolve();
+  const server = createServer3((socket) => {
+    let buffer = "";
+    socket.setTimeout(REQUEST_READ_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_BYTES2) {
+        socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request too large" } })}
+`);
+        return;
+      }
+      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 {
+          const exec = options.exec ?? spawnMetalCommand;
+          return { ok: true, result: request.claim.action === "delete" ? await removeMetalGuest(options.profile, request.claim, exec) : await provisionMetalGuest(options.profile, request.claim, exec) };
+        } catch (cause) {
+          return { ok: false, error: { code: "FAILED", message: cause instanceof Error ? cause.message : "provisioning 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, () => chmodSync6(socketPath, 432));
+  return {
+    server,
+    async stop() {
+      await new Promise((resolve) => server.close(() => resolve()));
+      await tail;
+    }
+  };
+}
+function requestMetalProvision(claim, socketPath = DEFAULT_METAL_HELPER_SOCKET) {
+  return new Promise((resolve, reject) => {
+    const socket = connect2(socketPath, () => socket.write(`${JSON.stringify({ op: "apply", claim })}
+`));
+    socket.setTimeout(COMMAND_TIMEOUT_MS + 1e4, () => {
+      socket.destroy();
+      reject(new Error("metal 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)
+          resolve(response.result);
+        else
+          reject(new Error(response.error.message));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+
+// src/deployment-runner.ts
+import { chmodSync as chmodSync7, existsSync as existsSync7, realpathSync, unlinkSync as unlinkSync7 } from "fs";
+import { isAbsolute as isAbsolute2, resolve, sep } from "path";
+import { connect as connect3, createServer as createServer4 } from "net";
+var DEFAULT_DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
+var MAX_REQUEST_BYTES3 = 256 * 1024;
+var MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+var MAX_RESPONSE_BYTES = 2 * MAX_OUTPUT_BYTES + MAX_REQUEST_BYTES3;
+var READ_TIMEOUT_MS = 5000;
+var MAX_COMMAND_TIMEOUT_MS = 60 * 60000;
+function within(root, candidate) {
+  return candidate === root || candidate.startsWith(`${root}${sep}`);
+}
+function validate(root, input) {
+  if (!input || typeof input.command !== "string" || input.command.length < 1 || input.command.length > 64 * 1024) {
+    throw new Error("invalid deployment command");
+  }
+  if (!input.cwd || !isAbsolute2(input.cwd))
+    throw new Error("deployment command needs an absolute working directory");
+  const realRoot = realpathSync(root);
+  const realCwd = realpathSync(input.cwd);
+  if (!within(realRoot, realCwd))
+    throw new Error("deployment command escaped the release root");
+  const timeoutMs = Math.trunc(input.timeoutMs ?? 10 * 60000);
+  if (timeoutMs < 1000 || timeoutMs > MAX_COMMAND_TIMEOUT_MS)
+    throw new Error("invalid deployment command timeout");
+  const env = {};
+  let environmentBytes = 0;
+  for (const [name, value] of Object.entries(input.env ?? {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || typeof value !== "string") {
+      throw new Error("invalid deployment environment");
+    }
+    environmentBytes += Buffer.byteLength(name) + Buffer.byteLength(value);
+    if (environmentBytes > 128 * 1024)
+      throw new Error("deployment environment is too large");
+    env[name] = value;
+  }
+  return { command: input.command, cwd: realCwd, env, timeoutMs };
+}
+async function limited(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder;
+  let output = "";
+  let remaining = MAX_OUTPUT_BYTES;
+  for (;; ) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    if (remaining > 0) {
+      const chunk = value.byteLength <= remaining ? value : value.subarray(0, remaining);
+      output += decoder.decode(chunk, { stream: true });
+      remaining -= chunk.byteLength;
+    }
+  }
+  output += decoder.decode();
+  return remaining === 0 ? `${output}
+[output truncated at ${MAX_OUTPUT_BYTES} bytes]` : output;
+}
+async function execute(input, home) {
+  const child = Bun.spawn(["bash", "-Eeuo", "pipefail", "-c", input.command], {
+    cwd: input.cwd,
+    detached: true,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      PATH: "/usr/local/bin:/usr/bin:/bin",
+      HOME: home,
+      XDG_CACHE_HOME: `${home}/cache`,
+      LANG: "C.UTF-8",
+      ...input.env ?? {}
+    }
+  });
+  let timedOut = false;
+  let forceTimer;
+  const killGroup = (signal) => {
+    try {
+      process.kill(-child.pid, signal);
+    } catch (cause) {
+      if (cause.code !== "ESRCH")
+        throw cause;
+    }
+  };
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killGroup("SIGTERM");
+    forceTimer = setTimeout(() => killGroup("SIGKILL"), 2000);
+  }, input.timeoutMs);
+  const [stdout, stderr, exitCode] = await Promise.all([
+    limited(child.stdout),
+    limited(child.stderr),
+    child.exited
+  ]);
+  clearTimeout(timer);
+  if (forceTimer)
+    clearTimeout(forceTimer);
+  return {
+    exitCode: timedOut ? 124 : exitCode,
+    output: `${stdout}${stderr}${timedOut ? `
+command exceeded ${input.timeoutMs}ms` : ""}`
+  };
+}
+function startDeploymentRunner(options) {
+  const root = resolve(options.root);
+  const home = resolve(options.home);
+  const socketPath = options.socketPath ?? DEFAULT_DEPLOYMENT_RUNNER_SOCKET;
+  if (options.listenFd === undefined && existsSync7(socketPath))
+    unlinkSync7(socketPath);
+  const active = new Set;
+  const server = createServer4((socket) => {
+    let buffer = "";
+    socket.setTimeout(READ_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.byteLength(buffer) > MAX_REQUEST_BYTES3) {
+        socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request too large" } })}
+`);
+        return;
+      }
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.setTimeout(0);
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      const work = (async () => {
+        try {
+          const input = validate(root, JSON.parse(line));
+          return { ok: true, result: await (options.exec ?? execute)(input, home) };
+        } catch (cause) {
+          return {
+            ok: false,
+            error: { code: "REFUSED", message: cause instanceof Error ? cause.message : "deployment command refused" }
+          };
+        }
+      })();
+      active.add(work);
+      work.finally(() => active.delete(work));
+      work.then((response) => socket.end(`${JSON.stringify(response)}
+`));
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  if (options.listenFd !== undefined)
+    server.listen({ fd: options.listenFd });
+  else
+    server.listen(socketPath, () => chmodSync7(socketPath, 432));
+  return {
+    server,
+    async stop() {
+      await new Promise((resolveStop) => server.close(() => resolveStop()));
+      await Promise.all(active);
+    }
+  };
+}
+function requestDeploymentCommand(input, socketPath = DEFAULT_DEPLOYMENT_RUNNER_SOCKET) {
+  return new Promise((resolveRequest, reject) => {
+    const socket = connect3(socketPath, () => socket.write(`${JSON.stringify(input)}
+`));
+    const timeout = Math.max(1000, input.timeoutMs ?? 10 * 60000) + 1e4;
+    socket.setTimeout(timeout, () => {
+      socket.destroy();
+      reject(new Error("deployment runner response timed out"));
+    });
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer) > MAX_RESPONSE_BYTES) {
+        socket.destroy();
+        reject(new Error("deployment runner response is too large"));
+        return;
+      }
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.end();
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        if (response.ok)
+          resolveRequest(response.result);
+        else
+          reject(new Error(response.error.message));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+
+// src/snp-attestation.ts
+import { existsSync as existsSync8 } from "fs";
+import { REPORT_BYTES } from "@forgezero/runtime/snp";
+var SNP_REPORT_HELPER = String.raw`
+import base64
+import ctypes
+import errno
+import os
+import re
+import sys
+
+REPORT_BYTES = 1184
+RESPONSE_BYTES = 4000
+RESPONSE_HEADER_BYTES = 32
+
+if len(sys.argv) != 3:
+    raise SystemExit("usage: snp-report NONCE_HEX DEVICE")
+
+nonce = sys.argv[1]
+device = sys.argv[2]
+if not re.fullmatch(r"[0-9a-fA-F]{64}", nonce):
+    raise SystemExit("the SNP challenge must be exactly 32 bytes of hex")
+if device != "/dev/sev-guest":
+    raise SystemExit("the SNP report source only accepts /dev/sev-guest")
+
+class ReportRequest(ctypes.Structure):
+    _fields_ = [
+        ("user_data", ctypes.c_ubyte * 64),
+        ("vmpl", ctypes.c_uint32),
+        ("reserved", ctypes.c_ubyte * 28),
+    ]
+
+class ReportResponse(ctypes.Structure):
+    _fields_ = [("data", ctypes.c_ubyte * RESPONSE_BYTES)]
+
+class GuestRequestIoctl(ctypes.Structure):
+    _fields_ = [
+        ("msg_version", ctypes.c_uint8),
+        ("req_data", ctypes.c_uint64),
+        ("resp_data", ctypes.c_uint64),
+        ("exitinfo2", ctypes.c_uint64),
+    ]
+
+def ioc(direction, kind, number, size):
+    return (direction << 30) | (size << 16) | (ord(kind) << 8) | number
+
+request = ReportRequest()
+for index, value in enumerate(bytes.fromhex(nonce)):
+    request.user_data[index] = value
+
+response = ReportResponse()
+argument = GuestRequestIoctl(
+    msg_version=1,
+    req_data=ctypes.addressof(request),
+    resp_data=ctypes.addressof(response),
+    exitinfo2=0,
+)
+
+# _IOWR('S', 0x0, struct snp_guest_request_ioctl)
+snp_get_report = ioc(3, "S", 0, ctypes.sizeof(GuestRequestIoctl))
+libc = ctypes.CDLL(None, use_errno=True)
+libc.ioctl.argtypes = [ctypes.c_int, ctypes.c_ulong, ctypes.c_void_p]
+libc.ioctl.restype = ctypes.c_int
+
+descriptor = os.open(device, os.O_RDWR | os.O_CLOEXEC)
+try:
+    result = libc.ioctl(descriptor, snp_get_report, ctypes.byref(argument))
+finally:
+    os.close(descriptor)
+
+if result != 0:
+    code = ctypes.get_errno()
+    firmware = argument.exitinfo2 & 0xffffffff
+    vmm = argument.exitinfo2 >> 32
+    detail = os.strerror(code) if code else errno.errorcode.get(code, "unknown error")
+    raise SystemExit(f"SNP_GET_REPORT failed: {detail}; firmware={firmware}; vmm={vmm}")
+
+raw = bytes(response.data)
+status = int.from_bytes(raw[0:4], "little")
+report_size = int.from_bytes(raw[4:8], "little")
+if status != 0 or report_size != REPORT_BYTES:
+    raise SystemExit(f"SNP report response invalid: status={status}; size={report_size}")
+report = raw[RESPONSE_HEADER_BYTES:RESPONSE_HEADER_BYTES + REPORT_BYTES]
+sys.stdout.write(base64.b64encode(report).decode("ascii"))
+`;
+function createSnpAttestationSource(options = {}) {
+  const device = options.device ?? "/dev/sev-guest";
+  const python = options.python ?? "python3";
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const spawn = options.spawn ?? Bun.spawn;
+  const exists = options.exists ?? existsSync8;
+  return {
+    name: "linux-sev-guest",
+    async report(nonce) {
+      if (!/^[0-9a-f]{64}$/i.test(nonce)) {
+        throw new Error("the SNP challenge must be exactly 32 bytes of hex");
+      }
+      if (device !== "/dev/sev-guest" || !exists(device)) {
+        throw new Error("/dev/sev-guest is unavailable");
+      }
+      const child = spawn([python, "-c", SNP_REPORT_HELPER, nonce, device], {
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      const timer = setTimeout(() => child.kill(), timeoutMs);
+      try {
+        const [exitCode, stdout, stderr] = await Promise.all([
+          child.exited,
+          new Response(child.stdout).text(),
+          new Response(child.stderr).text()
+        ]);
+        if (exitCode !== 0) {
+          throw new Error(stderr.trim() || `SNP report helper exited ${exitCode}`);
+        }
+        const report = stdout.trim();
+        const bytes = Uint8Array.from(Buffer.from(report, "base64"));
+        if (bytes.length !== REPORT_BYTES) {
+          throw new Error(`SNP report helper returned ${bytes.length} bytes; expected ${REPORT_BYTES}`);
+        }
+        return report;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  };
+}
+
+// src/attestation-client.ts
+async function attestNodeOnce(options) {
+  const challenge = await postSignedNode(options, "v1/node/attest/challenge", {});
+  if (!/^[0-9a-f]{64}$/i.test(challenge.nonce) || !Number.isSafeInteger(challenge.expiresAtSec)) {
+    throw new Error("attestation challenge response is malformed");
+  }
+  const report = await options.source.report(challenge.nonce);
+  const verdict = await postSignedNode(options, "v1/node/attest", { nonce: challenge.nonce, report });
+  if (!verdict.verified || !/^[0-9a-f]{96}$/i.test(verdict.measurement)) {
+    throw new Error("attestation verdict response is malformed");
+  }
+  return { measurement: verdict.measurement, ageMs: verdict.ageMs };
+}
+function startNodeAttestation(options) {
+  const interval = Math.max(5000, options.intervalMs ?? 30000);
+  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 schedule = () => {
+    if (!stopped)
+      timer = setTimer(tick, interval);
+  };
+  const tick = () => {
+    if (stopped || active)
+      return;
+    active = attestNodeOnce(options).then((result) => options.onEvent?.("verified", result)).catch((cause) => options.onEvent?.("failed", cause)).finally(() => {
+      active = null;
+      schedule();
+    });
+  };
+  if (options.immediate === false)
+    schedule();
+  else
+    tick();
+  return {
+    async stop() {
+      stopped = true;
+      clearTimer(timer);
+      await active;
+    }
   };
 }
 
+// src/metal-isolation.ts
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "fs";
+import { join as join3 } from "path";
+var members = (list) => list.split(",").flatMap((part) => {
+  const [first, last = first] = part.split("-").map(Number);
+  return Array.from({ length: last - first + 1 }, (_, index) => first + index);
+});
+var compact = (values) => {
+  const sorted = [...new Set(values)].sort((left, right) => left - right);
+  const ranges = [];
+  for (let index = 0;index < sorted.length; ) {
+    const first = sorted[index];
+    let last = first;
+    while (sorted[index + 1] === last + 1)
+      last = sorted[++index];
+    ranges.push(first === last ? String(first) : `${first}-${last}`);
+    index += 1;
+  }
+  return ranges.join(",");
+};
+var memoryDirective = (nodes) => nodes ? `AllowedMemoryNodes=${nodes}
+` : "";
+function metalGuestSliceUnit(profile) {
+  validateMetalProfile(profile);
+  const cpus = compact(profile.cpuPools.flatMap((pool) => members(pool.cpus)));
+  const nodes = compact(profile.cpuPools.flatMap((pool) => pool.memoryNodes ? members(pool.memoryNodes) : [])) || undefined;
+  return `[Unit]
+Description=ForgeZero exclusive guest CPU and memory boundary
+
+[Slice]
+AllowedCPUs=${cpus}
+${memoryDirective(nodes)}`;
+}
+function metalHousekeepingDropIn(profile, kind) {
+  validateMetalProfile(profile);
+  return `[${kind === "slice" ? "Slice" : "Scope"}]
+AllowedCPUs=${profile.housekeepingCpus}
+${memoryDirective(profile.housekeepingMemoryNodes)}`;
+}
+var defaultExec = async (argv) => {
+  const child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text()
+  ]);
+  return { exitCode, stdout, stderr };
+};
+var checked2 = async (exec, argv) => {
+  const result = await exec(argv);
+  if (result.exitCode !== 0)
+    throw new Error(`${argv[0]} failed: ${(result.stderr || result.stdout).trim()}`);
+  return result;
+};
+var requireGuestsInSlice = async (exec) => {
+  const active = await checked2(exec, [
+    "systemctl",
+    "list-units",
+    "--type=service",
+    "--state=running",
+    "--plain",
+    "--no-legend",
+    "forgezero-guest@*.service"
+  ]);
+  for (const line of active.stdout.split(`
+`)) {
+    const service = line.trim().split(/\s+/)[0];
+    if (!service)
+      continue;
+    const cgroup = await checked2(exec, ["systemctl", "show", "-p", "ControlGroup", "--value", service]);
+    if (!cgroup.stdout.trim().includes("/forgezero-guests.slice/")) {
+      throw new Error(`${service} must be drained and restarted into forgezero-guests.slice`);
+    }
+  }
+};
+async function applyMetalIsolation(profile, exec = defaultExec) {
+  validateMetalProfile(profile);
+  await requireGuestsInSlice(exec);
+  const unitDir = profile.unitDir;
+  mkdirSync5(unitDir, { recursive: true });
+  writeFileSync5(join3(unitDir, "forgezero-guests.slice"), metalGuestSliceUnit(profile), { mode: 420 });
+  for (const unit of ["system.slice", "user.slice"]) {
+    const directory = join3(unitDir, `${unit}.d`);
+    mkdirSync5(directory, { recursive: true });
+    writeFileSync5(join3(directory, "50-forgezero-housekeeping.conf"), metalHousekeepingDropIn(profile, "slice"), { mode: 420 });
+  }
+  const initDirectory = join3(unitDir, "init.scope.d");
+  mkdirSync5(initDirectory, { recursive: true });
+  writeFileSync5(join3(initDirectory, "50-forgezero-housekeeping.conf"), metalHousekeepingDropIn(profile, "scope"), { mode: 420 });
+  await checked2(exec, ["systemctl", "daemon-reload"]);
+  await requireGuestsInSlice(exec);
+  const properties = [`AllowedCPUs=${profile.housekeepingCpus}`];
+  if (profile.housekeepingMemoryNodes)
+    properties.push(`AllowedMemoryNodes=${profile.housekeepingMemoryNodes}`);
+  for (const unit of ["system.slice", "user.slice", "init.scope"]) {
+    await checked2(exec, ["systemctl", "set-property", "--runtime", unit, ...properties]);
+  }
+}
+
 // src/index.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.10";
 function loadOrCreateSeed(path) {
-  if (existsSync2(path)) {
-    const seed2 = new Uint8Array(Buffer.from(readFileSync(path, "utf8").trim(), "base64url"));
+  if (existsSync9(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;
   }
-  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync6(dirname5(path), { recursive: true });
   const seed = new Uint8Array(randomBytes(32));
-  writeFileSync(path, Buffer.from(seed).toString("base64url"), { mode: 384 });
-  chmodSync2(path, 384);
+  writeFileSync6(path, Buffer.from(seed).toString("base64url"), { mode: 384 });
+  chmodSync8(path, 384);
   return seed;
 }
 var DEFAULT_SOCKET_PATH = DEFAULT_SOCKET;
 var DEFAULT_SEED_PATH = "/var/lib/forgezero/node.seed";
+var DEFAULT_SEED_CREDENTIAL = "agent-seed";
+var DEFAULT_ENROLMENT_STATE_PATH = "/var/lib/forgezero/enrolment.json";
+function loadSeedCredential(name = DEFAULT_SEED_CREDENTIAL, directory = process.env.CREDENTIALS_DIRECTORY) {
+  if (!directory)
+    throw new Error("agent: CREDENTIALS_DIRECTORY is missing; systemd did not load the node identity.");
+  const path = `${directory}/${name}`;
+  if (!existsSync9(path))
+    throw new Error(`agent: the systemd credential ${name} is missing at ${path}.`);
+  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;
+}
+function loadTextCredential(name, directory = process.env.CREDENTIALS_DIRECTORY) {
+  if (!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 = readFileSync5(`${directory}/${name}`, "utf8").trim();
+  if (!value)
+    throw new Error(`agent: systemd credential ${name} is empty.`);
+  return value;
+}
+function createSystemdDeploymentSecrets(names, directory = process.env.CREDENTIALS_DIRECTORY) {
+  const allowed = new Set((names ?? "").split(",").map((name) => name.trim()).filter(Boolean));
+  if (allowed.size === 0)
+    return;
+  for (const name of allowed) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name))
+      throw new Error(`agent: invalid pipeline credential name ${name}.`);
+  }
+  return {
+    has: (name) => allowed.has(name),
+    async get(name) {
+      if (!allowed.has(name))
+        throw new Error(`agent: pipeline credential ${name} is not allowed.`);
+      return loadTextCredential(name, directory);
+    }
+  };
+}
 function runAgent(config = {}) {
-  const seedPath = config.seedPath ?? DEFAULT_SEED_PATH;
-  const keys = deriveKeysFromSeed(loadOrCreateSeed(seedPath));
+  const seed = config.seed ?? (config.seedCredential ? loadSeedCredential(config.seedCredential) : loadOrCreateSeed(config.seedPath ?? DEFAULT_SEED_PATH));
+  const keys = deriveKeysFromSeed(seed);
   const nodeKey = config.nodeKey ?? keys.ed25519.publicKey;
-  const server = startAgent({
+  const options = {
     socketPath: config.socketPath ?? DEFAULT_SOCKET_PATH,
     keys,
     nodeKey,
     attestation: config.attestation,
     cache: config.cache,
     record: config.record
-  });
-  return { server, keys, nodeKey };
+  };
+  const server = startAgent(options);
+  return { server, keys, nodeKey, setCache: (cache) => {
+    options.cache = cache;
+  } };
 }
 if (import.meta.main) {
   const args = process.argv.slice(2);
@@ -376,18 +2742,27 @@ if (import.meta.main) {
     console.log([
       `fz-agent ${VERSION}`,
       "",
-      "Runs on the metal and answers secret requests over a local socket.",
+      "Runs inside managed compute and answers secret requests over a local socket.",
       "It holds no configuration of its own \u2014 everything comes from the",
       "environment, so a systemd unit is the whole deployment.",
       "",
       "  FZ_SOCKET_PATH   where to listen        (default: " + DEFAULT_SOCKET_PATH + ")",
-      "  FZ_SEED_PATH     node identity seed     (default: " + DEFAULT_SEED_PATH + ")",
+      "  FZ_SEED_CREDENTIAL systemd credential   (production: agent-seed)",
+      "  FZ_SEED_PATH       legacy/dev seed file (default: " + DEFAULT_SEED_PATH + ")",
       "  FZ_NODE_KEY      override the node key  (default: derived from the seed)",
       "",
+      "  deploy [--revision=<full-sha>] [--coordinator]",
+      "  identity            print this sealed seed's public identity",
+      "  enrol               consume a systemd-loaded compute capability",
+      "  metal-helper --profile=/etc/forgezero/metal.json",
+      "  status | pause | resume",
+      "  pause-key|resume-key|stop-key|start-key --key=<key>",
+      "  cancel --id=<task-id>",
+      "",
       "  --help, -h       this text",
       "  --version, -v    print the version and exit",
       "",
-      "The seed is created on first run and never leaves the machine."
+      "Production reads the node seed from a private systemd credential."
     ].join(`
 `));
     process.exit(0);
@@ -396,22 +2771,399 @@ if (import.meta.main) {
     console.log(VERSION);
     process.exit(0);
   }
-  const { nodeKey } = runAgent({
+  const command = args.find((arg) => !arg.startsWith("-"));
+  if (command === "identity") {
+    const seed = process.env.FZ_SEED_CREDENTIAL ? loadSeedCredential(process.env.FZ_SEED_CREDENTIAL) : loadOrCreateSeed(process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH);
+    const keys2 = deriveKeysFromSeed(seed);
+    console.log(JSON.stringify({
+      nodeKey: keys2.ed25519.publicKey,
+      publicKeys: { ed25519: keys2.ed25519.publicKey, mlDsa: keys2.mlDsa.publicKey }
+    }, null, 2));
+    process.exit(0);
+  }
+  if (command === "enrol") {
+    if (!process.env.FZ_API)
+      throw new Error("agent enrolment requires FZ_API");
+    if (!process.env.FZ_ENROL_TOKEN_CREDENTIAL) {
+      throw new Error("agent enrolment requires a systemd enrolment credential");
+    }
+    const seed = process.env.FZ_SEED_CREDENTIAL ? loadSeedCredential(process.env.FZ_SEED_CREDENTIAL) : loadOrCreateSeed(process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH);
+    const keys2 = deriveKeysFromSeed(seed);
+    const nodeKey2 = process.env.FZ_NODE_KEY ?? keys2.ed25519.publicKey;
+    const binding2 = await enrolGuestIdentity({
+      apiUrl: process.env.FZ_API,
+      token: loadTextCredential(process.env.FZ_ENROL_TOKEN_CREDENTIAL),
+      statePath: process.env.FZ_ENROL_STATE_FILE ?? DEFAULT_ENROLMENT_STATE_PATH,
+      nodeKey: nodeKey2,
+      keys: keys2,
+      label: process.env.FZ_NODE_LABEL,
+      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);
+  }
+  if (command === "metal-helper") {
+    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(readFileSync5(profilePath, "utf8"));
+    const helper = startMetalHelper({
+      profile,
+      socketPath: process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET
+    });
+    console.log(`[metal-helper] listening on ${process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_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 === "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(readFileSync5(profilePath, "utf8"));
+    await applyMetalIsolation(profile);
+    console.log("[metal-isolation] host and guest cgroup boundaries active");
+    process.exit(0);
+  }
+  if (command === "deploy-runner") {
+    const root2 = args.find((arg) => arg.startsWith("--root="))?.slice("--root=".length);
+    const home = args.find((arg) => arg.startsWith("--home="))?.slice("--home=".length);
+    if (!root2 || !home)
+      throw new Error("deploy-runner requires --root=/absolute/path --home=/absolute/path");
+    const runner = startDeploymentRunner({
+      root: `${root2.replace(/\/$/, "")}/releases`,
+      home,
+      socketPath: process.env.FZ_DEPLOY_RUNNER_SOCKET ?? DEFAULT_DEPLOYMENT_RUNNER_SOCKET,
+      listenFd: Number(process.env.LISTEN_PID) === process.pid && Number(process.env.LISTEN_FDS) > 0 ? 3 : undefined
+    });
+    console.log(`[deploy-runner] listening on ${process.env.FZ_DEPLOY_RUNNER_SOCKET ?? DEFAULT_DEPLOYMENT_RUNNER_SOCKET}`);
+    let stopping = false;
+    const stop = async () => {
+      if (stopping)
+        return;
+      stopping = true;
+      await runner.stop();
+      process.exit(0);
+    };
+    process.on("SIGTERM", () => void stop());
+    process.on("SIGINT", () => void stop());
+    await new Promise(() => {});
+  }
+  if (process.env.FZ_AGENT_ROLE === "metal") {
+    if (!process.env.FZ_API)
+      throw new Error("metal agent requires FZ_API");
+    const seed = process.env.FZ_SEED_CREDENTIAL ? loadSeedCredential(process.env.FZ_SEED_CREDENTIAL) : loadOrCreateSeed(process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH);
+    const keys2 = deriveKeysFromSeed(seed);
+    const nodeKey2 = process.env.FZ_NODE_KEY ?? keys2.ed25519.publicKey;
+    const pull = startProvisioningPull({
+      apiUrl: process.env.FZ_API,
+      nodeKey: nodeKey2,
+      keys: keys2,
+      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)
+      }),
+      onEvent: (event, detail) => console.log(`[metal-agent] ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
+    });
+    console.log(`[metal-agent] signing as ${nodeKey2}; outbound provisioning enabled`);
+    let stopping = false;
+    const stop = async (signal) => {
+      if (stopping)
+        return;
+      stopping = true;
+      const deadline = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 120000));
+      const drained = await Promise.race([
+        pull.stop().then(() => true),
+        new Promise((resolve2) => setTimeout(() => resolve2(false), deadline))
+      ]);
+      console.log(`[metal-agent] ${signal}: ${drained ? "drained" : "deadline reached; claim left fenced for recovery"}`);
+      process.exit(drained ? 0 : 1);
+    };
+    process.on("SIGTERM", () => void stop("SIGTERM"));
+    process.on("SIGINT", () => void stop("SIGINT"));
+    await new Promise(() => {});
+  }
+  if (command && ["deploy", "status", "pause", "resume", "pause-key", "resume-key", "stop-key", "start-key", "cancel"].includes(command)) {
+    const revisionArg = args.find((arg) => arg.startsWith("--revision="));
+    const socketArg = args.find((arg) => arg.startsWith("--control-socket="));
+    const keyArg = args.find((arg) => arg.startsWith("--key="));
+    const idArg = args.find((arg) => arg.startsWith("--id="));
+    const socketPath = socketArg?.slice("--control-socket=".length) ?? process.env.FZ_CONTROL_SOCKET ?? DEFAULT_CONTROL_SOCKET;
+    const request = command === "deploy" ? {
+      op: "deploy",
+      request: {
+        revision: revisionArg?.slice("--revision=".length),
+        coordinator: args.includes("--coordinator")
+      }
+    } : command === "cancel" ? { op: "cancel", id: idArg?.slice("--id=".length) ?? "" } : ["pause-key", "resume-key", "stop-key", "start-key"].includes(command) ? {
+      op: command,
+      key: keyArg?.slice("--key=".length) ?? ""
+    } : { op: command };
+    try {
+      const response = await requestControl(request, socketPath);
+      console.log(JSON.stringify(response, null, 2));
+      process.exit(response.ok ? 0 : 1);
+    } catch (cause) {
+      console.error(`agent control failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+      process.exit(1);
+    }
+  }
+  const attestationSource = existsSync9("/dev/sev-guest") ? createSnpAttestationSource() : undefined;
+  const running = runAgent({
     socketPath: process.env.FZ_SOCKET_PATH ?? DEFAULT_SOCKET_PATH,
+    seedCredential: process.env.FZ_SEED_CREDENTIAL,
     seedPath: process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH,
     nodeKey: process.env.FZ_NODE_KEY,
+    attestation: attestationSource,
     record: (entry) => console.log(`[agent] ${entry.op} ${entry.outcome}${entry.detail ? ` ${entry.detail}` : ""}`)
   });
+  const { nodeKey, keys, server } = running;
   console.log(`[agent] ${VERSION} signing as ${nodeKey}`);
+  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));
+  if (!binding && (enrolmentCredentialAvailable || legacyEnrolmentFileAvailable) && process.env.FZ_API) {
+    binding = await enrolGuestIdentity({
+      apiUrl: process.env.FZ_API,
+      token: enrolmentCredential ? loadTextCredential(enrolmentCredential) : undefined,
+      tokenPath: enrolmentCredential ? undefined : process.env.FZ_ENROL_TOKEN_FILE,
+      statePath: enrolmentStatePath,
+      nodeKey,
+      keys,
+      label: process.env.FZ_NODE_LABEL,
+      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}`);
+  }
+  let nodeApiUrl = binding && process.env.FZ_API ? tenantNodeApiUrl(process.env.FZ_API, binding.tenantSlug) : process.env.FZ_API;
+  let secretCache;
+  let vaultSync;
+  if (binding && attestationSource && nodeApiUrl) {
+    const result = await attestNodeOnce({ apiUrl: nodeApiUrl, nodeKey, keys, source: attestationSource });
+    console.log(`[agent] initial SEV-SNP attestation verified ${result.measurement.slice(0, 16)}\u2026`);
+  }
+  if (binding && nodeApiUrl) {
+    secretCache = createNodeVaultCache({ apiUrl: nodeApiUrl, nodeKey, keys });
+    const loaded = await secretCache.load();
+    if (loaded.failed.length > 0) {
+      throw new Error(`agent: failed to load ${loaded.failed.length} assigned vault entries`);
+    }
+    running.setCache(secretCache);
+    vaultSync = startNodeVaultSync(secretCache, {
+      onEvent: (event, detail) => console.log(`[agent] vault ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
+    });
+    console.log(`[agent] in-memory vault loaded for ${binding.projectKey}/${binding.environmentKey}`);
+  }
+  const attestationLoop = attestationSource && nodeApiUrl ? startNodeAttestation({
+    apiUrl: nodeApiUrl,
+    nodeKey,
+    keys,
+    source: attestationSource,
+    immediate: !binding,
+    onEvent: (event, detail) => console.log(`[agent] attestation ${event}${detail ? ` ${detail instanceof Error ? detail.message : JSON.stringify(detail)}` : ""}`)
+  }) : undefined;
+  if (attestationLoop)
+    console.log("[agent] periodic SEV-SNP attestation enabled");
+  const systemdDeploymentSecrets = createSystemdDeploymentSecrets(process.env.FZ_DEPLOY_SYSTEMD_SECRETS);
+  const deploymentSecrets = secretCache ? {
+    async get(name) {
+      try {
+        return await secretCache.get(name);
+      } catch (cause) {
+        if (systemdDeploymentSecrets?.has(name))
+          return systemdDeploymentSecrets.get(name);
+        throw cause;
+      }
+    }
+  } : systemdDeploymentSecrets;
+  const repository = process.env.FZ_DEPLOY_REPO;
+  const branch = process.env.FZ_DEPLOY_BRANCH;
+  const role = process.env.FZ_DEPLOY_ROLE;
+  const root = process.env.FZ_DEPLOY_ROOT;
+  const pullEnabled = process.env.FZ_DEPLOY_PULL === "true" && Boolean(process.env.FZ_API);
+  if (pullEnabled && !binding) {
+    throw new Error("agent: outbound guest deployment requires a persisted tenant enrolment binding");
+  }
+  if (root && (repository && branch && role || pullEnabled)) {
+    const managers = new Map;
+    const managerOptions = (source, key) => ({
+      key,
+      repository: source.repository,
+      branch: source.branch,
+      role: source.role,
+      sourceAuth: source.auth,
+      root,
+      publicApiUrl: process.env.FZ_PUBLIC_API_URL,
+      environment: Object.fromEntries((process.env.FZ_DEPLOY_ENV_NAMES ?? "").split(",").filter(Boolean).map((name) => {
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || process.env[name] === undefined) {
+          throw new Error(`agent: invalid or absent deployment environment ${name}.`);
+        }
+        return [name, process.env[name]];
+      })),
+      gitCredentialPath: process.env.CREDENTIALS_DIRECTORY ? `${process.env.CREDENTIALS_DIRECTORY}/git-deploy-key` : undefined,
+      knownHostsPath: source.knownHosts ? join4(root, "cache", `known-hosts-${key}`) : undefined,
+      knownHostsContent: source.knownHosts,
+      cache: deploymentSecrets,
+      projectExec: process.env.FZ_DEPLOY_RUNNER_SOCKET ? (input) => requestDeploymentCommand(input, process.env.FZ_DEPLOY_RUNNER_SOCKET) : undefined
+    });
+    const staticManager = repository && branch && role ? createDeploymentManager(managerOptions({ repository, branch, role }, process.env.FZ_DEPLOY_KEY ?? `${repository}:${branch}:${role}`)) : undefined;
+    if (staticManager)
+      managers.set("__static__", staticManager);
+    const control = staticManager ? startControlServer(staticManager, process.env.FZ_CONTROL_SOCKET ?? DEFAULT_CONTROL_SOCKET) : undefined;
+    if (control)
+      console.log(`[agent] deployment control listening for ${repository}@${branch}`);
+    const staticWatch = staticManager && process.env.FZ_DEPLOY_WATCH === "true" ? startStaticDeploymentWatch({
+      manager: staticManager,
+      statePath: process.env.FZ_DEPLOY_STATE ?? join4(root, "cache", "static-deployment.json"),
+      coordinator: process.env.FZ_DEPLOY_COORDINATOR === "true",
+      currentRevision: () => {
+        try {
+          const slot = readFileSync5(join4(root, ".forge-slot"), "utf8").trim();
+          const revision = readFileSync5(join4(root, "slots", slot, ".git", "HEAD"), "utf8").trim();
+          return /^[a-f0-9]{40}$/i.test(revision) ? revision.toLowerCase() : undefined;
+        } catch {
+          return;
+        }
+      },
+      onEvent: (event, detail) => console.log(`[agent] static deployment ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
+    }) : undefined;
+    if (staticWatch)
+      console.log(`[agent] watching ${repository}@${branch} for exact revisions`);
+    const pull = pullEnabled ? startDeploymentPull({
+      apiUrl: nodeApiUrl,
+      nodeKey,
+      keys,
+      manager: staticManager,
+      managerFor: staticManager ? undefined : (claim) => {
+        const cacheKey = [
+          claim.pipelineKey,
+          claim.source.repository,
+          claim.source.branch,
+          claim.source.role,
+          JSON.stringify(claim.source.auth ?? null)
+        ].join("\x00");
+        const existing = managers.get(cacheKey);
+        if (existing)
+          return existing;
+        const manager = createDeploymentManager(managerOptions(claim.source, claim.pipelineKey));
+        managers.set(cacheKey, manager);
+        return manager;
+      },
+      onEvent: (event, detail) => console.log(`[agent] deployment ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
+    }) : undefined;
+    if (pull)
+      console.log(`[agent] outbound deployment claims enabled for ${process.env.FZ_API}`);
+    let stopping = false;
+    const shutdown = async (signal) => {
+      if (stopping)
+        return;
+      stopping = true;
+      console.log(`[agent] ${signal}: stopping deployment intake and draining`);
+      if (control)
+        await new Promise((resolve2) => control.close(() => resolve2()));
+      const deadlineMs = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 30000));
+      const deadline = Date.now() + deadlineMs;
+      const pullDrain = Promise.all([
+        pull?.stop() ?? Promise.resolve(),
+        staticWatch?.stop() ?? Promise.resolve()
+      ]);
+      const vaultDrain = vaultSync?.stop() ?? Promise.resolve();
+      const attestationDrain = attestationLoop?.stop() ?? Promise.resolve();
+      const pullWithinDeadline = pull || staticWatch ? Promise.race([
+        pullDrain.then(() => true),
+        new Promise((resolve2) => setTimeout(() => resolve2(false), deadlineMs))
+      ]) : Promise.resolve(true);
+      const pullDrained = await pullWithinDeadline;
+      await Promise.all([vaultDrain, attestationDrain]);
+      const managerReports = await Promise.all([...new Set(managers.values())].map((manager) => manager.stop(Math.max(1, deadline - Date.now()))));
+      await new Promise((resolve2) => server.close(() => resolve2()));
+      const timedOut = managerReports.some((report) => report.timedOut);
+      console.log(`[agent] drain ${JSON.stringify({ managers: managerReports, pullDrained })}`);
+      process.exit(timedOut || !pullDrained ? 1 : 0);
+    };
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+  } else {
+    console.log("[agent] signing/vault mode only; deployment root and pull are not configured");
+    if (vaultSync || attestationLoop) {
+      let stopping = false;
+      const stop = async () => {
+        if (stopping)
+          return;
+        stopping = true;
+        await Promise.all([
+          vaultSync?.stop() ?? Promise.resolve(),
+          attestationLoop?.stop() ?? Promise.resolve()
+        ]);
+        await new Promise((resolve2) => server.close(() => resolve2()));
+        process.exit(0);
+      };
+      process.on("SIGTERM", () => void stop());
+      process.on("SIGINT", () => void stop());
+    }
+  }
 }
 export {
+  writeStaticDeploymentState,
+  validateMetalProfile,
+  tenantNodeApiUrl,
+  startStaticDeploymentWatch,
+  startProvisioningPull,
+  startNodeVaultSync,
+  startNodeAttestation,
+  startMetalHelper,
+  startDeploymentRunner,
+  startDeploymentPull,
+  startControlServer,
   startAgent,
   runAgent,
+  requestMetalProvision,
+  requestDeploymentCommand,
+  requestControl,
+  removeMetalGuest,
+  readStaticDeploymentState,
+  pullProvisioningOnce,
+  pullDeploymentOnce,
+  provisionMetalGuest,
+  metalHousekeepingDropIn,
+  metalGuestSliceUnit,
+  loadTextCredential,
+  loadSeedCredential,
   loadOrCreateSeed,
+  loadGuestBinding,
   handleRequest,
+  guestNameFor,
+  enrolGuestIdentity,
+  createSystemdDeploymentSecrets,
+  createSnpAttestationSource,
   createSecretCache,
+  createNodeVaultCache,
+  createDeploymentManager,
+  cloudInit,
+  attestNodeOnce,
+  applyMetalIsolation,
+  allocateCpuPool,
+  allocateAddress,
   VERSION,
+  DeploymentError,
   DEFAULT_SOCKET_PATH,
   DEFAULT_SEED_PATH,
+  DEFAULT_SEED_CREDENTIAL,
+  DEFAULT_METAL_HELPER_SOCKET,
+  DEFAULT_ENROLMENT_STATE_PATH,
+  DEFAULT_DEPLOYMENT_RUNNER_SOCKET,
+  DEFAULT_CONTROL_SOCKET,
   CacheError
 };