@forgezero/agent 0.1.32 → 0.1.34

package/dist/fz-agent.js

@@ -4393,7 +4393,8 @@ function startNodeVaultSync(cache, options = {}) {
   const tick = () => {
     if (stopped || active)
       return;
-    active = cache.sync().then((result) => options.onEvent?.("synced", result)).catch((cause) => options.onEvent?.("sync-failed", cause)).finally(() => {
+    const sync = () => cache.sync();
+    active = (options.telemetry ? options.telemetry.observe("vault.sync", sync) : sync()).then((result) => options.onEvent?.("synced", result)).catch((cause) => options.onEvent?.("sync-failed", cause)).finally(() => {
       active = null;
       schedule();
     });
@@ -4575,9 +4576,9 @@ function safeOp(line) {
 }
 
 // src/deployment.ts
-import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "fs";
-import { randomUUID } from "crypto";
-import { dirname, join } from "path";
+import { chmodSync as chmodSync2, existsSync as existsSync2, lstatSync, mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "fs";
+import { createHash as createHash2, randomUUID } from "crypto";
+import { dirname, isAbsolute as isAbsolute2, join } from "path";
 
 // ../runtime/dist/queue.js
 class QueueStoppedError extends Error {
@@ -4987,6 +4988,121 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
   return results;
 }
 
+// src/capacity-calibration.ts
+var percentile95 = (values) => {
+  if (values.length === 0)
+    return Number.POSITIVE_INFINITY;
+  const sorted = values.toSorted((left, right) => left - right);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)];
+};
+function localCalibrationEndpoint(value) {
+  const endpoint = new URL(value);
+  if (endpoint.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname) || !endpoint.port || endpoint.username || endpoint.password || endpoint.hash) {
+    throw new Error("Capacity calibration requires an explicit loopback HTTP endpoint and port.");
+  }
+  return endpoint;
+}
+function validateCapacityCalibrationOptions(options) {
+  const endpoint = localCalibrationEndpoint(options.endpoint);
+  const maxConcurrency = options.maxConcurrency ?? 256;
+  const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maxP95Ms = options.maxP95Ms ?? 250;
+  const maxErrorRate = options.maxErrorRate ?? 0.01;
+  const headroomRatio = options.headroomRatio ?? 0.8;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(headroomRatio) || headroomRatio < 0.25 || headroomRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000) {
+    throw new Error("Capacity calibration bounds are invalid.");
+  }
+  return {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    headroomRatio,
+    requestTimeoutMs
+  };
+}
+async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher) {
+  const latencies = [];
+  let succeeded = 0;
+  let failed = 0;
+  let overloaded = 0;
+  const started = performance.now();
+  await Promise.all(Array.from({ length: concurrency }, async () => {
+    for (let request = 0;request < requestsPerWorker; request += 1) {
+      const requestStarted = performance.now();
+      try {
+        const response = await fetcher(endpoint, {
+          method: "GET",
+          headers: { accept: "application/json", "user-agent": "forgezero-capacity-calibration/1" },
+          signal: AbortSignal.timeout(timeoutMs),
+          redirect: "error"
+        });
+        await response.body?.cancel();
+        if (response.ok)
+          succeeded += 1;
+        else {
+          failed += 1;
+          if (response.status === 503)
+            overloaded += 1;
+        }
+      } catch {
+        failed += 1;
+      } finally {
+        latencies.push(performance.now() - requestStarted);
+      }
+    }
+  }));
+  const elapsedSeconds = Math.max((performance.now() - started) / 1000, 0.001);
+  return {
+    concurrency,
+    requests: concurrency * requestsPerWorker,
+    succeeded,
+    failed,
+    overloaded,
+    throughputPerSecond: Number(((succeeded + failed) / elapsedSeconds).toFixed(2)),
+    p95Ms: Number(percentile95(latencies).toFixed(2))
+  };
+}
+async function calibrateHttpConcurrency(options, fetcher = fetch) {
+  const {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    headroomRatio,
+    requestTimeoutMs: timeoutMs
+  } = validateCapacityCalibrationOptions(options);
+  const stages = [];
+  let lastSafe = 1;
+  let stopReason = "maximum-tested";
+  for (let concurrency = 1;; concurrency = Math.min(maxConcurrency, concurrency * 2)) {
+    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher);
+    stages.push(measured);
+    const errorRate = measured.failed / measured.requests;
+    const previous = stages.at(-2);
+    const throughputRegressed = Boolean(previous && concurrency > 1 && measured.throughputPerSecond < previous.throughputPerSecond * 0.9);
+    if (measured.overloaded > 0 || errorRate > maxErrorRate)
+      stopReason = "errors";
+    else if (measured.p95Ms > maxP95Ms)
+      stopReason = "latency";
+    else if (throughputRegressed)
+      stopReason = "throughput-regression";
+    else
+      lastSafe = concurrency;
+    if (stopReason !== "maximum-tested" || concurrency === maxConcurrency)
+      break;
+  }
+  return {
+    endpoint: endpoint.toString(),
+    recommendedConcurrency: Math.max(1, Math.floor(lastSafe * headroomRatio)),
+    stopReason,
+    stages
+  };
+}
+
 // src/definition.ts
 var PIPELINE_VERSION = 2;
 var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
@@ -5027,6 +5143,53 @@ var RESERVED_STEP_ENV = new Set([
   "GIT_SSH",
   "GIT_SSH_COMMAND"
 ]);
+function capacityCalibration(value, where) {
+  const calibration = record(value, where);
+  exactKeys(calibration, [
+    "endpoint",
+    "maxConcurrency",
+    "requestsPerWorker",
+    "maxP95Ms",
+    "maxErrorRate",
+    "headroomRatio",
+    "requestTimeoutMs"
+  ], where);
+  const endpoint = text(calibration.endpoint, `${where}.endpoint`);
+  try {
+    localCalibrationEndpoint(endpoint);
+  } catch (cause) {
+    throw new DefinitionError(cause instanceof Error ? cause.message : `${where}.endpoint is invalid.`);
+  }
+  const optionalNumber = (name) => {
+    const raw = calibration[name];
+    if (raw === undefined)
+      return;
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      throw new DefinitionError(`${where}.${name} must be a finite number.`);
+    }
+    return raw;
+  };
+  const parsed = {
+    endpoint,
+    ...Object.fromEntries([
+      "maxConcurrency",
+      "requestsPerWorker",
+      "maxP95Ms",
+      "maxErrorRate",
+      "headroomRatio",
+      "requestTimeoutMs"
+    ].flatMap((name) => {
+      const found = optionalNumber(name);
+      return found === undefined ? [] : [[name, found]];
+    }))
+  };
+  try {
+    validateCapacityCalibrationOptions(parsed);
+  } catch (cause) {
+    throw new DefinitionError(cause instanceof Error ? cause.message : `${where} bounds are invalid.`);
+  }
+  return parsed;
+}
 function parseDeployDefinition(value, options = {}) {
   const root = record(value, "pipeline");
   exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
@@ -5052,11 +5215,16 @@ function parseDeployDefinition(value, options = {}) {
     if (!NAME.test(name2))
       throw new DefinitionError(`pipeline profile name is invalid: ${name2}.`);
     const profile = record(raw, `profiles.${name2}`);
-    exactKeys(profile, ["software"], `profiles.${name2}`);
+    exactKeys(profile, ["software", "capacityCalibration"], `profiles.${name2}`);
     if (!Array.isArray(profile.software)) {
       throw new DefinitionError(`profiles.${name2}.software must be an array.`);
     }
-    profiles[name2] = { software: validateSoftwareRequirements(profile.software, options) };
+    profiles[name2] = {
+      software: validateSoftwareRequirements(profile.software, options),
+      ...profile.capacityCalibration === undefined ? {} : {
+        capacityCalibration: capacityCalibration(profile.capacityCalibration, `profiles.${name2}.capacityCalibration`)
+      }
+    };
   }
   const phases = new Set(["build", "release", "migrate", "health"]);
   const steps = root.steps.map((raw, index) => {
@@ -5122,6 +5290,11 @@ function parseDeployDefinition(value, options = {}) {
   if (new Set(steps.map((step) => step.name)).size !== steps.length) {
     throw new DefinitionError("pipeline.steps must have unique names.");
   }
+  for (const [profile, selected] of Object.entries(profiles)) {
+    if (selected.capacityCalibration && !steps.some((step) => step.phase === "health" && step.scope === "target" && (!step.profiles || step.profiles.includes(profile)))) {
+      throw new DefinitionError(`profiles.${profile}.capacityCalibration requires a target-scoped health step.`);
+    }
+  }
   const name = text(root.name, "pipeline.name");
   if (name.length > 120)
     throw new DefinitionError("pipeline.name must be at most 120 characters.");
@@ -5148,6 +5321,188 @@ function deployDefinitionDigest(definition) {
   return `sha256:${createHash("sha256").update(stable(definition)).digest("hex")}`;
 }
 
+// src/git-egress.ts
+import { lookup } from "dns/promises";
+import { isAbsolute } from "path";
+import { isIP } from "net";
+
+class GitEgressError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GitEgressError";
+  }
+}
+var normalizeHostname = (value) => value.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+function ipv4Number(address) {
+  if (isIP(address) !== 4)
+    return null;
+  const octets = address.split(".").map(Number);
+  return ((octets[0] * 256 + octets[1]) * 256 + octets[2]) * 256 + octets[3] >>> 0;
+}
+var ipv4Cidr = (address, base, prefix) => {
+  const start = ipv4Number(base);
+  const shift = 32 - prefix;
+  return shift === 32 ? true : address >>> shift === start >>> shift;
+};
+function ipv6Number(address) {
+  if (isIP(address) !== 6)
+    return null;
+  let source = address.toLowerCase().split("%", 1)[0];
+  const dotted = source.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    const ipv4 = ipv4Number(dotted[2]);
+    if (ipv4 === null)
+      return null;
+    source = `${dotted[1]}${(ipv4 >>> 16).toString(16)}:${(ipv4 & 65535).toString(16)}`;
+  }
+  const halves = source.split("::");
+  if (halves.length > 2)
+    return null;
+  const left = halves[0] ? halves[0].split(":") : [];
+  const right = halves[1] ? halves[1].split(":") : [];
+  if (halves.length === 1 && left.length !== 8)
+    return null;
+  const omitted = halves.length === 2 ? 8 - left.length - right.length : 0;
+  if (omitted < 1 && halves.length === 2)
+    return null;
+  const words = [...left, ...Array.from({ length: omitted }, () => "0"), ...right];
+  if (words.length !== 8 || words.some((word) => !/^[a-f0-9]{1,4}$/.test(word)))
+    return null;
+  return words.reduce((value, word) => value << 16n | BigInt(`0x${word}`), 0n);
+}
+var ipv6Cidr = (address, base, prefix) => address >> BigInt(128 - prefix) === base >> BigInt(128 - prefix);
+function isPublicGitAddress(value) {
+  const address = normalizeHostname(value);
+  const ipv4 = ipv4Number(address);
+  if (ipv4 !== null) {
+    return ![
+      ["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]
+    ].some(([base, prefix]) => ipv4Cidr(ipv4, base, prefix));
+  }
+  const ipv6 = ipv6Number(address);
+  if (ipv6 === null)
+    return false;
+  const globalUnicast = ipv6Cidr(ipv6, 0x20000000000000000000000000000000n, 3);
+  if (!globalUnicast)
+    return false;
+  return ![
+    [0x20010000000000000000000000000000n, 32],
+    [0x20010002000000000000000000000000n, 48],
+    [0x20010010000000000000000000000000n, 28],
+    [0x20010020000000000000000000000000n, 28],
+    [0x20010db8000000000000000000000000n, 32],
+    [0x20020000000000000000000000000000n, 16],
+    [0x3fff0000000000000000000000000000n, 20]
+  ].some(([base, prefix]) => ipv6Cidr(ipv6, base, prefix));
+}
+function gitNetworkTarget(repository) {
+  if (!repository || /[\r\n\0]/.test(repository)) {
+    throw new GitEgressError("The Git source is malformed.");
+  }
+  if (/^(?:https|ssh):\/\//i.test(repository)) {
+    let url;
+    try {
+      url = new URL(repository);
+    } catch {
+      throw new GitEgressError("The Git source URL is malformed.");
+    }
+    if (!url.hostname || url.password || url.search || url.hash) {
+      throw new GitEgressError("Git source URLs cannot contain a password, query, or fragment.");
+    }
+    if (url.protocol === "https:" && url.username) {
+      throw new GitEgressError("HTTPS Git credentials must not appear in the source URL.");
+    }
+    const hostname = normalizeHostname(url.hostname);
+    if (!hostname)
+      throw new GitEgressError("The Git source host is malformed.");
+    const protocol = url.protocol === "https:" ? "https" : "ssh";
+    const port = url.port ? Number(url.port) : protocol === "https" ? 443 : 22;
+    const hostKeyAlias = protocol === "ssh" ? url.port ? `[${hostname}]:${port}` : hostname : undefined;
+    assertPublicHostname(hostname);
+    return { protocol, hostname, port, hostKeyAlias };
+  }
+  const scp = repository.match(/^[^@\s:]+@([^:\s]+):(.+)$/);
+  if (scp) {
+    const hostname = normalizeHostname(scp[1]);
+    assertPublicHostname(hostname);
+    return { protocol: "ssh", hostname, port: 22, hostKeyAlias: hostname };
+  }
+  if (repository.includes("://") || /^[^@\s]+@/.test(repository)) {
+    throw new GitEgressError("Remote Git sources must use HTTPS or SSH.");
+  }
+  if (!isAbsolute(repository)) {
+    throw new GitEgressError("A local Git source must use an absolute path.");
+  }
+  return null;
+}
+function assertPublicHostname(hostname) {
+  const host = normalizeHostname(hostname);
+  if (!host || host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) {
+    throw new GitEgressError("Git source hosts must not target a private network.");
+  }
+  if (isIP(host) && !isPublicGitAddress(host)) {
+    throw new GitEgressError("Git source hosts must not target a private network.");
+  }
+  if (!isIP(host) && (host.length > 253 || !host.split(".").every((label) => label.length > 0 && label.length <= 63 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)))) {
+    throw new GitEgressError("The Git source host is malformed.");
+  }
+}
+var resolveSystemGitHost = async (hostname) => {
+  let timer;
+  try {
+    return await Promise.race([
+      lookup(hostname, { all: true, verbatim: true }).then((rows) => rows.map(({ address }) => address)),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("DNS lookup timed out.")), 5000);
+        timer.unref?.();
+      })
+    ]);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+  }
+};
+async function resolvePinnedGitTarget(repository, resolveHost = resolveSystemGitHost) {
+  const target = gitNetworkTarget(repository);
+  if (!target)
+    return null;
+  assertPublicHostname(target.hostname);
+  let addresses;
+  if (isIP(target.hostname)) {
+    addresses = [target.hostname];
+  } else {
+    try {
+      addresses = await resolveHost(target.hostname);
+    } catch {
+      throw new GitEgressError(`The Git source host ${target.hostname} could not be resolved.`);
+    }
+  }
+  const unique = [...new Set(addresses.map(normalizeHostname))];
+  if (unique.length === 0 || unique.length > 16 || unique.some((address) => !isPublicGitAddress(address))) {
+    throw new GitEgressError(`The Git source host ${target.hostname} did not resolve exclusively to public addresses.`);
+  }
+  return { ...target, addresses: unique };
+}
+var curlResolveValue = (target) => {
+  const addresses = target.addresses.map((address) => isIP(address) === 6 ? `[${address}]` : address);
+  return `${target.hostname}:${target.port}:${addresses.join(",")}`;
+};
+
 // src/pipeline.ts
 class PipelineError extends Error {
   code;
@@ -5267,7 +5622,49 @@ var shell = async (input) => {
   return { exitCode, output: `${stdout}${stderr}` };
 };
 var quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+function persistCapacityCalibration(args) {
+  if (!isAbsolute2(args.directory)) {
+    throw new DeploymentError("PIPELINE_FAILED", "capacity evidence directory must be an absolute Agent-owned path");
+  }
+  if (!existsSync2(args.directory)) {
+    const parent = lstatSync(dirname(args.directory));
+    if (!parent.isDirectory() || parent.isSymbolicLink()) {
+      throw new DeploymentError("PIPELINE_FAILED", "capacity evidence parent must be a real Agent-owned directory");
+    }
+    mkdirSync(args.directory, { mode: 448 });
+  }
+  const stats = lstatSync(args.directory);
+  if (!stats.isDirectory() || stats.isSymbolicLink()) {
+    throw new DeploymentError("PIPELINE_FAILED", "capacity evidence directory must be a real Agent-owned directory");
+  }
+  const identity = createHash2("sha256").update(`${args.deploymentKey}\x00${args.profile}\x00${args.revision}`).digest("hex").slice(0, 24);
+  const path = join(args.directory, `${identity}-${args.measuredAtTs}-${randomUUID().slice(0, 8)}.json`);
+  const next = `${path}.next`;
+  const recommendedCoordinate = {
+    FZ_CONCURRENCY_LIMIT: String(args.calibration.recommendedConcurrency)
+  };
+  writeFileSync(next, `${JSON.stringify({
+    format: 1,
+    kind: "forgezero-node-capacity-calibration",
+    deploymentKey: args.deploymentKey,
+    revision: args.revision,
+    definitionDigest: args.definitionDigest,
+    profile: args.profile,
+    measuredAtTs: args.measuredAtTs,
+    recommendedCoordinate,
+    calibration: args.calibration
+  }, null, 2)}
+`, { mode: 384, flag: "wx" });
+  chmodSync2(next, 384);
+  renameSync(next, path);
+  return path;
+}
 function createDeploymentManager(options) {
+  try {
+    gitNetworkTarget(options.repository);
+  } catch (cause) {
+    throw new DeploymentError("SOURCE_FAILED", cause instanceof GitEgressError ? cause.message : "The Git source is malformed.");
+  }
   const queue = createQueue({ width: options.width ?? 4 });
   const activeRevisions = new Map;
   const exec = options.exec ?? shell;
@@ -5293,13 +5690,61 @@ function createDeploymentManager(options) {
     renameSync(next, knownHostsPath);
     chmodSync2(knownHostsPath, 384);
   };
+  const gitBaseEnvironment = () => ({
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_SYSTEM: "/dev/null",
+    GIT_CONFIG_GLOBAL: "/dev/null",
+    GIT_CONFIG_PARAMETERS: "",
+    GIT_SSH_VARIANT: "ssh",
+    SSH_AUTH_SOCK: "",
+    HTTP_PROXY: "",
+    HTTPS_PROXY: "",
+    ALL_PROXY: "",
+    http_proxy: "",
+    https_proxy: "",
+    all_proxy: ""
+  });
+  const withGitConfig = (environment, entries) => ({
+    ...environment,
+    GIT_CONFIG_COUNT: String(entries.length),
+    ...Object.fromEntries(entries.flatMap(([key, value], index) => [
+      [`GIT_CONFIG_KEY_${index}`, key],
+      [`GIT_CONFIG_VALUE_${index}`, value]
+    ]))
+  });
+  let httpsGitVersion;
+  const requirePinnedHttpsGit = () => {
+    httpsGitVersion ??= (async () => {
+      const result = await exec({ command: "git version" });
+      const match = result.exitCode === 0 ? result.output.match(/\bgit version (\d+)\.(\d+)(?:\.(\d+))?\b/i) : null;
+      if (!match || Number(match[1]) < 2 || Number(match[1]) === 2 && Number(match[2]) < 37) {
+        throw new DeploymentError("SOURCE_FAILED", "HTTPS Git sources require Git 2.37 or newer for destination pinning.");
+      }
+    })();
+    return httpsGitVersion;
+  };
   const gitEnvironment = async () => {
-    const https = /^https:\/\//i.test(options.repository);
+    let target;
+    try {
+      target = await resolvePinnedGitTarget(options.repository, options.resolveGitHost);
+    } catch (cause) {
+      throw new DeploymentError("SOURCE_FAILED", cause instanceof GitEgressError ? cause.message : "The Git source destination could not be verified.");
+    }
+    if (!target)
+      return gitBaseEnvironment();
+    const https = target?.protocol === "https";
+    if (https)
+      await requirePinnedHttpsGit();
     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" };
+      return withGitConfig(gitBaseEnvironment(), [
+        ["http.followRedirects", "false"],
+        ["http.proxy", ""],
+        ["http.curloptResolve", curlResolveValue(target)]
+      ]);
     }
     if (auth.kind === "vault-token") {
       if (!https)
@@ -5319,20 +5764,23 @@ function createDeploymentManager(options) {
         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")}`
-      };
+      return withGitConfig(gitBaseEnvironment(), [
+        [`http.${origin}/.extraHeader`, `Authorization: Basic ${Buffer.from(`${username}:${token}`).toString("base64")}`],
+        ["http.followRedirects", "false"],
+        ["http.proxy", ""],
+        ["http.curloptResolve", curlResolveValue(target)]
+      ]);
     }
     if (!gitCredentialPath) {
       throw new DeploymentError("SOURCE_FAILED", "No Git deploy-key credential was loaded for the agent.");
     }
     persistKnownHosts();
+    if (!target || target.protocol !== "ssh") {
+      throw new DeploymentError("SOURCE_FAILED", "A Git deploy key requires an SSH network source.");
+    }
     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)}`
+      ...gitBaseEnvironment(),
+      GIT_SSH_COMMAND: `ssh -F /dev/null -i ${quote(gitCredentialPath)} -o IdentitiesOnly=yes -o BatchMode=yes ` + `-o ConnectTimeout=15 -o StrictHostKeyChecking=yes -o UserKnownHostsFile=${quote(knownHostsPath)} ` + `-o Hostname=${quote(target.addresses[0])} -o HostKeyAlias=${quote(target.hostKeyAlias)} ` + `-o CanonicalizeHostname=no -o ProxyCommand=none -o ProxyJump=none ` + `-o PermitLocalCommand=no -o ClearAllForwardings=yes`
     };
   };
   const checked = async (input, code) => {
@@ -5434,6 +5882,30 @@ function createDeploymentManager(options) {
         throw new DeploymentError("PIPELINE_FAILED", `${pipeline.name} failed at ${failedStep?.name ?? "unknown step"}` + (detail ? `: ${detail}` : ` (exit ${failedStep?.exitCode ?? "unknown"}).`));
       }
     }
+    let capacity;
+    if (selectedProfile.capacityCalibration) {
+      if (!options.capacityEvidenceDirectory) {
+        throw new DeploymentError("PIPELINE_FAILED", "capacity calibration was requested but the Agent has no evidence directory");
+      }
+      const calibration = await (options.calibrateCapacity ?? calibrateHttpConcurrency)(selectedProfile.capacityCalibration);
+      const measuredAtTs = now();
+      const evidencePath = persistCapacityCalibration({
+        directory: options.capacityEvidenceDirectory,
+        deploymentKey: options.key,
+        revision: head,
+        definitionDigest,
+        profile: options.profile,
+        measuredAtTs,
+        calibration
+      });
+      capacity = {
+        ...calibration,
+        evidencePath,
+        recommendedCoordinate: {
+          FZ_CONCURRENCY_LIMIT: String(calibration.recommendedConcurrency)
+        }
+      };
+    }
     return {
       key: options.key,
       repository: options.repository,
@@ -5444,7 +5916,8 @@ function createDeploymentManager(options) {
       profile: options.profile,
       release,
       ok: true,
-      phases
+      phases,
+      ...capacity ? { capacity } : {}
     };
   };
   return {
@@ -5598,6 +6071,8 @@ function requestControl(request, socketPath = DEFAULT_CONTROL_SOCKET) {
 }
 
 // src/deployment-pull.ts
+var remoteOutcome = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : "retryable";
+
 class DeploymentClaimLostError extends Error {
   constructor(message) {
     super(message);
@@ -5628,10 +6103,11 @@ async function deployClaim(options, claim) {
       if (stopped || renewal)
         return;
       let retryDelay;
-      renewal = postSigned(options, "renew", {
+      const renew = () => postSigned(options, "renew", {
         runKey: claim.runKey,
         claimToken: claim.claimToken
-      }).then((response) => {
+      });
+      renewal = (options.telemetry ? options.telemetry.observe("deployment.renew", renew, () => "success", remoteOutcome) : renew()).then((response) => {
         expires = response.claimExpiresAtTs;
         options.onEvent?.("lease-renewed", { runKey: claim.runKey, claimExpiresAtTs: expires });
       }).catch((cause) => {
@@ -5652,7 +6128,8 @@ async function deployClaim(options, claim) {
   schedule();
   let result;
   try {
-    result = await manager.deploy({ revision: claim.revision, releaseExecutor: claim.releaseExecutor }).result;
+    const run = () => manager.deploy({ revision: claim.revision, releaseExecutor: claim.releaseExecutor }).result;
+    result = options.telemetry ? await options.telemetry.observe("deployment.run", run) : await run();
   } finally {
     stopped = true;
     clearTimer(timer);
@@ -5681,7 +6158,8 @@ async function completeSigned(options, body) {
   throw last;
 }
 async function pullDeploymentOnce(options) {
-  const claimed = await postSigned(options, "claim", {});
+  const claimWork = () => postSigned(options, "claim", {});
+  const claimed = options.telemetry ? await options.telemetry.observe("deployment.claim", claimWork, (value) => value.claim ? "success" : "idle", remoteOutcome) : await claimWork();
   if (!claimed.claim)
     return { status: "idle" };
   const claim = claimed.claim;
@@ -5692,15 +6170,19 @@ async function pullDeploymentOnce(options) {
     if (cause instanceof DeploymentClaimLostError)
       throw cause;
     const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
-    await completeSigned(options, {
+    const acknowledge2 = () => completeSigned(options, {
       runKey: claim.runKey,
       claimToken: claim.claimToken,
       ok: false,
       detail: reason
     });
+    if (options.telemetry) {
+      await options.telemetry.observe("deployment.complete", acknowledge2, () => "success", remoteOutcome);
+    } else
+      await acknowledge2();
     return { status: "failed", claim, reason };
   }
-  await completeSigned(options, {
+  const acknowledge = () => completeSigned(options, {
     runKey: claim.runKey,
     claimToken: claim.claimToken,
     ok: true,
@@ -5710,6 +6192,10 @@ async function pullDeploymentOnce(options) {
     definitionVersion: result.definitionVersion,
     profile: result.profile
   });
+  if (options.telemetry) {
+    await options.telemetry.observe("deployment.complete", acknowledge, () => "success", remoteOutcome);
+  } else
+    await acknowledge();
   return { status: "deployed", claim, result };
 }
 function startDeploymentPull(options) {
@@ -5854,6 +6340,7 @@ async function enrolGuestIdentity(options) {
 // src/provisioning-pull.ts
 class ProvisionClaimLostError extends Error {
 }
+var remoteOutcome2 = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : "retryable";
 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));
@@ -5872,10 +6359,11 @@ async function runClaim(options, claim) {
       if (stopped || renewal)
         return;
       let retry;
-      renewal = post(options, "renew", {
+      const renew = () => post(options, "renew", {
         computeKey: claim.computeKey,
         claimToken: claim.claimToken
-      }).then((response) => {
+      });
+      renewal = (options.telemetry ? options.telemetry.observe("provisioning.renew", renew, () => "success", remoteOutcome2) : renew()).then((response) => {
         expires = response.claimExpiresAtTs;
         options.onEvent?.("lease-renewed", { computeKey: claim.computeKey, claimExpiresAtTs: expires });
       }).catch((cause) => {
@@ -5896,7 +6384,8 @@ async function runClaim(options, claim) {
   schedule();
   let result;
   try {
-    result = await options.run(claim);
+    const run = () => options.run(claim);
+    result = options.telemetry ? await options.telemetry.observe("provisioning.apply", run) : await run();
   } finally {
     stopped = true;
     clearTimer(timer);
@@ -5927,7 +6416,8 @@ async function complete(options, body) {
 async function pullProvisioningOnce(options) {
   if (options.metalPreflight) {
     const report = options.metalPreflight();
-    const accepted = await postSignedNode(options, "v1/metal/preflight", report);
+    const preflight = () => postSignedNode(options, "v1/metal/preflight", report);
+    const accepted = options.telemetry ? await options.telemetry.observe("provisioning.preflight", preflight, (value) => value.ready ? "success" : "refused", remoteOutcome2) : await preflight();
     if (options.metalHostname && accepted.hostname !== options.metalHostname) {
       throw new Error(`metal agent: configured inventory hostname ${options.metalHostname} is bound as ${accepted.hostname}; refusing work.`);
     }
@@ -5940,7 +6430,8 @@ async function pullProvisioningOnce(options) {
     if (!accepted.ready)
       return { status: "idle" };
   }
-  const response = await post(options, "claim", {});
+  const claimWork = () => post(options, "claim", {});
+  const response = options.telemetry ? await options.telemetry.observe("provisioning.claim", claimWork, (value) => value.claim ? "success" : "idle", remoteOutcome2) : await claimWork();
   if (!response.claim)
     return { status: "idle" };
   const claim = response.claim;
@@ -5951,20 +6442,28 @@ async function pullProvisioningOnce(options) {
     if (cause instanceof ProvisionClaimLostError)
       throw cause;
     const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
-    await complete(options, {
+    const acknowledge2 = () => complete(options, {
       computeKey: claim.computeKey,
       claimToken: claim.claimToken,
       ok: false,
       detail: reason
     });
+    if (options.telemetry) {
+      await options.telemetry.observe("provisioning.complete", acknowledge2, () => "success", remoteOutcome2);
+    } else
+      await acknowledge2();
     return { status: "failed", claim, reason };
   }
-  await complete(options, {
+  const acknowledge = () => complete(options, {
     computeKey: claim.computeKey,
     claimToken: claim.claimToken,
     ok: true,
     ...result.guestAddress ? { guestAddress: result.guestAddress } : {}
   });
+  if (options.telemetry) {
+    await options.telemetry.observe("provisioning.complete", acknowledge, () => "success", remoteOutcome2);
+  } else
+    await acknowledge();
   return { status: claim.action === "delete" ? "terminated" : "running", claim, result };
 }
 function startProvisioningPull(options) {
@@ -6003,6 +6502,7 @@ class MigrationClaimLostError extends Error {
     this.name = "MigrationClaimLostError";
   }
 }
+var remoteOutcome3 = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : "retryable";
 var post2 = (options, operation, body) => postSignedNode(options, `v1/node/migrations/${operation}`, body);
 async function complete2(options, body) {
   const attempts = Math.max(1, Math.min(options.completionAttempts ?? 5, 10));
@@ -6023,7 +6523,8 @@ async function complete2(options, body) {
   throw last;
 }
 async function pullMigrationOnce(options) {
-  const response = await post2(options, "claim", {});
+  const claimWork = () => post2(options, "claim", {});
+  const response = options.telemetry ? await options.telemetry.observe("migration.claim", claimWork, (value) => value.claim ? "success" : "idle", remoteOutcome3) : await claimWork();
   if (!response.claim)
     return { status: "idle" };
   const claim = response.claim;
@@ -6043,10 +6544,11 @@ async function pullMigrationOnce(options) {
       if (stopped || renewal)
         return;
       let retry;
-      renewal = post2(options, "renew", {
+      const renew = () => post2(options, "renew", {
         migrationKey: claim.migrationKey,
         claimToken: claim.claimToken
-      }).then((value) => {
+      });
+      renewal = (options.telemetry ? options.telemetry.observe("migration.renew", renew, () => "success", remoteOutcome3) : renew()).then((value) => {
         expires = value.claimExpiresAtTs;
       }).catch((cause) => {
         if (cause instanceof SignedNodeHttpError && cause.status < 500) {
@@ -6064,7 +6566,8 @@ async function pullMigrationOnce(options) {
   schedule();
   let evidence;
   try {
-    evidence = await options.run(claim);
+    const run = () => options.run(claim);
+    evidence = options.telemetry ? await options.telemetry.observe("migration.run", run) : await run();
   } catch (cause) {
     stopped = true;
     clearTimer(timer);
@@ -6072,12 +6575,16 @@ async function pullMigrationOnce(options) {
     if (lost)
       throw lost;
     const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
-    await complete2(options, {
+    const acknowledge2 = () => complete2(options, {
       migrationKey: claim.migrationKey,
       claimToken: claim.claimToken,
       ok: false,
       detail: reason
     });
+    if (options.telemetry) {
+      await options.telemetry.observe("migration.complete", acknowledge2, () => "success", remoteOutcome3);
+    } else
+      await acknowledge2();
     return { status: "failed", claim, reason };
   }
   stopped = true;
@@ -6085,12 +6592,16 @@ async function pullMigrationOnce(options) {
   await renewal;
   if (lost)
     throw lost;
-  await complete2(options, {
+  const acknowledge = () => complete2(options, {
     migrationKey: claim.migrationKey,
     claimToken: claim.claimToken,
     ok: true,
     evidence
   });
+  if (options.telemetry) {
+    await options.telemetry.observe("migration.complete", acknowledge, () => "success", remoteOutcome3);
+  } else
+    await acknowledge();
   return { status: "completed", claim, evidence };
 }
 function startMigrationPull(options) {
@@ -6127,7 +6638,7 @@ import { chmodSync as chmodSync5, existsSync as existsSync6, unlinkSync as unlin
 import { connect as connect2, createServer as createServer3 } from "net";
 
 // src/metal-provision.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import {
   existsSync as existsSync5,
   mkdirSync as mkdirSync3,
@@ -6138,7 +6649,8 @@ import {
   unlinkSync as unlinkSync4,
   writeFileSync as writeFileSync3
 } from "fs";
-import { dirname as dirname3, isAbsolute, join as join2 } from "path";
+import { dirname as dirname3, isAbsolute as isAbsolute3, join as join2 } from "path";
+import { isIP as isIP2 } from "net";
 
 // src/compute.ts
 class ComputeError extends Error {
@@ -6280,8 +6792,8 @@ function membersOfLinuxList(value, label) {
     throw new MetalProvisionError(`${label} list overlaps itself`);
   return members;
 }
-var guestNameFor = (computeKey) => `fzg-${createHash2("sha256").update(computeKey).digest("hex").slice(0, 16)}`;
-var tapNameFor = (computeKey) => `fzt${createHash2("sha256").update(computeKey).digest("hex").slice(0, 12)}`;
+var guestNameFor = (computeKey) => `fzg-${createHash3("sha256").update(computeKey).digest("hex").slice(0, 16)}`;
+var tapNameFor = (computeKey) => `fzt${createHash3("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)) {
@@ -6299,10 +6811,18 @@ function validateMetalProfile(profile) {
   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))
+    if (!isAbsolute3(path))
       throw new MetalProvisionError("metal paths must be absolute");
   }
   new URL(profile.apiUrl);
+  let telemetryEndpoint;
+  try {
+    telemetryEndpoint = new URL(profile.agentTelemetryEndpoint);
+  } catch {
+    throw new MetalProvisionError("Agent telemetry endpoint must be an absolute public HTTPS URL");
+  }
+  if (telemetryEndpoint.protocol !== "https:" || telemetryEndpoint.username || telemetryEndpoint.password || telemetryEndpoint.search || telemetryEndpoint.hash || isIP2(telemetryEndpoint.hostname) !== 0 || !telemetryEndpoint.hostname.includes(".") || telemetryEndpoint.hostname === "localhost" || telemetryEndpoint.hostname.endsWith(".local"))
+    throw new MetalProvisionError("Agent telemetry endpoint must be a public HTTPS DNS coordinate without credentials, query or fragment");
   const imageKeys = Object.keys(profile.images);
   if (imageKeys.length !== 1 || imageKeys[0] !== SUPPORTED_GUEST_IMAGE.key || profile.images[SUPPORTED_GUEST_IMAGE.key]?.sha256 !== SUPPORTED_GUEST_IMAGE.sha256) {
     throw new MetalProvisionError(`metal profile must contain only the pinned ${SUPPORTED_GUEST_IMAGE.key} image contract`);
@@ -6363,7 +6883,7 @@ function allocateAddress(profile, computeKey, rows) {
     return existing.address;
   const used = new Set(rows.map((row) => row.address));
   const width = profile.addressEnd - profile.addressStart + 1;
-  const start = createHash2("sha256").update(computeKey).digest().readUInt16BE(0) % width;
+  const start = createHash3("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}`;
@@ -6419,7 +6939,9 @@ var yamlFile = (path, content, permissions) => `  - path: ${JSON.stringify(path)
     content: ${base64(content)}
 `;
 function guestBootstrapScript(profile, attested = Boolean(profile.confidential), hasEnrolment = true, nodeLabel = "compute") {
+  validateMetalProfile(profile);
   const agentBun = "/usr/local/lib/forgezero/bun";
+  const telemetryEndpoint = `'${profile.agentTelemetryEndpoint.replace(/'/g, `'\\''`)}'`;
   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 driver shipped by the one pinned image before the agent starts. Do
@@ -6443,7 +6965,7 @@ fi
 if [[ ! -x /usr/local/lib/forgezero/agent/fz-agent ]] || [[ "$(/usr/local/lib/forgezero/agent/fz-agent --version 2>/dev/null || true)" != "${profile.agentVersion}" ]]; then
   env BUN_INSTALL=${agentBun} /usr/local/bin/bun add -g --no-cache --force @forgezero/agent@${profile.agentVersion}
 fi
-env   FZ_API=${profile.apiUrl}   FZ_AGENT_BIN=/usr/local/lib/forgezero/agent/fz-agent   FZ_AGENT_USER=forgezero-agent   FZ_SOCKET_PATH=/run/forgezero/vault.sock   FZ_SEED_CREDENTIAL_PATH=/etc/forgezero/creds/agent-seed.cred   FZ_GIT_CREDENTIAL_PATH=/etc/forgezero/creds/git-deploy-key.cred   FZ_GIT_PUBLIC_KEY_PATH=/etc/forgezero/git/deploy.pub   FZ_DEPLOY_ROOT=/opt/forgezero   FZ_DEPLOY_PULL=${hasEnrolment ? "true" : "false"}   FZ_NODE_LABEL=${nodeLabel}   ${agentBun}/bin/fz agent install --apply${hasEnrolment ? " --enrol" : ""}
+env   FZ_API=${profile.apiUrl}   OTEL_EXPORTER_OTLP_ENDPOINT=${telemetryEndpoint}   FZ_AGENT_BIN=/usr/local/lib/forgezero/agent/fz-agent   FZ_AGENT_USER=forgezero-agent   FZ_SOCKET_PATH=/run/forgezero/vault.sock   FZ_SEED_CREDENTIAL_PATH=/etc/forgezero/creds/agent-seed.cred   FZ_GIT_CREDENTIAL_PATH=/etc/forgezero/creds/git-deploy-key.cred   FZ_GIT_PUBLIC_KEY_PATH=/etc/forgezero/git/deploy.pub   FZ_DEPLOY_ROOT=/opt/forgezero   FZ_DEPLOY_PULL=${hasEnrolment ? "true" : "false"}   FZ_AGENT_EGRESS_ENFORCE=${hasEnrolment ? "true" : "false"}   FZ_NODE_LABEL=${nodeLabel}   ${agentBun}/bin/fz agent install --apply${hasEnrolment ? " --enrol" : ""}
 `;
 }
 function cloudInit(profile, claim, manifest) {
@@ -6499,7 +7021,7 @@ async function provisionMetalGuest(profile, claim, exec) {
   if (!claim.computeKey || !claim.spec.reference || !SAFE_NAME.test(claim.spec.imageKey) || claim.spec.guestName !== undefined && !SAFE_NAME.test(claim.spec.guestName) || claim.spec.cpuPoolKey !== undefined && !SAFE_NAME.test(claim.spec.cpuPoolKey) || !Number.isInteger(claim.spec.physicalCores) || claim.spec.physicalCores < 1 || claim.spec.physicalCores > 256 || !Number.isInteger(claim.spec.vcpu) || claim.spec.vcpu < 1 || claim.spec.vcpu > 512 || !Number.isInteger(claim.spec.memoryGib) || claim.spec.memoryGib < 1 || claim.spec.memoryGib > 8192 || !Number.isInteger(claim.spec.diskGib) || claim.spec.diskGib < 8 || claim.spec.diskGib > 65536 || !Number.isInteger(claim.spec.egressGuaranteedMbps) || claim.spec.egressGuaranteedMbps < 0 || !Number.isInteger(claim.spec.egressBurstMbps) || claim.spec.egressBurstMbps < claim.spec.egressGuaranteedMbps)
     throw new MetalProvisionError("invalid compute claim");
   const image = profile.images[claim.spec.imageKey];
-  if (!image || !isAbsolute(image.path) || !SHA256.test(image.sha256)) {
+  if (!image || !isAbsolute3(image.path) || !SHA256.test(image.sha256)) {
     throw new MetalProvisionError(`image ${claim.spec.imageKey} is not configured locally`);
   }
   if (!statSync2(image.path).isFile())
@@ -6820,7 +7342,7 @@ function requestMetalProvision(claim, socketPath = DEFAULT_METAL_HELPER_SOCKET)
 
 // src/deployment-runner.ts
 import { chmodSync as chmodSync6, existsSync as existsSync7, realpathSync, unlinkSync as unlinkSync6 } from "fs";
-import { isAbsolute as isAbsolute2, resolve, sep } from "path";
+import { isAbsolute as isAbsolute4, 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;
@@ -6835,7 +7357,7 @@ 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))
+  if (!input.cwd || !isAbsolute4(input.cwd))
     throw new Error("deployment command needs an absolute working directory");
   const realRoot = realpathSync(root);
   const realCwd = realpathSync(input.cwd);
@@ -7151,6 +7673,7 @@ function createSnpAttestationSource(options = {}) {
 }
 
 // src/attestation-client.ts
+var attestationOutcome = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : cause instanceof SignedNodeHttpError ? "retryable" : "failed";
 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)) {
@@ -7177,7 +7700,8 @@ function startNodeAttestation(options) {
   const tick = () => {
     if (stopped || active)
       return;
-    active = attestNodeOnce(options).then((result) => options.onEvent?.("verified", result)).catch((cause) => options.onEvent?.("failed", cause)).finally(() => {
+    const refresh = () => attestNodeOnce(options);
+    active = (options.telemetry ? options.telemetry.observe("attestation.refresh", refresh, () => "success", attestationOutcome) : refresh()).then((result) => options.onEvent?.("verified", result)).catch((cause) => options.onEvent?.("failed", cause)).finally(() => {
       active = null;
       schedule();
     });
@@ -7319,7 +7843,7 @@ async function closeServerWithin(server, timeoutMs) {
 
 // src/lifecycle-helper.ts
 import { chmodSync as chmodSync7, existsSync as existsSync9, readFileSync as readFileSync5, unlinkSync as unlinkSync7 } from "fs";
-import { connect as connect4, createConnection, createServer as createServer5, isIP } from "net";
+import { connect as connect4, createConnection, createServer as createServer5, isIP as isIP3 } from "net";
 var DEFAULT_LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
 var MAX_REQUEST_BYTES4 = 16 * 1024;
 var REQUEST_TIMEOUT_MS = 5000;
@@ -7327,11 +7851,11 @@ var ACTION_TIMEOUT_MS = 10 * 60000;
 var unitPattern = /^[A-Za-z0-9_.@-]+\.service$/;
 var privateIp = (value) => {
   const address = value.replace(/^\[|\]$/g, "").toLowerCase();
-  if (isIP(address) === 4) {
+  if (isIP3(address) === 4) {
     const [a, b] = address.split(".").map(Number);
     return a === 10 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
   }
-  if (isIP(address) === 6) {
+  if (isIP3(address) === 6) {
     const first = Number.parseInt(address.split(":", 1)[0], 16);
     return Number.isFinite(first) && (first & 65024) === 64512;
   }
@@ -7578,7 +8102,7 @@ function materializeWarpMdm(options) {
 }
 
 // src/agent-update.ts
-import { createHash as createHash3, timingSafeEqual, randomUUID as randomUUID2 } from "crypto";
+import { createHash as createHash4, timingSafeEqual, randomUUID as randomUUID2 } from "crypto";
 import {
   chmodSync as chmodSync9,
   closeSync,
@@ -7698,9 +8222,9 @@ async function stageAgentRelease(releaseInput, options) {
   const versions = join4(root, "versions");
   const finalDirectory = join4(versions, release.version);
   const currentLink = join4(root, "current");
-  const stage = join4(versions, `.${release.version}.${randomUUID2()}.staging`);
-  const archive = join4(stage, "agent.tgz");
-  const unpacked = join4(stage, "unpacked");
+  const stage2 = join4(versions, `.${release.version}.${randomUUID2()}.staging`);
+  const archive = join4(stage2, "agent.tgz");
+  const unpacked = join4(stage2, "unpacked");
   const run = options.run ?? command;
   mkdirSync6(unpacked, { recursive: true, mode: 448 });
   try {
@@ -7718,7 +8242,7 @@ async function stageAgentRelease(releaseInput, options) {
       throw new Error("agent update tarball is empty or exceeds the size limit");
     }
     const expected = Buffer.from(release.integrity.slice("sha512-".length), "base64");
-    const actual = createHash3("sha512").update(bytes).digest();
+    const actual = createHash4("sha512").update(bytes).digest();
     if (!timingSafeEqual(actual, expected))
       throw new Error("agent update integrity mismatch");
     writeFileSync6(archive, bytes, { mode: 384, flag: "wx" });
@@ -7760,7 +8284,7 @@ async function stageAgentRelease(releaseInput, options) {
       currentLink
     };
   } finally {
-    rmSync2(stage, { recursive: true, force: true });
+    rmSync2(stage2, { recursive: true, force: true });
   }
 }
 function selectAgentRelease(staged) {
@@ -7807,6 +8331,7 @@ var AGENT_UPDATE_JOURNAL = "/var/lib/forgezero/agent-update.json";
 var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update-receipt.json";
 var MAX_REQUEST_BYTES5 = 8 * 1024;
 var COMPUTE_HELPER_UNITS = [
+  "forgezero-agent-egress.service",
   "forgezero-deploy-runner.service",
   "forgezero-lifecycle-helper.service",
   "forgezero-software-helper.service"
@@ -8252,10 +8777,14 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 import { readFileSync as readFileSync8 } from "fs";
 
 // src/version.ts
-var VERSION3 = "0.1.32";
+var VERSION3 = "0.1.34";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");
+var remoteOutcome4 = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : cause instanceof SignedNodeHttpError ? "retryable" : "failed";
+
+class AgentUpdateRefusedError extends Error {
+}
 function observeAgentHost(version = VERSION3, mode = "enrolled", osRelease = readFileSync8("/etc/os-release", "utf8"), architecture = process.arch) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
@@ -8303,17 +8832,25 @@ async function heartbeatAgentOnce(options) {
       try {
         await options.prepareUpdate?.(release);
         prepared = true;
-        const applied = await (options.applyUpdate ?? ((next, current, attemptId) => requestAgentUpdate({
-          op: "apply",
-          target: options.updateTarget ?? "compute",
-          release: next,
-          currentVersion: current,
-          attemptId
-        })))(release, observation.version, desired.attemptId);
-        if (!applied.ok)
-          throw new Error(`agent update refused: ${applied.error.message}`);
-        if (applied.attemptId !== desired.attemptId) {
-          throw new Error("agent update helper returned the wrong rollout attempt");
+        const apply = async () => {
+          const applied = await (options.applyUpdate ?? ((next, current, attemptId) => requestAgentUpdate({
+            op: "apply",
+            target: options.updateTarget ?? "compute",
+            release: next,
+            currentVersion: current,
+            attemptId
+          })))(release, observation.version, desired.attemptId);
+          if (!applied.ok)
+            throw new AgentUpdateRefusedError(`agent update refused: ${applied.error.message}`);
+          if (applied.attemptId !== desired.attemptId) {
+            throw new Error("agent update helper returned the wrong rollout attempt");
+          }
+          return applied;
+        };
+        if (options.telemetry) {
+          await options.telemetry.observe("agent.update", apply, () => "success", (cause) => cause instanceof AgentUpdateRefusedError ? "refused" : "failed");
+        } else {
+          await apply();
         }
         options.onEvent?.("update-staged", { from: observation.version, to: release.version });
       } catch (cause) {
@@ -8335,7 +8872,8 @@ function startAgentHeartbeat(options) {
     if (stopped || active)
       return;
     let nextSeconds = 30;
-    active = heartbeatAgentOnce(options).then((response) => {
+    const heartbeat = () => heartbeatAgentOnce(options);
+    active = (options.telemetry ? options.telemetry.observe("agent.heartbeat", heartbeat, () => "success", remoteOutcome4) : heartbeat()).then((response) => {
       nextSeconds = Math.max(5, Math.min(response.intervalSeconds, 300));
     }).catch((cause) => options.onEvent?.("heartbeat-failed", cause)).finally(() => {
       active = null;
@@ -8462,6 +9000,884 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
   });
 }
 
+// src/egress-policy.ts
+import { realpathSync as realpathSync2 } from "fs";
+var AGENT_EGRESS_TABLE = "forgezero_agent_egress";
+var SYSTEMD_RESOLVED_STUB = "/run/systemd/resolve/stub-resolv.conf";
+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 assertServiceUser = (user) => {
+  if (!/^[a-z_][a-z0-9_-]{0,30}$/.test(user))
+    throw new Error("Agent egress user is invalid.");
+};
+var assertUid = (uid) => {
+  if (!Number.isSafeInteger(uid) || uid < 1 || uid > 4294967295) {
+    throw new Error("Agent egress policy refuses an invalid or root service UID.");
+  }
+};
+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(`
+`);
+}
+function renderAgentEgressNft(uids, replace = false, loopback) {
+  if (uids.length < 1)
+    throw new Error("Agent egress policy needs at least one service UID.");
+  for (const uid of uids)
+    assertUid(uid);
+  const uniqueUids = [...new Set(uids)].sort((left, right) => left - right);
+  let loopbackRules = "";
+  let loopbackSet = "";
+  let loopbackComment = "";
+  let restrictedPublicRules = "";
+  if (loopback) {
+    assertUid(loopback.uid);
+    if (!uniqueUids.includes(loopback.uid))
+      throw new Error("Loopback egress UID must be protected.");
+    const ports = normalizeEgressTcpPorts(loopback.tcpPorts);
+    const publicPorts = loopback.publicTcpPorts === undefined ? undefined : normalizeEgressTcpPorts(loopback.publicTcpPorts);
+    if (publicPorts && publicPorts.length < 1) {
+      throw new Error("Restricted public egress needs at least one TCP port.");
+    }
+    if (ports.length < 1 && !publicPorts) {
+      throw new Error("Restricted egress needs a loopback or public TCP port.");
+    }
+    loopbackComment = (ports.length > 0 ? ` loopback=${loopback.uid}:${ports.join(",")}` : "") + (publicPorts ? ` public-tcp=${publicPorts.join(",")}` : "");
+    loopbackSet = `${ports.length > 0 ? `	set loopback_tcp_ports {
+		type inet_service
+		elements = { ${ports.join(", ")} }
+	}
+` : ""}${publicPorts ? `	set public_tcp_ports {
+		type inet_service
+		elements = { ${publicPorts.join(", ")} }
+	}
+` : ""}`;
+    loopbackRules = ports.length > 0 ? `		meta skuid ${loopback.uid} tcp dport @loopback_tcp_ports ip daddr 127.0.0.1 accept
+		meta skuid ${loopback.uid} tcp dport @loopback_tcp_ports ip6 daddr ::1 accept
+` : "";
+    restrictedPublicRules = publicPorts ? `		meta skuid ${loopback.uid} tcp dport @public_tcp_ports accept
+		meta skuid ${loopback.uid} reject
+` : "";
+  }
+  return `${replace ? `delete table inet ${AGENT_EGRESS_TABLE}
+` : ""}table inet ${AGENT_EGRESS_TABLE} {
+	comment "forgezero-agent-egress-v1 uids=${uniqueUids.join(",")}${loopbackComment}"
+	set service_uids {
+		type uid
+		elements = { ${uniqueUids.join(", ")} }
+	}
+${loopbackSet}	set blocked_ipv4 {
+		type ipv4_addr
+		flags interval
+		elements = { ${BLOCKED_IPV4.join(", ")} }
+	}
+	set blocked_ipv6 {
+		type ipv6_addr
+		flags interval
+		elements = { ${BLOCKED_IPV6.join(", ")} }
+	}
+	chain output {
+		type filter hook output priority filter; policy accept;
+		meta skuid @service_uids udp dport 53 ip daddr ${SYSTEMD_RESOLVED_ADDRESS} accept
+		meta skuid @service_uids tcp dport 53 ip daddr ${SYSTEMD_RESOLVED_ADDRESS} accept
+${loopbackRules}		meta skuid @service_uids udp dport 53 reject
+		meta skuid @service_uids tcp dport 53 reject
+		meta skuid @service_uids ip daddr @blocked_ipv4 reject
+		meta skuid @service_uids ip6 daddr @blocked_ipv6 reject
+		meta skuid @service_uids ip6 daddr != 2000::/3 reject
+${restrictedPublicRules}	}
+}
+`;
+}
+var systemCommand = (argv, stdin) => {
+  const result = Bun.spawnSync([...argv], {
+    stdin: stdin === undefined ? undefined : Buffer.from(stdin),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdout.toString(),
+    stderr: result.stderr.toString()
+  };
+};
+function resolveServiceUid(user, command2 = systemCommand) {
+  assertServiceUser(user);
+  const result = command2(["/usr/bin/id", "-u", user]);
+  const uid = Number(result.stdout.trim());
+  if (result.exitCode !== 0 || !/^\d+$/.test(result.stdout.trim())) {
+    throw new Error(`Agent egress service account ${user} does not exist.`);
+  }
+  assertUid(uid);
+  return uid;
+}
+function assertResolvedStub(realpath = realpathSync2) {
+  let source;
+  try {
+    source = realpath("/etc/resolv.conf");
+  } catch {
+    throw new Error("Agent egress requires /etc/resolv.conf.");
+  }
+  if (source !== SYSTEMD_RESOLVED_STUB) {
+    throw new Error(`Agent egress requires /etc/resolv.conf to use ${SYSTEMD_RESOLVED_STUB}; found ${source}.`);
+  }
+  try {
+    if (realpath(SYSTEMD_RESOLVED_STUB) !== SYSTEMD_RESOLVED_STUB)
+      throw new Error("not canonical");
+  } catch {
+    throw new Error("Agent egress requires the active systemd-resolved stub.");
+  }
+}
+var listPolicy = (command2) => command2(["/usr/sbin/nft", "--numeric", "list", "table", "inet", AGENT_EGRESS_TABLE]);
+function verifyAgentEgressPolicy(uids, command2 = systemCommand, loopback) {
+  if (uids.length < 1)
+    return false;
+  for (const uid of uids)
+    assertUid(uid);
+  const uniqueUids = [...new Set(uids)].sort((left, right) => left - right);
+  const result = listPolicy(command2);
+  if (result.exitCode !== 0)
+    return false;
+  let loopbackComment = "";
+  const loopbackRequired = [];
+  if (loopback) {
+    assertUid(loopback.uid);
+    if (!uniqueUids.includes(loopback.uid))
+      return false;
+    const ports = normalizeEgressTcpPorts(loopback.tcpPorts);
+    const publicPorts = loopback.publicTcpPorts === undefined ? undefined : normalizeEgressTcpPorts(loopback.publicTcpPorts);
+    if (publicPorts && publicPorts.length < 1)
+      return false;
+    if (ports.length < 1 && !publicPorts)
+      return false;
+    loopbackComment = (ports.length > 0 ? ` loopback=${loopback.uid}:${ports.join(",")}` : "") + (publicPorts ? ` public-tcp=${publicPorts.join(",")}` : "");
+    if (ports.length > 0)
+      loopbackRequired.push(`elements = { ${ports.join(", ")} }`, `meta skuid ${loopback.uid} tcp dport @loopback_tcp_ports ip daddr 127.0.0.1 accept`, `meta skuid ${loopback.uid} tcp dport @loopback_tcp_ports ip6 daddr ::1 accept`);
+    if (publicPorts)
+      loopbackRequired.push(`elements = { ${publicPorts.join(", ")} }`, `meta skuid ${loopback.uid} tcp dport @public_tcp_ports accept`, `meta skuid ${loopback.uid} reject`);
+  }
+  const required = [
+    `comment "forgezero-agent-egress-v1 uids=${uniqueUids.join(",")}${loopbackComment}"`,
+    `elements = { ${uniqueUids.join(", ")} }`,
+    ...loopbackRequired,
+    `meta skuid @service_uids udp dport 53 ip daddr ${SYSTEMD_RESOLVED_ADDRESS} accept`,
+    `meta skuid @service_uids tcp dport 53 ip daddr ${SYSTEMD_RESOLVED_ADDRESS} accept`,
+    "meta skuid @service_uids udp dport 53 reject",
+    "meta skuid @service_uids tcp dport 53 reject",
+    "meta skuid @service_uids ip daddr @blocked_ipv4 reject",
+    "meta skuid @service_uids ip6 daddr @blocked_ipv6 reject",
+    "meta skuid @service_uids ip6 daddr != 2000::/3 reject",
+    ...BLOCKED_IPV4.map((network) => network.endsWith("/32") ? network.slice(0, -3) : network),
+    ...BLOCKED_IPV6.map((network) => {
+      if (network === "::ffff:0:0/96")
+        return "::ffff:0.0.0.0/96";
+      return network.endsWith("/128") ? network.slice(0, -4) : network;
+    })
+  ];
+  return required.every((fragment) => result.stdout.includes(fragment));
+}
+function applyAgentEgressPolicy(options) {
+  const getuid = options.getuid ?? process.getuid;
+  if (typeof getuid !== "function" || getuid() !== 0) {
+    throw new Error("Agent egress policy must run as root.");
+  }
+  const command2 = options.command ?? systemCommand;
+  assertResolvedStub(options.realpath);
+  if (options.users.length < 1)
+    throw new Error("Agent egress policy needs at least one service user.");
+  const uids = [...new Set(options.users.map((user) => resolveServiceUid(user, command2)))];
+  const loopback = options.loopback ? {
+    uid: resolveServiceUid(options.loopback.user, command2),
+    tcpPorts: normalizeEgressTcpPorts(options.loopback.tcpPorts),
+    publicTcpPorts: options.loopback.publicTcpPorts === undefined ? undefined : normalizeEgressTcpPorts(options.loopback.publicTcpPorts)
+  } : undefined;
+  if (loopback && !uids.includes(loopback.uid))
+    uids.push(loopback.uid);
+  const current = listPolicy(command2);
+  const applied = command2(["/usr/sbin/nft", "--file", "-"], renderAgentEgressNft(uids, current.exitCode === 0, loopback));
+  if (applied.exitCode !== 0) {
+    throw new Error(`Could not apply Agent egress policy: ${applied.stderr.trim() || "nft refused it"}`);
+  }
+  if (!verifyAgentEgressPolicy(uids, command2, loopback)) {
+    throw new Error("Agent egress policy did not verify after installation.");
+  }
+  return uids;
+}
+async function superviseAgentEgressPolicy(options) {
+  const command2 = options.command ?? systemCommand;
+  const uids = applyAgentEgressPolicy({
+    users: options.users,
+    loopback: options.loopback,
+    command: command2,
+    realpath: options.realpath,
+    getuid: options.getuid
+  });
+  const loopback = options.loopback ? {
+    uid: resolveServiceUid(options.loopback.user, command2),
+    tcpPorts: normalizeEgressTcpPorts(options.loopback.tcpPorts),
+    publicTcpPorts: options.loopback.publicTcpPorts === undefined ? undefined : normalizeEgressTcpPorts(options.loopback.publicTcpPorts)
+  } : undefined;
+  (options.notifyReady ?? (() => {
+    const result = command2(["/usr/bin/systemd-notify", "--ready"]);
+    if (result.exitCode !== 0)
+      throw new Error("Could not notify systemd that Agent egress is ready.");
+  }))();
+  const wait = options.wait ?? ((milliseconds) => new Promise((resolve4) => setTimeout(resolve4, milliseconds)));
+  const intervalMs = options.intervalMs ?? 1000;
+  if (!Number.isSafeInteger(intervalMs) || intervalMs < 100 || intervalMs > 60000) {
+    throw new Error("Agent egress monitor interval is invalid.");
+  }
+  for (;; ) {
+    await wait(intervalMs);
+    if (!verifyAgentEgressPolicy(uids, command2, loopback)) {
+      throw new Error("Agent egress policy disappeared or changed; stopping the bound Agent.");
+    }
+  }
+}
+
+// src/telemetry.ts
+var AGENT_TELEMETRY_OPERATIONS = [
+  "agent.heartbeat",
+  "agent.update",
+  "attestation.refresh",
+  "deployment.claim",
+  "deployment.run",
+  "deployment.renew",
+  "deployment.complete",
+  "migration.claim",
+  "migration.run",
+  "migration.renew",
+  "migration.complete",
+  "provisioning.preflight",
+  "provisioning.claim",
+  "provisioning.apply",
+  "provisioning.renew",
+  "provisioning.complete",
+  "vault.sync",
+  "agent.other"
+];
+var AGENT_TELEMETRY_OUTCOMES = [
+  "success",
+  "idle",
+  "refused",
+  "retryable",
+  "failed"
+];
+var AGENT_TELEMETRY_EVENTS = [
+  "agent.started",
+  "agent.draining",
+  "agent.stopped",
+  "agent.update_prepared",
+  "agent.update_recovered",
+  "telemetry.queue_overflow"
+];
+var AGENT_OTLP_EXPORT_TIMEOUT_MS = 5000;
+var AGENT_OTLP_MAX_ATTEMPTS = 2;
+var AGENT_OTLP_MAX_RETRY_DELAY_MS = 1000;
+var AGENT_TELEMETRY_MAX_SPANS = 256;
+var AGENT_TELEMETRY_MAX_LOGS = 64;
+var AGENT_OTLP_RETRY_BASE_MS = 100;
+var AGENT_OTLP_MAX_RESPONSE_BYTES = 4096;
+var AGENT_TELEMETRY_CLOSE_DRAIN_PASSES = 2;
+var MAX_STATE_VALUE = 1e9;
+var MAX_DURATION_MS = 24 * 60 * 60000;
+var MAX_COUNTER_VALUE = Number.MAX_SAFE_INTEGER;
+var HISTOGRAM_BOUNDS = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 30000];
+var OPERATION_SET = new Set(AGENT_TELEMETRY_OPERATIONS);
+var OUTCOME_SET = new Set(AGENT_TELEMETRY_OUTCOMES);
+var EVENT_SET = new Set(AGENT_TELEMETRY_EVENTS);
+function requiredToken(value, name) {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > 128 || !/^[A-Za-z0-9._:-]+$/.test(trimmed)) {
+    throw new Error(`${name} must be a non-empty operational token`);
+  }
+  return trimmed;
+}
+function resolveAgentTelemetryConfig(env = process.env) {
+  const raw = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+  if (!raw) {
+    if (env.NODE_ENV === "production") {
+      throw new Error("OTEL_EXPORTER_OTLP_ENDPOINT is required when NODE_ENV=production");
+    }
+    return null;
+  }
+  let endpoint;
+  try {
+    endpoint = new URL(raw);
+  } catch {
+    throw new Error("OTEL_EXPORTER_OTLP_ENDPOINT must be an absolute URL");
+  }
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error("OTEL_EXPORTER_OTLP_ENDPOINT cannot contain credentials, query parameters or a fragment");
+  }
+  const loopback = endpoint.hostname === "127.0.0.1" || endpoint.hostname === "localhost" || endpoint.hostname === "[::1]";
+  if (endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && loopback)) {
+    throw new Error("Agent OTLP must use HTTPS, except for a loopback collector");
+  }
+  endpoint.pathname = endpoint.pathname.replace(/\/$/, "");
+  const flushIntervalMs = Number(env.FZ_OTLP_FLUSH_INTERVAL_MS ?? 5000);
+  if (!Number.isSafeInteger(flushIntervalMs) || flushIntervalMs < 1000 || flushIntervalMs > 60000) {
+    throw new Error("FZ_OTLP_FLUSH_INTERVAL_MS must be between 1000 and 60000");
+  }
+  const traceSampleRatio = Number(env.FZ_OTLP_TRACE_SAMPLE_RATIO ?? 0.1);
+  if (!Number.isFinite(traceSampleRatio) || traceSampleRatio < 0 || traceSampleRatio > 1) {
+    throw new Error("FZ_OTLP_TRACE_SAMPLE_RATIO must be between 0 and 1");
+  }
+  return {
+    endpoint: endpoint.toString().replace(/\/$/, ""),
+    serviceName: requiredToken(env.OTEL_SERVICE_NAME ?? "forgezero-agent", "OTEL_SERVICE_NAME"),
+    instanceId: requiredToken(env.FZ_NODE_HOSTNAME ?? env.FZ_METAL_HOSTNAME ?? "unbound-agent", "Agent telemetry instance id"),
+    environment: env.NODE_ENV === "production" ? "production" : "development",
+    flushIntervalMs,
+    traceSampleRatio
+  };
+}
+var attribute = (key, value) => ({
+  key,
+  value: typeof value === "string" ? { stringValue: value } : typeof value === "boolean" ? { boolValue: value } : { intValue: String(Math.trunc(value)) }
+});
+var nanos = (milliseconds) => String(BigInt(Math.max(0, Math.floor(milliseconds))) * 1000000n);
+var randomHex = (bytes) => {
+  const value = new Uint8Array(bytes);
+  crypto.getRandomValues(value);
+  return [...value].map((part) => part.toString(16).padStart(2, "0")).join("");
+};
+var boundedInteger = (value, maximum = MAX_STATE_VALUE) => Number.isFinite(value) ? Math.min(maximum, Math.max(0, Math.floor(value))) : 0;
+
+class RetryableExportError extends Error {
+  retryAfterMs;
+  constructor(retryAfterMs = null) {
+    super("Transient OTLP export failure");
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+class PermanentExportError extends Error {
+  constructor() {
+    super("Permanent OTLP export failure");
+  }
+}
+var TRANSIENT_EXPORT_STATUSES = new Set([408, 429, 502, 503, 504]);
+function retryAfterMilliseconds(value, currentTimeMs) {
+  if (!value)
+    return null;
+  const seconds = Number(value);
+  const requested = Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : Date.parse(value) - currentTimeMs;
+  if (!Number.isFinite(requested) || requested < 0)
+    return null;
+  return Math.min(AGENT_OTLP_MAX_RETRY_DELAY_MS, Math.ceil(requested));
+}
+async function boundedResponseJson(response) {
+  if (!response.body)
+    return null;
+  const reader = response.body.getReader();
+  const chunks = [];
+  let length = 0;
+  while (true) {
+    const next = await reader.read();
+    if (next.done)
+      break;
+    length += next.value.byteLength;
+    if (length > AGENT_OTLP_MAX_RESPONSE_BYTES) {
+      await reader.cancel();
+      throw new PermanentExportError;
+    }
+    chunks.push(next.value);
+  }
+  if (length === 0)
+    return null;
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  const text2 = new TextDecoder().decode(bytes).trim();
+  if (!text2)
+    return null;
+  try {
+    return JSON.parse(text2);
+  } catch {
+    throw new PermanentExportError;
+  }
+}
+function rejectedItemsFromResponse(path, payload, sentItems) {
+  if (!payload || typeof payload !== "object" || !("partialSuccess" in payload))
+    return 0;
+  const partial = payload.partialSuccess;
+  if (!partial || typeof partial !== "object")
+    return 0;
+  const key = path === "/v1/traces" ? "rejectedSpans" : path === "/v1/logs" ? "rejectedLogRecords" : "rejectedDataPoints";
+  const raw = partial[key];
+  const count = typeof raw === "string" || typeof raw === "number" ? Number(raw) : 0;
+  return Number.isSafeInteger(count) && count > 0 ? Math.min(sentItems, count) : 0;
+}
+function createAgentTelemetry(input, options = {}) {
+  if (!input) {
+    return {
+      recordOperation() {},
+      recordEvent() {},
+      recordState() {},
+      async flush() {},
+      async close() {}
+    };
+  }
+  const config = {
+    ...input,
+    serviceName: requiredToken(input.serviceName, "Agent telemetry service name"),
+    instanceId: requiredToken(input.instanceId, "Agent telemetry instance id")
+  };
+  if (config.environment !== "production" && config.environment !== "development") {
+    throw new Error("Agent telemetry environment must be production or development");
+  }
+  if (config.endpoint !== resolveAgentTelemetryConfig({
+    OTEL_EXPORTER_OTLP_ENDPOINT: config.endpoint,
+    OTEL_SERVICE_NAME: config.serviceName,
+    FZ_NODE_HOSTNAME: config.instanceId,
+    FZ_OTLP_FLUSH_INTERVAL_MS: String(config.flushIntervalMs),
+    FZ_OTLP_TRACE_SAMPLE_RATIO: String(config.traceSampleRatio),
+    NODE_ENV: config.environment
+  })?.endpoint)
+    throw new Error("Agent telemetry endpoint is not canonical");
+  const send = options.fetch ?? fetch;
+  const warn = options.warn ?? ((message) => console.warn(`[telemetry] ${message}`));
+  const now = options.now ?? Date.now;
+  const random = options.random ?? Math.random;
+  const wait = options.wait ?? ((milliseconds) => new Promise((resolve4) => setTimeout(resolve4, milliseconds)));
+  const processStartedAtMs = Math.max(0, Math.floor(now()));
+  const processInstanceId = randomHex(16);
+  const resource = {
+    attributes: [
+      attribute("service.name", config.serviceName),
+      attribute("service.instance.id", processInstanceId),
+      attribute("forgezero.agent.instance", config.instanceId),
+      attribute("deployment.environment.name", config.environment)
+    ]
+  };
+  const metrics = new Map;
+  let spans = [];
+  let logs = [];
+  let state = null;
+  let dropped = 0;
+  let exportDiscards = 0;
+  let metricsDirty = false;
+  let stateDirty = false;
+  let overflowNoted = false;
+  let activeFlush = null;
+  let closePromise = null;
+  let closed = false;
+  const logRecord = (event) => ({
+    timeUnixNano: nanos(now()),
+    severityNumber: event === "telemetry.queue_overflow" ? 13 : 9,
+    severityText: event === "telemetry.queue_overflow" ? "WARN" : "INFO",
+    body: { stringValue: event }
+  });
+  const noteDrop = () => {
+    dropped = Math.min(MAX_COUNTER_VALUE, dropped + 1);
+    if (!overflowNoted && logs.length < AGENT_TELEMETRY_MAX_LOGS) {
+      overflowNoted = true;
+      logs.push(logRecord("telemetry.queue_overflow"));
+    }
+  };
+  const post3 = async (path, body, sentItems) => {
+    for (let attempt = 0;attempt < AGENT_OTLP_MAX_ATTEMPTS; attempt += 1) {
+      try {
+        const response = await send(`${config.endpoint}${path}`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(AGENT_OTLP_EXPORT_TIMEOUT_MS)
+        });
+        if (TRANSIENT_EXPORT_STATUSES.has(response.status)) {
+          try {
+            await response.body?.cancel();
+          } catch {}
+          throw new RetryableExportError(retryAfterMilliseconds(response.headers.get("retry-after"), now()));
+        }
+        if (!response.ok) {
+          try {
+            await response.body?.cancel();
+          } catch {}
+          throw new PermanentExportError;
+        }
+        if (response.status !== 200) {
+          try {
+            await response.body?.cancel();
+          } catch {}
+          return { rejectedItems: 0 };
+        }
+        const payload = await boundedResponseJson(response);
+        return { rejectedItems: rejectedItemsFromResponse(path, payload, sentItems) };
+      } catch (cause) {
+        const transient = cause instanceof RetryableExportError || !(cause instanceof PermanentExportError);
+        if (!transient || attempt + 1 >= AGENT_OTLP_MAX_ATTEMPTS)
+          throw new PermanentExportError;
+        const retryAfter2 = cause instanceof RetryableExportError ? cause.retryAfterMs : null;
+        const backoff = AGENT_OTLP_RETRY_BASE_MS * 2 ** attempt;
+        const randomValue = random();
+        const jitter = Math.floor((Number.isFinite(randomValue) ? Math.max(0, Math.min(1, randomValue)) : 0) * backoff);
+        await wait(Math.min(AGENT_OTLP_MAX_RETRY_DELAY_MS, Math.max(retryAfter2 ?? 0, backoff + jitter)));
+      }
+    }
+    throw new PermanentExportError;
+  };
+  const hasPending = () => spans.length > 0 || logs.length > 0 || dropped > 0 || exportDiscards > 0 || metricsDirty || stateDirty;
+  const addExportDiscards = (count) => {
+    exportDiscards = Math.min(MAX_COUNTER_VALUE, exportDiscards + boundedInteger(count, MAX_COUNTER_VALUE));
+  };
+  const retainFailedRecords = (kind, records) => {
+    if (closed) {
+      addExportDiscards(records.length);
+      return;
+    }
+    const target = kind === "traces" ? spans : logs;
+    const maximum = kind === "traces" ? AGENT_TELEMETRY_MAX_SPANS : AGENT_TELEMETRY_MAX_LOGS;
+    const combined = [...records, ...target];
+    const overflow = Math.max(0, combined.length - maximum);
+    const retained = combined.slice(-maximum);
+    if (kind === "traces")
+      spans = retained;
+    else
+      logs = retained;
+    if (overflow > 0)
+      dropped = Math.min(MAX_COUNTER_VALUE, dropped + overflow);
+  };
+  const api = {
+    recordOperation(observation) {
+      if (closed)
+        return;
+      const suppliedOperation = observation.operation;
+      const operation = typeof suppliedOperation === "string" && OPERATION_SET.has(suppliedOperation) ? suppliedOperation : "agent.other";
+      const suppliedOutcome = observation.outcome;
+      const outcome = typeof suppliedOutcome === "string" && OUTCOME_SET.has(suppliedOutcome) ? suppliedOutcome : "failed";
+      const duration = Number.isFinite(observation.durationMs) ? Math.min(MAX_DURATION_MS, Math.max(0, observation.durationMs)) : 0;
+      const key = `${operation}:${outcome}`;
+      const metric = metrics.get(key) ?? {
+        operation,
+        outcome,
+        count: 0,
+        sum: 0,
+        buckets: Array(HISTOGRAM_BOUNDS.length + 1).fill(0)
+      };
+      metric.count = Math.min(MAX_COUNTER_VALUE, metric.count + 1);
+      metric.sum = Math.min(MAX_COUNTER_VALUE, metric.sum + duration);
+      const bucket = HISTOGRAM_BOUNDS.findIndex((bound) => duration <= bound);
+      metric.buckets[bucket < 0 ? HISTOGRAM_BOUNDS.length : bucket] = Math.min(MAX_COUNTER_VALUE, metric.buckets[bucket < 0 ? HISTOGRAM_BOUNDS.length : bucket] + 1);
+      metrics.set(key, metric);
+      metricsDirty = true;
+      if (config.traceSampleRatio <= 0 || random() >= config.traceSampleRatio)
+        return;
+      if (spans.length >= AGENT_TELEMETRY_MAX_SPANS)
+        return noteDrop();
+      const endedAt = now();
+      const startedAt = Number.isFinite(observation.startedAtMs) && observation.startedAtMs >= 0 ? Math.min(observation.startedAtMs, endedAt) : Math.max(0, endedAt - duration);
+      const endTime = Math.max(startedAt, Math.min(endedAt, startedAt + duration));
+      spans.push({
+        traceId: randomHex(16),
+        spanId: randomHex(8),
+        name: operation,
+        kind: 1,
+        flags: 1,
+        startTimeUnixNano: nanos(startedAt),
+        endTimeUnixNano: nanos(endTime),
+        attributes: [
+          attribute("forgezero.agent.operation", operation),
+          attribute("forgezero.agent.outcome", outcome)
+        ],
+        status: {
+          code: outcome === "failed" || outcome === "refused" || outcome === "retryable" ? 2 : outcome === "success" ? 1 : 0
+        }
+      });
+    },
+    recordEvent(event) {
+      if (closed)
+        return;
+      const supplied = event;
+      if (!EVENT_SET.has(supplied))
+        return;
+      if (logs.length >= AGENT_TELEMETRY_MAX_LOGS)
+        return noteDrop();
+      logs.push(logRecord(supplied));
+    },
+    recordState(snapshot) {
+      if (closed)
+        return;
+      state = {
+        active: boundedInteger(snapshot.active),
+        completed: boundedInteger(snapshot.completed),
+        failed: boundedInteger(snapshot.failed),
+        draining: snapshot.draining === true
+      };
+      stateDirty = true;
+    },
+    async flush() {
+      if (activeFlush)
+        return activeFlush;
+      if (!hasPending())
+        return;
+      const currentSpans = spans;
+      const currentLogs = logs;
+      const droppedNow = dropped;
+      const exportDiscardsNow = exportDiscards;
+      const metricValues = metricsDirty ? [...metrics.values()] : [];
+      const stateNow = stateDirty ? state : null;
+      spans = [];
+      logs = [];
+      dropped = 0;
+      exportDiscards = 0;
+      metricsDirty = false;
+      stateDirty = false;
+      overflowNoted = false;
+      const timeUnixNano = nanos(now());
+      const startTimeUnixNano = nanos(processStartedAtMs);
+      const metricRows = metricValues.map((metric) => ({
+        attributes: [
+          attribute("forgezero.agent.operation", metric.operation),
+          attribute("forgezero.agent.outcome", metric.outcome)
+        ],
+        startTimeUnixNano,
+        timeUnixNano,
+        count: String(metric.count),
+        sum: metric.sum,
+        explicitBounds: [...HISTOGRAM_BOUNDS],
+        bucketCounts: metric.buckets.map(String)
+      }));
+      const metricInstruments = [];
+      let metricPointCount = 0;
+      if (metricRows.length > 0) {
+        metricInstruments.push({ name: "forgezero.agent.operation.duration", unit: "ms", histogram: {
+          aggregationTemporality: 2,
+          dataPoints: metricRows
+        } }, { name: "forgezero.agent.operations", sum: {
+          aggregationTemporality: 2,
+          isMonotonic: true,
+          dataPoints: metricRows.map((row, index) => ({
+            attributes: row.attributes,
+            asInt: String(metricValues[index].count),
+            startTimeUnixNano,
+            timeUnixNano
+          }))
+        } });
+        metricPointCount += metricRows.length * 2;
+      }
+      if (droppedNow > 0) {
+        metricInstruments.push({ name: "forgezero.agent.telemetry.dropped", sum: {
+          aggregationTemporality: 1,
+          isMonotonic: true,
+          dataPoints: [{ asInt: String(droppedNow), timeUnixNano }]
+        } });
+        metricPointCount += 1;
+      }
+      if (exportDiscardsNow > 0) {
+        metricInstruments.push({ name: "forgezero.agent.telemetry.exports.discarded", sum: {
+          aggregationTemporality: 1,
+          isMonotonic: true,
+          dataPoints: [{ asInt: String(exportDiscardsNow), timeUnixNano }]
+        } });
+        metricPointCount += 1;
+      }
+      if (stateNow) {
+        metricInstruments.push({ name: "forgezero.agent.work.active", gauge: { dataPoints: [{ asInt: String(stateNow.active), timeUnixNano }] } }, { name: "forgezero.agent.work.completed", gauge: { dataPoints: [{ asInt: String(stateNow.completed), timeUnixNano }] } }, { name: "forgezero.agent.work.failed", gauge: { dataPoints: [{ asInt: String(stateNow.failed), timeUnixNano }] } }, { name: "forgezero.agent.draining", gauge: { dataPoints: [{ asInt: stateNow.draining ? "1" : "0", timeUnixNano }] } });
+        metricPointCount += 4;
+      }
+      const exports = [];
+      if (currentSpans.length > 0)
+        exports.push({
+          kind: "traces",
+          itemCount: currentSpans.length,
+          promise: post3("/v1/traces", {
+            resourceSpans: [{ resource, scopeSpans: [{
+              scope: { name: "forgezero.agent" },
+              spans: currentSpans
+            }] }]
+          }, currentSpans.length)
+        });
+      if (metricPointCount > 0)
+        exports.push({
+          kind: "metrics",
+          itemCount: metricPointCount,
+          promise: post3("/v1/metrics", {
+            resourceMetrics: [{ resource, scopeMetrics: [{
+              scope: { name: "forgezero.agent" },
+              metrics: metricInstruments
+            }] }]
+          }, metricPointCount)
+        });
+      if (currentLogs.length > 0)
+        exports.push({
+          kind: "logs",
+          itemCount: currentLogs.length,
+          promise: post3("/v1/logs", {
+            resourceLogs: [{ resource, scopeLogs: [{
+              scope: { name: "forgezero.agent" },
+              logRecords: currentLogs
+            }] }]
+          }, currentLogs.length)
+        });
+      activeFlush = Promise.allSettled(exports.map((entry) => entry.promise)).then((results) => {
+        let failed = false;
+        let partiallyRejected = 0;
+        for (const [index, result] of results.entries()) {
+          const exported = exports[index];
+          if (result.status === "fulfilled") {
+            partiallyRejected += result.value.rejectedItems;
+            continue;
+          }
+          failed = true;
+          if (exported.kind === "traces")
+            retainFailedRecords("traces", currentSpans);
+          else if (exported.kind === "logs")
+            retainFailedRecords("logs", currentLogs);
+          else if (closed)
+            addExportDiscards(exportDiscardsNow + exported.itemCount);
+          else {
+            if (metricValues.length > 0)
+              metricsDirty = true;
+            if (stateNow)
+              stateDirty = true;
+            dropped = Math.min(MAX_COUNTER_VALUE, dropped + droppedNow);
+            addExportDiscards(exportDiscardsNow);
+          }
+        }
+        if (partiallyRejected > 0) {
+          addExportDiscards(partiallyRejected);
+          warn("OTLP export partially rejected telemetry");
+        }
+        if (failed)
+          warn("OTLP export failed");
+      }).finally(() => {
+        activeFlush = null;
+      });
+      return activeFlush;
+    },
+    close() {
+      if (closePromise)
+        return closePromise;
+      closed = true;
+      clearInterval(timer);
+      closePromise = (async () => {
+        if (activeFlush)
+          await activeFlush;
+        for (let pass = 0;pass < AGENT_TELEMETRY_CLOSE_DRAIN_PASSES && hasPending(); pass += 1)
+          await api.flush();
+      })();
+      return closePromise;
+    }
+  };
+  const timer = setInterval(() => void api.flush(), config.flushIntervalMs);
+  timer.unref?.();
+  return api;
+}
+
+// src/telemetry-runtime.ts
+class AgentTelemetryRuntime {
+  telemetry;
+  now;
+  active = 0;
+  completed = 0;
+  failed = 0;
+  draining = false;
+  constructor(telemetry, now = Date.now) {
+    this.telemetry = telemetry;
+    this.now = now;
+  }
+  event(event) {
+    this.telemetry.recordEvent(event);
+  }
+  setDraining(draining) {
+    this.draining = draining;
+    this.recordState();
+  }
+  async observe(operation, work, outcome = () => "success", errorOutcome = () => "failed") {
+    const startedAtMs = this.now();
+    this.active += 1;
+    this.recordState();
+    let observedOutcome;
+    try {
+      const value = await work();
+      observedOutcome = outcome(value);
+      return value;
+    } catch (cause) {
+      observedOutcome = errorOutcome(cause);
+      throw cause;
+    } finally {
+      this.active -= 1;
+      this.completed += 1;
+      if (observedOutcome !== "success" && observedOutcome !== "idle")
+        this.failed += 1;
+      this.telemetry.recordOperation({
+        operation,
+        outcome: observedOutcome,
+        startedAtMs,
+        durationMs: Math.max(0, this.now() - startedAtMs)
+      });
+      this.recordState();
+    }
+  }
+  close() {
+    return this.telemetry.close();
+  }
+  recordState() {
+    this.telemetry.recordState({
+      active: this.active,
+      completed: this.completed,
+      failed: this.failed,
+      draining: this.draining
+    });
+  }
+}
+
 // src/index.ts
 function loadOrCreateSeed(path) {
   if (existsSync13(path)) {
@@ -8480,6 +9896,13 @@ function loadOrCreateSeed(path) {
 var DEFAULT_SOCKET_PATH = DEFAULT_SOCKET;
 var DEFAULT_SEED_PATH = "/var/lib/forgezero/node.seed";
 var DEFAULT_SEED_CREDENTIAL = "agent-seed";
+function configuredAgentSeed(options) {
+  if (options.credential)
+    return loadSeedCredential(options.credential);
+  if (options.allowFileSeed)
+    return loadOrCreateSeed(options.path ?? DEFAULT_SEED_PATH);
+  throw new Error("agent: a systemd seed credential is required; file-backed seeds are development-only and require FZ_ALLOW_FILE_SEED=1.");
+}
 var DEFAULT_ENROLMENT_STATE_PATH = "/var/lib/forgezero/enrolment.json";
 function systemdListenFd(environment = process.env, pid = process.pid) {
   if (!environment.LISTEN_FDS && !environment.LISTEN_PID)
@@ -8531,7 +9954,11 @@ function createSystemdDeploymentSecrets(names, directory = process.env.CREDENTIA
   };
 }
 function runAgent(config = {}) {
-  const seed = config.seed ?? (config.seedCredential ? loadSeedCredential(config.seedCredential) : loadOrCreateSeed(config.seedPath ?? DEFAULT_SEED_PATH));
+  const seed = config.seed ?? configuredAgentSeed({
+    credential: config.seedCredential,
+    path: config.seedPath,
+    allowFileSeed: config.allowFileSeed
+  });
   const keys = deriveKeysFromSeed(seed);
   const nodeKey = config.nodeKey ?? keys.ed25519.publicKey;
   const options = {
@@ -8567,11 +9994,13 @@ if (import.meta.main) {
       "  FZ_SOCKET_PATH   where to listen        (default: " + DEFAULT_SOCKET_PATH + ")",
       "  FZ_SEED_CREDENTIAL systemd credential   (production: agent-seed)",
       "  FZ_SEED_PATH       legacy/dev seed file (default: " + DEFAULT_SEED_PATH + ")",
+      "  FZ_ALLOW_FILE_SEED=1 permits that development-only file fallback",
       "  FZ_NODE_KEY      override the node key  (default: derived from the seed)",
       "",
       "  deploy [--revision=<full-sha>] [--release-executor]",
       "  identity            print this sealed seed's public identity",
       "  enrol               consume a systemd-loaded compute capability",
+      "  egress-policy --user=<service-user> [explicit loopback/public TCP grants]",
       "  metal-helper --profile=/etc/forgezero/metal.json",
       "  status | pause | resume",
       "  pause-key|resume-key|stop-key|start-key --key=<key>",
@@ -8590,8 +10019,13 @@ if (import.meta.main) {
     process.exit(0);
   }
   const command2 = args.find((arg) => !arg.startsWith("-"));
+  const allowFileSeed = process.env.FZ_ALLOW_FILE_SEED === "1";
   if (command2 === "identity") {
-    const seed = process.env.FZ_SEED_CREDENTIAL ? loadSeedCredential(process.env.FZ_SEED_CREDENTIAL) : loadOrCreateSeed(process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH);
+    const seed = configuredAgentSeed({
+      credential: process.env.FZ_SEED_CREDENTIAL,
+      path: process.env.FZ_SEED_PATH,
+      allowFileSeed
+    });
     const keys2 = deriveKeysFromSeed(seed);
     console.log(JSON.stringify({
       nodeKey: keys2.ed25519.publicKey,
@@ -8605,7 +10039,11 @@ if (import.meta.main) {
     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 seed = configuredAgentSeed({
+      credential: process.env.FZ_SEED_CREDENTIAL,
+      path: process.env.FZ_SEED_PATH,
+      allowFileSeed
+    });
     const keys2 = deriveKeysFromSeed(seed);
     const nodeKey2 = process.env.FZ_NODE_KEY ?? keys2.ed25519.publicKey;
     const binding2 = await enrolGuestIdentity({
@@ -8622,6 +10060,29 @@ if (import.meta.main) {
     console.log(`[agent] enrolled ${binding2.computeReference} in project ${binding2.projectKey}/${binding2.environmentKey}`);
     process.exit(0);
   }
+  if (command2 === "egress-policy") {
+    const users = args.filter((arg) => arg.startsWith("--user=")).map((arg) => arg.slice("--user=".length));
+    if (users.length < 1)
+      throw new Error("egress-policy requires --user=<service-user>");
+    const loopbackUser = args.find((arg) => arg.startsWith("--loopback-user="))?.slice("--loopback-user=".length);
+    const parsePorts = (prefix) => args.filter((arg) => arg.startsWith(prefix)).map((arg) => Number(arg.slice(prefix.length)));
+    const loopbackTcpPorts = parsePorts("--loopback-tcp-port=");
+    const publicTcpPorts = parsePorts("--public-tcp-port=");
+    if (!loopbackUser && (loopbackTcpPorts.length > 0 || publicTcpPorts.length > 0)) {
+      throw new Error("egress-policy port grants require --loopback-user=<service-user>");
+    }
+    if (loopbackUser && loopbackTcpPorts.length < 1 && publicTcpPorts.length < 1) {
+      throw new Error("egress-policy restricted user requires an explicit TCP port grant");
+    }
+    await superviseAgentEgressPolicy({
+      users,
+      loopback: loopbackUser ? {
+        user: loopbackUser,
+        tcpPorts: loopbackTcpPorts,
+        publicTcpPorts: publicTcpPorts.length > 0 ? publicTcpPorts : undefined
+      } : undefined
+    });
+  }
   if (command2 === "metal-helper") {
     const profilePath = args.find((arg) => arg.startsWith("--profile="))?.slice("--profile=".length);
     if (!profilePath)
@@ -8805,13 +10266,21 @@ if (import.meta.main) {
       throw new Error("metal agent requires FZ_API");
     if (!process.env.FZ_METAL_HOSTNAME)
       throw new Error("metal agent requires FZ_METAL_HOSTNAME");
-    const seed = process.env.FZ_SEED_CREDENTIAL ? loadSeedCredential(process.env.FZ_SEED_CREDENTIAL) : loadOrCreateSeed(process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH);
+    const telemetry2 = new AgentTelemetryRuntime(createAgentTelemetry(resolveAgentTelemetryConfig()));
+    telemetry2.event("agent.started");
+    telemetry2.setDraining(false);
+    const seed = configuredAgentSeed({
+      credential: process.env.FZ_SEED_CREDENTIAL,
+      path: process.env.FZ_SEED_PATH,
+      allowFileSeed
+    });
     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,
+      telemetry: telemetry2,
       metalHostname: process.env.FZ_METAL_HOSTNAME,
       run: (claim) => requestMetalProvision(claim, process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET),
       metalPreflight: () => ({
@@ -8826,6 +10295,7 @@ if (import.meta.main) {
       apiUrl: process.env.FZ_API,
       nodeKey: nodeKey2,
       keys: keys2,
+      telemetry: telemetry2,
       mode: process.env.FZ_AGENT_MODE === "attested" ? "attested" : "enrolled",
       updateTarget: "metal",
       async prepareUpdate() {
@@ -8834,13 +10304,18 @@ if (import.meta.main) {
         updatePrepared = true;
         try {
           await pull.stop();
+          telemetry2.event("agent.update_prepared");
         } catch (cause) {
           updatePrepared = false;
           throw cause;
         }
       },
-      recoverUpdate(cause) {
+      async recoverUpdate(cause) {
         console.error("[metal-agent] update staging failed after drain; restarting current release", cause);
+        telemetry2.event("agent.update_recovered");
+        telemetry2.setDraining(true);
+        telemetry2.event("agent.stopped");
+        await settleWithin(telemetry2.close(), Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 120000)));
         process.exit(1);
       },
       onEvent: (event, detail) => console.log(`[metal-agent] ${event}${detail ? ` ${detail instanceof Error ? detail.message : JSON.stringify(detail)}` : ""}`)
@@ -8851,13 +10326,16 @@ if (import.meta.main) {
       if (stopping)
         return;
       stopping = true;
-      const deadline = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 120000));
-      const drained = await Promise.race([
-        Promise.all([pull.stop(), heartbeat.stop()]).then(() => true),
-        new Promise((resolve4) => setTimeout(() => resolve4(false), deadline))
-      ]);
+      telemetry2.setDraining(true);
+      telemetry2.event("agent.draining");
+      const deadlineMs = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 120000));
+      const deadline = Date.now() + deadlineMs;
+      const remaining = () => Math.max(1, deadline - Date.now());
+      const drained = await settleWithin(Promise.all([pull.stop(), heartbeat.stop()]), remaining());
+      telemetry2.event("agent.stopped");
+      const telemetryClosed = await settleWithin(telemetry2.close(), remaining());
       console.log(`[metal-agent] ${signal}: ${drained ? "drained" : "deadline reached; claim left fenced for recovery"}`);
-      process.exit(drained ? 0 : 1);
+      process.exit(drained && telemetryClosed ? 0 : 1);
     };
     process.on("SIGTERM", () => void stop("SIGTERM"));
     process.on("SIGINT", () => void stop("SIGINT"));
@@ -8888,11 +10366,15 @@ if (import.meta.main) {
       process.exit(1);
     }
   }
+  const telemetry = new AgentTelemetryRuntime(createAgentTelemetry(resolveAgentTelemetryConfig()));
+  telemetry.event("agent.started");
+  telemetry.setDraining(false);
   const attestationSource = existsSync13("/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,
+    allowFileSeed,
     nodeKey: process.env.FZ_NODE_KEY,
     attestation: attestationSource,
     record: (entry) => console.log(`[agent] ${entry.op} ${entry.outcome}${entry.detail ? ` ${entry.detail}` : ""}`)
@@ -8923,7 +10405,12 @@ if (import.meta.main) {
   let secretCache;
   let vaultSync;
   if (binding && attestationSource && nodeApiUrl) {
-    const result = await attestNodeOnce({ apiUrl: nodeApiUrl, nodeKey, keys, source: attestationSource });
+    const result = await telemetry.observe("attestation.refresh", () => attestNodeOnce({
+      apiUrl: nodeApiUrl,
+      nodeKey,
+      keys,
+      source: attestationSource
+    }));
     console.log(`[agent] initial SEV-SNP attestation verified ${result.measurement.slice(0, 16)}\u2026`);
   }
   if (binding?.realm === "tenant" && nodeApiUrl) {
@@ -8933,12 +10420,13 @@ if (import.meta.main) {
       keys,
       projectKey: binding.projectKey
     });
-    const loaded = await secretCache.load();
+    const loaded = await telemetry.observe("vault.sync", () => secretCache.load(), (result) => result.failed.length > 0 ? "failed" : "success");
     if (loaded.failed.length > 0) {
       throw new Error(`agent: failed to load ${loaded.failed.length} assigned vault entries`);
     }
     running.setVault(secretCache, binding.projectKey);
     vaultSync = startNodeVaultSync(secretCache, {
+      telemetry,
       onEvent: (event, detail) => console.log(`[agent] vault ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
     });
     console.log(`[agent] in-memory vault loaded for every environment in project ${binding.projectKey}`);
@@ -8947,6 +10435,7 @@ if (import.meta.main) {
     apiUrl: nodeApiUrl,
     nodeKey,
     keys,
+    telemetry,
     source: attestationSource,
     immediate: !binding,
     onEvent: (event, detail) => console.log(`[agent] attestation ${event}${detail ? ` ${detail instanceof Error ? detail.message : JSON.stringify(detail)}` : ""}`)
@@ -8961,6 +10450,7 @@ if (import.meta.main) {
     apiUrl: nodeApiUrl,
     nodeKey,
     keys,
+    telemetry,
     run: (claim) => requestLifecycleAction(claim, process.env.FZ_LIFECYCLE_HELPER_SOCKET ?? DEFAULT_LIFECYCLE_HELPER_SOCKET),
     onEvent: (event, detail) => console.log(`[agent] migration ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`)
   }) : undefined;
@@ -9006,6 +10496,7 @@ if (import.meta.main) {
       knownHostsPath: source.knownHosts ? join6(root, "cache", `known-hosts-${key}`) : undefined,
       knownHostsContent: source.knownHosts,
       cache: deploymentSecrets,
+      capacityEvidenceDirectory: process.env.FZ_CAPACITY_EVIDENCE_DIR ?? join6(root, "cache", "capacity"),
       ensureSoftware: (requirements) => requestSoftware(requirements, process.env.FZ_SOFTWARE_HELPER_SOCKET ?? DEFAULT_SOFTWARE_HELPER_SOCKET),
       projectExec: process.env.FZ_DEPLOY_RUNNER_SOCKET ? (input) => requestDeploymentCommand(input, process.env.FZ_DEPLOY_RUNNER_SOCKET) : undefined
     });
@@ -9019,6 +10510,7 @@ if (import.meta.main) {
       apiUrl: nodeApiUrl,
       nodeKey,
       keys,
+      telemetry,
       manager: staticManager,
       managerFor: staticManager ? undefined : (claim) => {
         const cacheKey = [
@@ -9044,6 +10536,7 @@ if (import.meta.main) {
       apiUrl: nodeApiUrl,
       nodeKey,
       keys,
+      telemetry,
       mode: process.env.FZ_AGENT_MODE === "attested" ? "attested" : "enrolled",
       async prepareUpdate() {
         if (updatePrepared)
@@ -9058,13 +10551,18 @@ if (import.meta.main) {
           if (reports.some(({ timedOut }) => timedOut)) {
             throw new Error("Agent update deferred because deployment drain reached its deadline.");
           }
+          telemetry.event("agent.update_prepared");
         } catch (cause) {
           updatePrepared = false;
           throw cause;
         }
       },
-      recoverUpdate(cause) {
+      async recoverUpdate(cause) {
         console.error("[agent] update staging failed after drain; restarting current release", cause);
+        telemetry.event("agent.update_recovered");
+        telemetry.setDraining(true);
+        telemetry.event("agent.stopped");
+        await settleWithin(telemetry.close(), Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 30000)));
         process.exit(1);
       },
       onEvent: (event, detail) => console.log(`[agent] ${event}${detail ? ` ${detail instanceof Error ? detail.message : JSON.stringify(detail)}` : ""}`)
@@ -9074,6 +10572,8 @@ if (import.meta.main) {
       if (stopping)
         return;
       stopping = true;
+      telemetry.setDraining(true);
+      telemetry.event("agent.draining");
       console.log(`[agent] ${signal}: stopping deployment intake and draining`);
       const deadlineMs = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 30000));
       const deadline = Date.now() + deadlineMs;
@@ -9088,6 +10588,8 @@ if (import.meta.main) {
       const backgroundDrained = await settleWithin(Promise.all([vaultDrain, attestationDrain, migrationDrain, heartbeatDrain]), remaining());
       const managerReports = await Promise.all([...new Set(managers.values())].map((manager) => manager.stop(remaining())));
       const socketClosed = await closeServerWithin(server, remaining());
+      telemetry.event("agent.stopped");
+      const telemetryClosed = await settleWithin(telemetry.close(), remaining());
       const timedOut = managerReports.some((report) => report.timedOut);
       console.log(`[agent] drain ${JSON.stringify({
         managers: managerReports,
@@ -9096,7 +10598,7 @@ if (import.meta.main) {
         backgroundDrained,
         socketClosed
       })}`);
-      process.exit(timedOut || !controlClosed || !pullDrained || !backgroundDrained || !socketClosed ? 1 : 0);
+      process.exit(timedOut || !controlClosed || !pullDrained || !backgroundDrained || !socketClosed || !telemetryClosed ? 1 : 0);
     };
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
     process.on("SIGINT", () => void shutdown("SIGINT"));
@@ -9107,6 +10609,7 @@ if (import.meta.main) {
       apiUrl: nodeApiUrl,
       nodeKey,
       keys,
+      telemetry,
       mode: process.env.FZ_AGENT_MODE === "attested" ? "attested" : "enrolled",
       async prepareUpdate() {
         if (updatePrepared)
@@ -9114,49 +10617,59 @@ if (import.meta.main) {
         updatePrepared = true;
         try {
           await migrationPull?.stop();
+          telemetry.event("agent.update_prepared");
         } catch (cause) {
           updatePrepared = false;
           throw cause;
         }
       },
-      recoverUpdate(cause) {
+      async recoverUpdate(cause) {
         console.error("[agent] update staging failed after drain; restarting current release", cause);
+        telemetry.event("agent.update_recovered");
+        telemetry.setDraining(true);
+        telemetry.event("agent.stopped");
+        await settleWithin(telemetry.close(), Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 30000)));
         process.exit(1);
       },
       onEvent: (event, detail) => console.log(`[agent] ${event}${detail ? ` ${detail instanceof Error ? detail.message : JSON.stringify(detail)}` : ""}`)
     }) : undefined;
-    if (vaultSync || attestationLoop || migrationPull || heartbeat) {
-      let stopping = false;
-      const stop = async (signal) => {
-        if (stopping)
-          return;
-        stopping = true;
-        const deadlineMs = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 30000));
-        const deadline = Date.now() + deadlineMs;
-        const remaining = () => Math.max(1, deadline - Date.now());
-        console.log(`[agent] ${signal}: stopping background intake and draining`);
-        const backgroundDrained = await settleWithin(Promise.all([
-          vaultSync?.stop() ?? Promise.resolve(),
-          attestationLoop?.stop() ?? Promise.resolve(),
-          migrationPull?.stop() ?? Promise.resolve(),
-          heartbeat?.stop() ?? Promise.resolve()
-        ]), remaining());
-        const socketClosed = await closeServerWithin(server, remaining());
-        console.log(`[agent] drain ${JSON.stringify({ backgroundDrained, socketClosed })}`);
-        process.exit(backgroundDrained && socketClosed ? 0 : 1);
-      };
-      process.on("SIGTERM", () => void stop("SIGTERM"));
-      process.on("SIGINT", () => void stop("SIGINT"));
-    }
+    let stopping = false;
+    const stop = async (signal) => {
+      if (stopping)
+        return;
+      stopping = true;
+      telemetry.setDraining(true);
+      telemetry.event("agent.draining");
+      const deadlineMs = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 30000));
+      const deadline = Date.now() + deadlineMs;
+      const remaining = () => Math.max(1, deadline - Date.now());
+      console.log(`[agent] ${signal}: stopping background intake and draining`);
+      const backgroundDrained = await settleWithin(Promise.all([
+        vaultSync?.stop() ?? Promise.resolve(),
+        attestationLoop?.stop() ?? Promise.resolve(),
+        migrationPull?.stop() ?? Promise.resolve(),
+        heartbeat?.stop() ?? Promise.resolve()
+      ]), remaining());
+      const socketClosed = await closeServerWithin(server, remaining());
+      telemetry.event("agent.stopped");
+      const telemetryClosed = await settleWithin(telemetry.close(), remaining());
+      console.log(`[agent] drain ${JSON.stringify({ backgroundDrained, socketClosed, telemetryClosed })}`);
+      process.exit(backgroundDrained && socketClosed && telemetryClosed ? 0 : 1);
+    };
+    process.on("SIGTERM", () => void stop("SIGTERM"));
+    process.on("SIGINT", () => void stop("SIGINT"));
   }
 }
 export {
+  verifyAgentEgressPolicy,
   validateSoftwareRequirements,
   validateMetalProfile,
   validateLifecycleProfile,
   validateAgentRelease,
   tenantNodeApiUrl,
   systemdListenFd,
+  systemdAgentEgressDirectives,
+  superviseAgentEgressPolicy,
   startSoftwareHelper,
   startProvisioningPull,
   startNodeVaultSync,
@@ -9174,6 +10687,7 @@ export {
   selectAgentRelease,
   runAgent,
   restoreAgentRelease,
+  resolveAgentTelemetryConfig,
   requestSoftware,
   requestMetalProvision,
   requestLifecycleAction,
@@ -9181,6 +10695,7 @@ export {
   requestControl,
   requestAgentUpdate,
   renderWarpMdm,
+  renderAgentEgressNft,
   removeMetalGuest,
   recoverInterruptedAgentUpdate,
   readAgentUpdateReceipt,
@@ -9193,9 +10708,11 @@ export {
   probeAgentSocket,
   observeSoftwareHost,
   observeAgentHost,
+  normalizeEgressTcpPorts,
   metalHousekeepingDropIn,
   metalGuestSliceUnit,
   materializeWarpMdm,
+  localCalibrationEndpoint,
   loadTextCredential,
   loadSeedCredential,
   loadOrCreateSeed,
@@ -9213,15 +10730,21 @@ export {
   createSecretCache,
   createNodeVaultCache,
   createDeploymentManager,
+  createAgentTelemetry,
+  configuredAgentSeed,
   compareVersions,
   cloudInit,
+  calibrateHttpConcurrency,
   attestNodeOnce,
   assertSupportedGuestImage,
   applyMetalIsolation,
+  applyAgentEgressPolicy,
   allocateCpuPool,
   allocateAddress,
   activateAgentRelease,
   VERSION3 as VERSION,
+  SYSTEMD_RESOLVED_STUB,
+  SYSTEMD_RESOLVED_ADDRESS,
   SUPPORTED_GUEST_IMAGE,
   SOFTWARE_HELPER_UNIT_PATH,
   SOFTWARE_HELPER_GROUP,
@@ -9241,8 +10764,14 @@ export {
   DEFAULT_AGENT_UPDATE_SOCKET,
   DEFAULT_AGENT_RELEASE_ROOT,
   CacheError,
+  BLOCKED_IPV6,
+  BLOCKED_IPV4,
   AGENT_UPDATE_RECEIPT,
   AGENT_UPDATE_JOURNAL,
   AGENT_UPDATE_HELPER_UNIT_PATH,
-  AGENT_UPDATE_GROUP
+  AGENT_UPDATE_GROUP,
+  AGENT_TELEMETRY_OUTCOMES,
+  AGENT_TELEMETRY_OPERATIONS,
+  AGENT_TELEMETRY_EVENTS,
+  AGENT_EGRESS_TABLE
 };