@forgezero/agent 0.1.31 → 0.1.33

package/dist/provision.js

@@ -2,8 +2,11 @@
 import { createHash, timingSafeEqual, randomUUID } from "node:crypto";
 import {
   chmodSync,
+  closeSync,
   existsSync,
+  fsyncSync,
   mkdirSync,
+  openSync,
   readFileSync,
   readlinkSync,
   renameSync,
@@ -17,6 +20,25 @@ var DEFAULT_AGENT_UPDATE_SOCKET = "/run/forgezero-update/helper.sock";
 var MAX_AGENT_TARBALL_BYTES = 32 * 1024 * 1024;
 var VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 var REGISTRY = "registry.npmjs.org";
+var syncPath = (path) => {
+  const descriptor = openSync(path, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+};
+var syncReleaseDirectory = (directory) => {
+  for (const path of [
+    join(directory, "package.json"),
+    join(directory, "dist", "fz-agent.js"),
+    join(directory, "dist", "fz.js"),
+    join(directory, "dist"),
+    directory,
+    dirname(directory)
+  ])
+    syncPath(path);
+};
 function validateAgentRelease(release) {
   if (release?.package !== "@forgezero/agent")
     throw new Error("agent update package is fixed");
@@ -135,16 +157,24 @@ async function stageAgentRelease(releaseInput, options) {
       ]
     }, "agent update extraction");
     await validateReleaseDirectory(unpacked, release, run);
-    if (!existsSync(finalDirectory))
+    if (!existsSync(finalDirectory)) {
       renameSync(unpacked, finalDirectory);
-    else
+      syncReleaseDirectory(finalDirectory);
+    } else
       await validateReleaseDirectory(finalDirectory, release, run);
     if (!existsSync(currentLink)) {
       throw new Error("agent update requires an active immutable release to roll back to");
     }
     const previousTarget = readlinkSync(currentLink);
+    if (previousTarget !== join("versions", options.currentVersion)) {
+      throw new Error("agent update current release does not match the running version");
+    }
+    if (!existsSync(join(root, previousTarget))) {
+      throw new Error("agent update rollback release is missing");
+    }
     return {
       version: release.version,
+      fromVersion: options.currentVersion,
       directory: finalDirectory,
       previousTarget,
       nextTarget: join("versions", release.version),
@@ -159,6 +189,7 @@ function selectAgentRelease(staged) {
   try {
     symlinkSync(staged.nextTarget, next);
     renameSync(next, staged.currentLink);
+    syncPath(dirname(staged.currentLink));
   } finally {
     rmSync(next, { force: true });
   }
@@ -168,25 +199,189 @@ function restoreAgentRelease(staged) {
   try {
     symlinkSync(staged.previousTarget, next);
     renameSync(next, staged.currentLink);
+    syncPath(dirname(staged.currentLink));
   } finally {
     rmSync(next, { force: true });
   }
 }
 
 // src/agent-update-helper.ts
-import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, renameSync as renameSync2, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import {
+  chmodSync as chmodSync2,
+  closeSync as closeSync2,
+  existsSync as existsSync2,
+  fsyncSync as fsyncSync2,
+  mkdirSync as mkdirSync2,
+  openSync as openSync2,
+  readFileSync as readFileSync2,
+  renameSync as renameSync2,
+  rmSync as rmSync2,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
 import { connect, createServer } from "node:net";
-import { dirname as dirname2 } from "node:path";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
 import { DEFAULT_SOCKET } from "@forgezero/vault";
 var AGENT_UPDATE_GROUP = "forgezero-update";
 var AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-helper.service";
-var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update.json";
+var AGENT_UPDATE_JOURNAL = "/var/lib/forgezero/agent-update.json";
+var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update-receipt.json";
 var MAX_REQUEST_BYTES = 8 * 1024;
 var COMPUTE_HELPER_UNITS = [
+  "forgezero-agent-egress.service",
   "forgezero-deploy-runner.service",
   "forgezero-lifecycle-helper.service",
   "forgezero-software-helper.service"
 ];
+var VERSION2 = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+var ATTEMPT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+var REASON_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+var MAX_REASON_BYTES = 512;
+var UPDATE_RETRY_BASE_MS = 5 * 60000;
+var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
+var boundedMessage = (value) => {
+  let message = value.replace(/[\r\n]+/g, " ").trim();
+  while (Buffer.byteLength(message, "utf8") > MAX_REASON_BYTES)
+    message = message.slice(0, -1);
+  return message;
+};
+var reason = (code, message) => ({
+  code: REASON_CODE.test(code) ? code : "UPDATE_FAILED",
+  message: boundedMessage(message) || "Agent update failed"
+});
+var validTime = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+function validateReceipt(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("Agent update receipt is malformed");
+  const receipt = value;
+  if (!receipt.attemptId || !ATTEMPT_ID.test(receipt.attemptId))
+    throw new Error("Agent update attempt ID is invalid");
+  if (!receipt.fromVersion || !VERSION2.test(receipt.fromVersion))
+    throw new Error("Agent update source version is invalid");
+  if (!receipt.targetVersion || !VERSION2.test(receipt.targetVersion))
+    throw new Error("Agent update target version is invalid");
+  if (!["activating", "active", "rolled-back", "failed"].includes(receipt.outcome ?? "")) {
+    throw new Error("Agent update outcome is invalid");
+  }
+  if (!validTime(receipt.startedAtTs) || !validTime(receipt.updatedAtTs)) {
+    throw new Error("Agent update timestamps are invalid");
+  }
+  if (receipt.retryAfterTs !== undefined && !validTime(receipt.retryAfterTs)) {
+    throw new Error("Agent update retry timestamp is invalid");
+  }
+  if (receipt.rollbackHealthy !== undefined && typeof receipt.rollbackHealthy !== "boolean") {
+    throw new Error("Agent update rollback health is invalid");
+  }
+  if (receipt.reason && (!REASON_CODE.test(receipt.reason.code) || typeof receipt.reason.message !== "string" || Buffer.byteLength(receipt.reason.message, "utf8") > MAX_REASON_BYTES))
+    throw new Error("Agent update failure reason is invalid");
+  return {
+    attemptId: receipt.attemptId,
+    fromVersion: receipt.fromVersion,
+    targetVersion: receipt.targetVersion,
+    outcome: receipt.outcome,
+    startedAtTs: receipt.startedAtTs,
+    updatedAtTs: receipt.updatedAtTs,
+    ...receipt.retryAfterTs === undefined ? {} : { retryAfterTs: receipt.retryAfterTs },
+    ...receipt.rollbackHealthy === undefined ? {} : { rollbackHealthy: receipt.rollbackHealthy },
+    ...receipt.reason === undefined ? {} : { reason: receipt.reason }
+  };
+}
+function validateJournal(value, root) {
+  if (!value || typeof value !== "object")
+    throw new Error("Agent update journal is malformed");
+  const legacy = value;
+  if (legacy.schemaVersion === undefined) {
+    if (typeof legacy.version === "string" && VERSION2.test(legacy.version) && legacy.outcome === "active" && validTime(legacy.updatedAtTs) && Object.keys(value).every((key) => ["version", "outcome", "updatedAtTs"].includes(key)))
+      return;
+    throw new Error("Agent update legacy receipt is malformed");
+  }
+  const journal = value;
+  const receipt = validateReceipt(journal);
+  if (journal.schemaVersion !== 1)
+    throw new Error("Agent update journal schema is unsupported");
+  if (journal.target !== "compute" && journal.target !== "metal")
+    throw new Error("Agent update target is invalid");
+  if (!Number.isSafeInteger(journal.failureCount) || (journal.failureCount ?? -1) < 0) {
+    throw new Error("Agent update failure count is invalid");
+  }
+  const releaseRoot = resolve2(root);
+  if (journal.currentLink !== join2(releaseRoot, "current"))
+    throw new Error("Agent update current link is invalid");
+  if (journal.previousTarget !== join2("versions", receipt.fromVersion)) {
+    throw new Error("Agent update rollback target is invalid");
+  }
+  if (journal.nextTarget !== join2("versions", receipt.targetVersion)) {
+    throw new Error("Agent update next target is invalid");
+  }
+  return journal;
+}
+function readJournal(path, root) {
+  if (!existsSync2(path))
+    return;
+  return validateJournal(JSON.parse(readFileSync2(path, "utf8")), root);
+}
+function writeAtomic(path, value, mode) {
+  mkdirSync2(dirname2(path), { recursive: true, mode: 493 });
+  const next = `${path}.${randomUUID2()}.next`;
+  let file;
+  try {
+    file = openSync2(next, "wx", mode);
+    writeFileSync2(file, `${JSON.stringify(value)}
+`);
+    fsyncSync2(file);
+    closeSync2(file);
+    file = undefined;
+    renameSync2(next, path);
+    const directory = openSync2(dirname2(path), "r");
+    try {
+      fsyncSync2(directory);
+    } finally {
+      closeSync2(directory);
+    }
+  } finally {
+    if (file !== undefined)
+      closeSync2(file);
+    rmSync2(next, { force: true });
+  }
+}
+var publicReceipt = (journal) => {
+  const {
+    attemptId,
+    fromVersion,
+    targetVersion,
+    outcome,
+    startedAtTs,
+    updatedAtTs,
+    retryAfterTs,
+    rollbackHealthy,
+    reason: failureReason
+  } = journal;
+  return {
+    attemptId,
+    fromVersion,
+    targetVersion,
+    outcome,
+    startedAtTs,
+    updatedAtTs,
+    ...retryAfterTs === undefined ? {} : { retryAfterTs },
+    ...rollbackHealthy === undefined ? {} : { rollbackHealthy },
+    ...failureReason === undefined ? {} : { reason: failureReason }
+  };
+};
+function writeUpdateState(journalPath, receiptPath, journal) {
+  writeAtomic(journalPath, journal, 384);
+  writeAtomic(receiptPath, publicReceipt(journal), 416);
+}
+function readAgentUpdateReceipt(path = AGENT_UPDATE_RECEIPT) {
+  try {
+    if (!existsSync2(path))
+      return;
+    return validateReceipt(JSON.parse(readFileSync2(path, "utf8")));
+  } catch {
+    return;
+  }
+}
 var runCommand = async (input) => {
   const child = Bun.spawn([input.command, ...input.args], {
     cwd: input.cwd,
@@ -202,8 +397,27 @@ var runCommand = async (input) => {
   return { exitCode, output: `${stdout}${stderr}` };
 };
 var runOk = async (run, command2, args) => (await run({ command: command2, args })).exitCode === 0;
+var retryAfter = (now, failures) => now + Math.min(UPDATE_RETRY_MAX_MS, UPDATE_RETRY_BASE_MS * 2 ** Math.min(16, Math.max(0, failures - 1)));
+var stagedFromJournal = (journal, root) => ({
+  version: journal.targetVersion,
+  fromVersion: journal.fromVersion,
+  directory: join2(resolve2(root), journal.nextTarget),
+  previousTarget: journal.previousTarget,
+  nextTarget: journal.nextTarget,
+  currentLink: journal.currentLink
+});
+var restartAgent = async (target, run) => {
+  const helpers = target === "compute" ? COMPUTE_HELPER_UNITS : ["forgezero-metal-helper.service"];
+  for (const unit of helpers)
+    await run({ command: "/usr/bin/systemctl", args: ["try-restart", unit] });
+  const service = target === "compute" ? "forgezero-agent.service" : "forgezero-metal-agent.service";
+  if (!await runOk(run, "/usr/bin/systemctl", ["restart", service])) {
+    throw new Error(`systemd could not restart ${service}`);
+  }
+};
+var targetProbe = (target, run) => target === "compute" ? () => probeAgentSocket() : async () => await runOk(run, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-agent.service"]) && await runOk(run, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-helper.service"]);
 function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const socket = connect(socketPath);
     let settled = false;
     let buffer = "";
@@ -213,7 +427,7 @@ function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
       settled = true;
       clearTimeout(timer);
       socket.destroy();
-      resolve2(value);
+      resolve3(value);
     };
     const timer = setTimeout(() => finish(false), timeoutMs);
     socket.on("connect", () => socket.write(`{"op":"identity"}
@@ -237,55 +451,136 @@ function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
 async function activateAgentRelease(staged, options = {}) {
   const run = options.run ?? runCommand;
   const target = options.target ?? "compute";
-  const probe = options.probe ?? (target === "compute" ? () => probeAgentSocket() : async () => await runOk(run, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-agent.service"]) && await runOk(run, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-helper.service"]));
-  const restart = async () => {
-    const helpers = target === "compute" ? COMPUTE_HELPER_UNITS : ["forgezero-metal-helper.service"];
-    for (const unit of helpers) {
-      await run({ command: "/usr/bin/systemctl", args: ["try-restart", unit] });
-    }
-    const service = target === "compute" ? "forgezero-agent.service" : "forgezero-metal-agent.service";
-    const restarted = await runOk(run, "/usr/bin/systemctl", ["restart", service]);
-    if (!restarted)
-      throw new Error(`systemd could not restart ${service}`);
+  const probe = options.probe ?? targetProbe(target, run);
+  const now = options.now ?? Date.now;
+  const journalPath = options.journalPath ?? AGENT_UPDATE_JOURNAL;
+  const receiptPath = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
+  const previous = readJournal(journalPath, dirname2(staged.currentLink));
+  const attemptId = options.attemptId ?? randomUUID2();
+  if (!ATTEMPT_ID.test(attemptId))
+    throw new Error("Agent update attempt ID is invalid");
+  const startedAtTs = now();
+  const failureCount = previous?.targetVersion === staged.version ? previous.failureCount : 0;
+  let journal = {
+    schemaVersion: 1,
+    attemptId,
+    target,
+    fromVersion: staged.fromVersion,
+    targetVersion: staged.version,
+    outcome: "activating",
+    startedAtTs,
+    updatedAtTs: startedAtTs,
+    currentLink: staged.currentLink,
+    previousTarget: staged.previousTarget,
+    nextTarget: staged.nextTarget,
+    failureCount
   };
-  let selected = false;
+  writeUpdateState(journalPath, receiptPath, journal);
+  let selectionAttempted = false;
   try {
+    selectionAttempted = true;
     selectAgentRelease(staged);
-    selected = true;
-    await restart();
+    await restartAgent(target, run);
     if (!await probe())
       throw new Error("the replacement Agent did not answer its retained Vault socket");
-    const receipt = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
-    mkdirSync2(dirname2(receipt), { recursive: true, mode: 493 });
-    const next = `${receipt}.next`;
-    writeFileSync2(next, JSON.stringify({
-      version: staged.version,
-      outcome: "active",
-      updatedAtTs: (options.now ?? Date.now)()
-    }) + `
-`, { mode: 420 });
-    renameSync2(next, receipt);
+    journal = { ...journal, outcome: "active", updatedAtTs: now(), rollbackHealthy: undefined };
+    writeUpdateState(journalPath, receiptPath, journal);
     run({
       command: "/usr/bin/systemctl",
       args: ["try-restart", "--no-block", "forgezero-agent-update-helper.service"]
     });
     return { ok: true, version: staged.version };
   } catch (cause) {
-    const reason = cause instanceof Error ? cause.message : String(cause);
-    if (selected) {
-      restoreAgentRelease(staged);
-      await restart();
+    const message = cause instanceof Error ? cause.message : String(cause);
+    let rollbackHealthy = false;
+    let restored = false;
+    if (selectionAttempted) {
+      try {
+        restoreAgentRelease(staged);
+        restored = true;
+        await restartAgent(target, run);
+        rollbackHealthy = await probe();
+      } catch {
+        rollbackHealthy = false;
+      }
     }
-    return { ok: false, rolledBack: selected, reason };
+    const failures = failureCount + 1;
+    const updatedAtTs = now();
+    journal = {
+      ...journal,
+      outcome: rollbackHealthy ? "rolled-back" : "failed",
+      updatedAtTs,
+      retryAfterTs: retryAfter(updatedAtTs, failures),
+      rollbackHealthy,
+      reason: reason(rollbackHealthy ? "REPLACEMENT_UNHEALTHY" : "ROLLBACK_UNHEALTHY", rollbackHealthy ? message : `${message}; the restored Agent did not pass its health probe`),
+      failureCount: failures
+    };
+    writeUpdateState(journalPath, receiptPath, journal);
+    return { ok: false, rolledBack: restored, rollbackHealthy, reason: message };
   }
 }
+async function recoverInterruptedAgentUpdate(options = {}) {
+  const root = resolve2(options.root ?? DEFAULT_AGENT_RELEASE_ROOT);
+  const journalPath = options.journalPath ?? AGENT_UPDATE_JOURNAL;
+  const receiptPath = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
+  const journal = readJournal(journalPath, root);
+  if (!journal)
+    return;
+  if (journal.outcome !== "activating") {
+    writeAtomic(receiptPath, publicReceipt(journal), 416);
+    return publicReceipt(journal);
+  }
+  const staged = stagedFromJournal(journal, root);
+  if (!existsSync2(join2(root, journal.previousTarget))) {
+    throw new Error("Agent update rollback release is missing");
+  }
+  const run = options.run ?? runCommand;
+  const probe = options.probe ?? targetProbe(journal.target, run);
+  restoreAgentRelease(staged);
+  let rollbackHealthy = false;
+  let failureMessage = "activation was interrupted before its health verdict became durable";
+  try {
+    await restartAgent(journal.target, run);
+    rollbackHealthy = await probe();
+  } catch (cause) {
+    failureMessage = `${failureMessage}; ${cause instanceof Error ? cause.message : String(cause)}`;
+  }
+  const failures = journal.failureCount + 1;
+  const updatedAtTs = (options.now ?? Date.now)();
+  const recovered = {
+    ...journal,
+    outcome: rollbackHealthy ? "rolled-back" : "failed",
+    updatedAtTs,
+    retryAfterTs: retryAfter(updatedAtTs, failures),
+    rollbackHealthy,
+    reason: reason(rollbackHealthy ? "ACTIVATION_INTERRUPTED" : "ROLLBACK_UNHEALTHY", failureMessage),
+    failureCount: failures
+  };
+  writeUpdateState(journalPath, receiptPath, recovered);
+  return readAgentUpdateReceipt(receiptPath);
+}
 function startAgentUpdateHelper(options = {}) {
   const socketPath = options.socketPath ?? DEFAULT_AGENT_UPDATE_SOCKET;
   if (existsSync2(socketPath))
     unlinkSync(socketPath);
   mkdirSync2(dirname2(socketPath), { recursive: true, mode: 488 });
   const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
-  const activate = options.activate ?? ((staged, target) => activateAgentRelease(staged, { target }));
+  const receiptPath = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
+  const journalPath = options.journalPath ?? AGENT_UPDATE_JOURNAL;
+  const releaseRoot = options.root ?? DEFAULT_AGENT_RELEASE_ROOT;
+  const activate = options.activate ?? ((staged, target, attemptId) => activateAgentRelease(staged, { target, attemptId, journalPath, receiptPath, now: options.now }));
+  let busy = true;
+  let blocked;
+  (options.recover ?? (() => recoverInterruptedAgentUpdate({
+    root: releaseRoot,
+    journalPath,
+    receiptPath,
+    now: options.now
+  })))().catch((cause) => {
+    blocked = cause instanceof Error ? cause.message : String(cause);
+  }).finally(() => {
+    busy = false;
+  });
   const server = createServer((socket) => {
     let buffer = "";
     socket.on("data", (chunk) => {
@@ -301,22 +596,42 @@ function startAgentUpdateHelper(options = {}) {
         return;
       const line = buffer.slice(0, newline);
       buffer = "";
+      let ownsBusy = false;
       Promise.resolve().then(() => JSON.parse(line)).then(async (request) => {
+        if (blocked)
+          throw new Error(`update journal needs operator recovery: ${blocked}`);
+        if (busy)
+          throw new Error("another Agent update or recovery is already active");
         if (request.op !== "apply")
           throw new Error("unknown update operation");
         if (request.target !== "compute" && request.target !== "metal") {
           throw new Error("agent update target is invalid");
         }
+        const attemptId = request.attemptId ?? randomUUID2();
+        if (!ATTEMPT_ID.test(attemptId))
+          throw new Error("Agent update attempt ID is invalid");
+        const prior = readJournal(journalPath, releaseRoot);
+        const now = (options.now ?? Date.now)();
+        if (prior?.targetVersion === request.release.version && (prior.outcome === "rolled-back" || prior.outcome === "failed") && (prior.retryAfterTs ?? 0) > now)
+          throw new Error(`Agent update ${request.release.version} is quarantined until ${prior.retryAfterTs}`);
+        busy = true;
+        ownsBusy = true;
         const staged = await stageAgentRelease(request.release, {
           currentVersion: request.currentVersion,
-          root: options.root ?? DEFAULT_AGENT_RELEASE_ROOT
+          root: releaseRoot
         });
-        const response = { ok: true, status: "staged", version: staged.version };
+        const response = { ok: true, status: "staged", version: staged.version, attemptId };
         socket.end(`${JSON.stringify(response)}
-`, () => {
-          setTimer(() => void activate(staged, request.target), 100);
-        });
+`);
+        setTimer(() => void activate(staged, request.target, attemptId).catch((cause) => {
+          blocked = cause instanceof Error ? cause.message : String(cause);
+        }).finally(() => {
+          busy = false;
+        }), 100);
+        ownsBusy = false;
       }).catch((cause) => {
+        if (ownsBusy)
+          busy = false;
         const response = {
           ok: false,
           error: { code: "UPDATE_REFUSED", message: cause instanceof Error ? cause.message : String(cause) }
@@ -331,7 +646,7 @@ function startAgentUpdateHelper(options = {}) {
   return server;
 }
 function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, timeoutMs = 90000) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const socket = connect(socketPath, () => socket.write(`${JSON.stringify(request)}
 `));
     let buffer = "";
@@ -347,7 +662,7 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
         return;
       socket.end();
       try {
-        resolve2(JSON.parse(buffer.slice(0, newline)));
+        resolve3(JSON.parse(buffer.slice(0, newline)));
       } catch (cause) {
         reject(cause);
       }
@@ -357,7 +672,7 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 }
 
 // src/software.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync3 } from "node:fs";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
@@ -398,7 +713,7 @@ var UBUNTU_2604_X64 = [
     install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
   }
 ];
-function observeSoftwareHost(osRelease = readFileSync2("/etc/os-release", "utf8"), architecture = process.arch) {
+function observeSoftwareHost(osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
     const separator = line.indexOf("=");
@@ -540,7 +855,7 @@ function startSoftwareHelper(options = {}) {
 }
 function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
   validateSoftwareRequirements(requirements);
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const socket = connect2(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
 `));
     let buffer = "";
@@ -559,7 +874,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
         const response = JSON.parse(buffer.slice(0, newline));
         if (!response.ok || !response.results)
           throw new Error(response.error?.message ?? "software helper refused the request");
-        resolve2(response.results);
+        resolve3(response.results);
       } catch (cause) {
         reject(cause);
       }
@@ -569,9 +884,71 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION2 = "0.1.31";
+var VERSION3 = "0.1.33";
+
+// src/egress-policy.ts
+import { realpathSync } from "node:fs";
+var AGENT_EGRESS_TABLE = "forgezero_agent_egress";
+var SYSTEMD_RESOLVED_ADDRESS = "127.0.0.53";
+var BLOCKED_IPV4 = [
+  "0.0.0.0/8",
+  "10.0.0.0/8",
+  "100.64.0.0/10",
+  "127.0.0.0/8",
+  "168.63.129.16/32",
+  "169.254.0.0/16",
+  "172.16.0.0/12",
+  "192.0.0.0/24",
+  "192.0.2.0/24",
+  "192.88.99.0/24",
+  "192.168.0.0/16",
+  "198.18.0.0/15",
+  "198.51.100.0/24",
+  "203.0.113.0/24",
+  "224.0.0.0/4",
+  "240.0.0.0/4"
+];
+var BLOCKED_IPV6 = [
+  "::/128",
+  "::1/128",
+  "::ffff:0:0/96",
+  "64:ff9b::/96",
+  "64:ff9b:1::/48",
+  "100::/64",
+  "fc00::/7",
+  "fec0::/10",
+  "fe80::/10",
+  "ff00::/8",
+  "2001::/32",
+  "2001:2::/48",
+  "2001:10::/28",
+  "2001:20::/28",
+  "2001:db8::/32",
+  "2002::/16",
+  "3fff::/20"
+];
+var normalizeEgressTcpPorts = (ports) => {
+  for (const port of ports) {
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+      throw new Error("Agent egress policy refuses an invalid loopback TCP port.");
+    }
+  }
+  return [...new Set(ports)].sort((left, right) => left - right);
+};
+function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
+  const ports = normalizeEgressTcpPorts(loopbackTcpPorts);
+  return [
+    "RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6",
+    `IPAddressAllow=${SYSTEMD_RESOLVED_ADDRESS}/32`,
+    ...ports.length > 0 ? ["IPAddressAllow=127.0.0.1/32", "IPAddressAllow=::1/128"] : [],
+    ...BLOCKED_IPV4.map((network) => `IPAddressDeny=${network}`),
+    ...BLOCKED_IPV6.map((network) => `IPAddressDeny=${network}`)
+  ].join(`
+`);
+}
 
 // src/provision.ts
+import { isIP } from "node:net";
 function atLeast(version, floor) {
   const parse = (value) => (value.trim().replace(/^v/, "").match(/\d+/g) ?? []).slice(0, 3).map(Number);
   const got = parse(version);
@@ -625,6 +1002,63 @@ var LIFECYCLE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-lifecycle-helper
 var LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
 var WARP_CONFIG_UNIT_PATH = "/etc/systemd/system/forgezero-warp-config.service";
 var WARP_SERVICE_DROP_IN_PATH = "/etc/systemd/system/warp-svc.service.d/forgezero.conf";
+var AGENT_EGRESS_UNIT_PATH = "/etc/systemd/system/forgezero-agent-egress.service";
+var DEFAULT_RUNNER_PUBLIC_TCP_PORTS = [443];
+function agentEgressUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  const user = options.user ?? "forgezero";
+  if (!/^[a-z_][a-z0-9_-]{0,30}$/.test(user))
+    throw new Error("invalid Agent service user");
+  const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const runnerLoopbackPorts = normalizeEgressTcpPorts(options.runnerLoopbackPorts ?? []);
+  const runnerPublicTcpPorts = normalizeEgressTcpPorts(options.runnerPublicTcpPorts ?? DEFAULT_RUNNER_PUBLIC_TCP_PORTS);
+  if (deploymentEnabled && runnerPublicTcpPorts.length < 1) {
+    throw new Error("deployed project runner needs at least one vetted public TCP port");
+  }
+  if (deploymentEnabled)
+    systemdAgentEgressDirectives(runnerLoopbackPorts);
+  const users = [user, ...deploymentEnabled ? [DEPLOYMENT_RUNNER_USER] : []];
+  const runnerGrant = deploymentEnabled ? ` --loopback-user=${DEPLOYMENT_RUNNER_USER}` + runnerLoopbackPorts.map((port) => ` --loopback-tcp-port=${port}`).join("") + runnerPublicTcpPorts.map((port) => ` --public-tcp-port=${port}`).join("") : "";
+  const policyProofs = deploymentEnabled ? [
+    ...runnerLoopbackPorts.length > 0 ? [`loopback=.*:${runnerLoopbackPorts.join(",")}`] : [],
+    `public-tcp=${runnerPublicTcpPorts.join(",")}`
+  ].map((pattern) => `ExecStartPost=/bin/sh -c '/usr/sbin/nft --numeric list table inet ${AGENT_EGRESS_TABLE} | /usr/bin/grep -q "${pattern}"'`).join(`
+`) : "";
+  return `[Unit]
+Description=ForgeZero Agent host egress policy
+Documentation=https://www.forgezero.net/docs/agent
+After=systemd-resolved.service nftables.service
+Requires=systemd-resolved.service
+Before=forgezero-agent-enrol.service forgezero-agent.service
+
+[Service]
+Type=notify
+NotifyAccess=all
+User=root
+Group=root
+ExecStart=${bin} egress-policy ${users.map((name) => `--user=${name}`).join(" ")}${runnerGrant}
+${policyProofs}
+Restart=on-failure
+RestartSec=2
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+CapabilityBoundingSet=CAP_NET_ADMIN
+RestrictAddressFamilies=AF_UNIX AF_NETLINK
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
 function softwareHelperUnit(options) {
   const bin = options.binPath ?? "fz-agent";
   return `[Unit]
@@ -869,11 +1303,16 @@ function agentEnrolmentUnit(options) {
 ` : ""
   ].join("");
   const stateDir = options.enrolStatePath.replace(/\/[^/]+$/, "");
+  const egressDependency = options.enforceEgress ? `After=forgezero-agent-egress.service
+Requires=forgezero-agent-egress.service
+BindsTo=forgezero-agent-egress.service
+` : "";
+  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives() : "";
   return `[Unit]
 Description=Bind this machine to its ForgeZero compute
 After=network-online.target
 Wants=network-online.target
-Before=forgezero-agent.service
+${egressDependency}Before=forgezero-agent.service
 ConditionPathExists=!${options.enrolStatePath}
 
 [Service]
@@ -896,6 +1335,7 @@ ProtectSystem=strict
 ProtectHome=true
 ReadWritePaths=${stateDir}
 LimitCORE=0
+${egressDirectives}
 
 [Install]
 WantedBy=multi-user.target
@@ -905,9 +1345,15 @@ function deploymentRunnerUnit(options) {
   const bin = options.binPath ?? "fz-agent";
   const root = options.deployRoot ?? "/opt/forgezero";
   const agentUser = options.user ?? "forgezero-agent";
+  const egressDependency = options.enforceEgress ? `After=forgezero-agent-egress.service
+Requires=forgezero-agent-egress.service
+BindsTo=forgezero-agent-egress.service
+` : "";
+  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives(options.runnerLoopbackPorts ?? []) : "";
   return `[Unit]
 Description=ForgeZero credential-free project command runner
 Documentation=https://www.forgezero.net/docs/agent
+${egressDependency}
 
 [Service]
 Type=notify
@@ -938,6 +1384,7 @@ ProtectControlGroups=true
 RestrictRealtime=true
 MemoryDenyWriteExecute=true
 LockPersonality=true
+${egressDirectives}
 ReadWritePaths=${root}/releases ${root}/runner-home
 
 [Install]
@@ -947,6 +1394,21 @@ WantedBy=multi-user.target
 function agentUnit(options) {
   if (!validNodeHostname(options.nodeHostname))
     throw new Error("node hostname is invalid");
+  if (!options.telemetryEndpoint) {
+    throw new Error("compute Agent provisioning requires OTEL_EXPORTER_OTLP_ENDPOINT as an explicit public HTTPS collector coordinate");
+  }
+  let telemetryEndpoint;
+  {
+    let endpoint;
+    try {
+      endpoint = new URL(options.telemetryEndpoint);
+    } catch {
+      throw new Error("compute telemetry endpoint must be an absolute public HTTPS URL");
+    }
+    if (endpoint.protocol !== "https:" || endpoint.username || endpoint.password || endpoint.search || endpoint.hash || isIP(endpoint.hostname) !== 0 || !endpoint.hostname.includes(".") || endpoint.hostname === "localhost" || endpoint.hostname.endsWith(".local"))
+      throw new Error("compute telemetry endpoint must be an absolute public HTTPS URL without credentials, query or fragment");
+    telemetryEndpoint = endpoint.toString().replace(/\/$/, "");
+  }
   const bin = options.binPath ?? "fz-agent";
   const user = options.user ?? "forgezero";
   const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
@@ -995,6 +1457,7 @@ function agentUnit(options) {
     }
   }
   const environment = [
+    "NODE_ENV=production",
     `FZ_SOCKET_PATH=${agentBackendSocketPath(options.socketPath)}`,
     `FZ_CONTROL_SOCKET=${controlSocketPath}`,
     `FZ_SEED_CREDENTIAL=agent-seed`,
@@ -1005,6 +1468,8 @@ function agentUnit(options) {
     options.enrolStatePath ? `FZ_ENROL_STATE_FILE=${options.enrolStatePath}` : null,
     options.nodeLabel ? `FZ_NODE_LABEL=${options.nodeLabel}` : null,
     options.nodeHostname ? `FZ_NODE_HOSTNAME=${options.nodeHostname}` : null,
+    `OTEL_EXPORTER_OTLP_ENDPOINT=${telemetryEndpoint}`,
+    "OTEL_SERVICE_NAME=forgezero-agent",
     options.gitPublicKeyPath ? `FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}` : null,
     options.repository ? `FZ_DEPLOY_REPO=${options.repository}` : null,
     options.branch ? `FZ_DEPLOY_BRANCH=${options.branch}` : null,
@@ -1040,6 +1505,7 @@ function agentUnit(options) {
   const after = [
     "network-online.target",
     "forgezero-agent-update-helper.service",
+    options.enforceEgress ? "forgezero-agent-egress.service" : null,
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
     deploymentEnabled ? "forgezero-software-helper.service" : null,
     lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
@@ -1048,6 +1514,7 @@ function agentUnit(options) {
   ].filter((value) => value !== null);
   const requires = [
     "forgezero-agent-update-helper.service",
+    options.enforceEgress ? "forgezero-agent-egress.service" : null,
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
     deploymentEnabled ? "forgezero-software-helper.service" : null,
     lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
@@ -1057,7 +1524,8 @@ function agentUnit(options) {
   const deploymentDependency = [
     `After=${after.join(" ")}`,
     "Wants=network-online.target",
-    requires.length > 0 ? `Requires=${requires.join(" ")}` : null
+    requires.length > 0 ? `Requires=${requires.join(" ")}` : null,
+    options.enforceEgress ? "BindsTo=forgezero-agent-egress.service" : null
   ].filter((value) => value !== null).join(`
 `);
   const snpDevice = options.mode === "attested" ? `DevicePolicy=closed
@@ -1065,6 +1533,7 @@ DeviceAllow=/dev/sev-guest rw` : "";
   const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${VAULT_GROUP} /dev/sev-guest
 ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
 ` : "";
+  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives() : "";
   return `[Unit]
 Description=ForgeZero node agent (${options.mode})
 Documentation=https://www.forgezero.net/docs/agent
@@ -1109,6 +1578,7 @@ RestrictSUIDSGID=true
 RestrictRealtime=true
 MemoryDenyWriteExecute=true
 LockPersonality=true
+${egressDirectives}
 ${snpDevice}
 ${deploymentWrites}
 
@@ -1124,6 +1594,8 @@ function planProvision(options) {
   const credentialDir = seedCredentialPath.replace(/\/[^/]+$/, "");
   const deployRoot = options.deployRoot ?? "/opt/forgezero";
   const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const runnerLoopbackPorts = normalizeEgressTcpPorts(options.runnerLoopbackPorts ?? []);
+  const runnerPublicTcpPorts = normalizeEgressTcpPorts(options.runnerPublicTcpPorts ?? DEFAULT_RUNNER_PUBLIC_TCP_PORTS);
   const lifecycleEnabled = Boolean(options.pullMigrations && options.lifecycleProfilePath);
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
@@ -1164,6 +1636,9 @@ function planProvision(options) {
       { path: AGENT_SOCKET_UNIT_PATH, unit: agentSocketUnit(options) },
       { path: AGENT_SOCKET_PROXY_UNIT_PATH, unit: agentSocketProxyUnit(options) },
       { path: AGENT_UPDATE_HELPER_UNIT_PATH, unit: agentUpdateHelperUnit(options) },
+      ...options.enforceEgress ? [
+        { path: AGENT_EGRESS_UNIT_PATH, unit: agentEgressUnit(options) }
+      ] : [],
       ...deploymentEnabled ? [
         { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) },
         { path: SOFTWARE_HELPER_UNIT_PATH, unit: softwareHelperUnit(options) }
@@ -1190,6 +1665,10 @@ function planProvision(options) {
     socketPath: options.socketPath,
     user,
     steps: [
+      ...options.enforceEgress ? [{
+        label: "Ubuntu Agent egress prerequisites",
+        command: `. /etc/os-release; test "$ID" = ubuntu; ` + `DEBIAN_FRONTEND=noninteractive apt-get update -qq; ` + `DEBIAN_FRONTEND=noninteractive apt-get install -y nftables; ` + `systemctl enable --now systemd-resolved.service; ` + `test "$(readlink -f /etc/resolv.conf)" = /run/systemd/resolve/stub-resolv.conf; ` + `test -s /run/systemd/resolve/stub-resolv.conf`
+      }] : [],
       {
         label: "vault socket access group",
         command: `groupadd --system ${VAULT_GROUP} || true`
@@ -1200,7 +1679,7 @@ function planProvision(options) {
       },
       ...sourceBinPath && binPath ? [{
         label: "root-owned agent runtime",
-        command: `install -d -o root -g root -m 0755 ${binPath.replace(/\/[^/]+$/, "")} ` + `${DEFAULT_AGENT_RELEASE_ROOT}/versions/${VERSION2}/dist; ` + `install -o root -g root -m 0755 ${sourceBinPath} ` + `${DEFAULT_AGENT_RELEASE_ROOT}/versions/${VERSION2}/dist/fz-agent.js; ` + `ln -sfn versions/${VERSION2} ${DEFAULT_AGENT_RELEASE_ROOT}/current.next; ` + `mv -Tf ${DEFAULT_AGENT_RELEASE_ROOT}/current.next ${DEFAULT_AGENT_RELEASE_ROOT}/current; ` + `rm -f ${binPath}; ln -s ${DEFAULT_AGENT_RELEASE_ROOT}/current/dist/fz-agent.js ${binPath}`
+        command: `install -d -o root -g root -m 0755 ${binPath.replace(/\/[^/]+$/, "")} ` + `${DEFAULT_AGENT_RELEASE_ROOT}/versions/${VERSION3}/dist; ` + `install -o root -g root -m 0755 ${sourceBinPath} ` + `${DEFAULT_AGENT_RELEASE_ROOT}/versions/${VERSION3}/dist/fz-agent.js; ` + `ln -sfn versions/${VERSION3} ${DEFAULT_AGENT_RELEASE_ROOT}/current.next; ` + `mv -Tf ${DEFAULT_AGENT_RELEASE_ROOT}/current.next ${DEFAULT_AGENT_RELEASE_ROOT}/current; ` + `rm -f ${binPath}; ln -s ${DEFAULT_AGENT_RELEASE_ROOT}/current/dist/fz-agent.js ${binPath}`
       }] : [],
       ...warpEnabled ? [{
         label: "Cloudflare One client for Ubuntu 26.04",
@@ -1280,6 +1759,7 @@ function planProvision(options) {
         command: `systemctl enable ${[
           "forgezero-agent.socket",
           "forgezero-agent-update-helper.service",
+          ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
           ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
           ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
           ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
@@ -1287,6 +1767,7 @@ function planProvision(options) {
           "forgezero-agent.service"
         ].join(" ")}; systemctl reset-failed forgezero-agent.service || true; systemctl restart ${[
           "forgezero-agent-update-helper.service",
+          ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
           ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
           ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
           ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
@@ -1297,6 +1778,10 @@ function planProvision(options) {
         label: "prove the compute binding is durable",
         command: `test -s ${enrolStatePath}`
       }] : [],
+      ...options.enforceEgress ? [{
+        label: "prove the Agent egress policy is active",
+        command: "systemctl is-active forgezero-agent-egress.service && " + "nft --numeric list table inet forgezero_agent_egress | grep -q forgezero-agent-egress-v1" + (deploymentEnabled ? ` && nft --numeric list table inet forgezero_agent_egress | grep -q 'public-tcp=${runnerPublicTcpPorts.join(",")}'` + (runnerLoopbackPorts.length > 0 ? ` && nft --numeric list table inet forgezero_agent_egress | grep -Eq 'loopback=[0-9]+:${runnerLoopbackPorts.join(",")}( |")'` : "") : "")
+      }] : [],
       { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
       { label: "prove the public Vault socket exists", command: awaitSocketCommand(options.socketPath) },
       { label: "prove the Agent Vault backend exists", command: awaitSocketCommand(agentBackendSocketPath(options.socketPath)) },
@@ -1338,6 +1823,7 @@ export {
   agentSocketUnit,
   agentSocketProxyUnit,
   agentEnrolmentUnit,
+  agentEgressUnit,
   agentBackendSocketPath,
   WARP_SERVICE_DROP_IN_PATH,
   WARP_CONFIG_UNIT_PATH,
@@ -1351,7 +1837,9 @@ export {
   DEPLOYMENT_RUNNER_UNIT_PATH,
   DEPLOYMENT_RUNNER_SOCKET,
   DEPLOYMENT_GROUP,
+  DEFAULT_RUNNER_PUBLIC_TCP_PORTS,
   CAPABILITY_CHECKS,
   AGENT_SOCKET_UNIT_PATH,
-  AGENT_SOCKET_PROXY_UNIT_PATH
+  AGENT_SOCKET_PROXY_UNIT_PATH,
+  AGENT_EGRESS_UNIT_PATH
 };