@forgezero/agent 0.1.32 → 0.1.34

package/dist/provision.js

@@ -229,6 +229,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_BYTES = 8 * 1024;
 var COMPUTE_HELPER_UNITS = [
+  "forgezero-agent-egress.service",
   "forgezero-deploy-runner.service",
   "forgezero-lifecycle-helper.service",
   "forgezero-software-helper.service"
@@ -883,9 +884,71 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.32";
+var VERSION3 = "0.1.34";
+
+// src/egress-policy.ts
+import { realpathSync } from "node:fs";
+var AGENT_EGRESS_TABLE = "forgezero_agent_egress";
+var SYSTEMD_RESOLVED_ADDRESS = "127.0.0.53";
+var BLOCKED_IPV4 = [
+  "0.0.0.0/8",
+  "10.0.0.0/8",
+  "100.64.0.0/10",
+  "127.0.0.0/8",
+  "168.63.129.16/32",
+  "169.254.0.0/16",
+  "172.16.0.0/12",
+  "192.0.0.0/24",
+  "192.0.2.0/24",
+  "192.88.99.0/24",
+  "192.168.0.0/16",
+  "198.18.0.0/15",
+  "198.51.100.0/24",
+  "203.0.113.0/24",
+  "224.0.0.0/4",
+  "240.0.0.0/4"
+];
+var BLOCKED_IPV6 = [
+  "::/128",
+  "::1/128",
+  "::ffff:0:0/96",
+  "64:ff9b::/96",
+  "64:ff9b:1::/48",
+  "100::/64",
+  "fc00::/7",
+  "fec0::/10",
+  "fe80::/10",
+  "ff00::/8",
+  "2001::/32",
+  "2001:2::/48",
+  "2001:10::/28",
+  "2001:20::/28",
+  "2001:db8::/32",
+  "2002::/16",
+  "3fff::/20"
+];
+var normalizeEgressTcpPorts = (ports) => {
+  for (const port of ports) {
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+      throw new Error("Agent egress policy refuses an invalid loopback TCP port.");
+    }
+  }
+  return [...new Set(ports)].sort((left, right) => left - right);
+};
+function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
+  const ports = normalizeEgressTcpPorts(loopbackTcpPorts);
+  return [
+    "RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6",
+    `IPAddressAllow=${SYSTEMD_RESOLVED_ADDRESS}/32`,
+    ...ports.length > 0 ? ["IPAddressAllow=127.0.0.1/32", "IPAddressAllow=::1/128"] : [],
+    ...BLOCKED_IPV4.map((network) => `IPAddressDeny=${network}`),
+    ...BLOCKED_IPV6.map((network) => `IPAddressDeny=${network}`)
+  ].join(`
+`);
+}
 
 // src/provision.ts
+import { isIP } from "node:net";
 function atLeast(version, floor) {
   const parse = (value) => (value.trim().replace(/^v/, "").match(/\d+/g) ?? []).slice(0, 3).map(Number);
   const got = parse(version);
@@ -939,6 +1002,63 @@ var LIFECYCLE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-lifecycle-helper
 var LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
 var WARP_CONFIG_UNIT_PATH = "/etc/systemd/system/forgezero-warp-config.service";
 var WARP_SERVICE_DROP_IN_PATH = "/etc/systemd/system/warp-svc.service.d/forgezero.conf";
+var AGENT_EGRESS_UNIT_PATH = "/etc/systemd/system/forgezero-agent-egress.service";
+var DEFAULT_RUNNER_PUBLIC_TCP_PORTS = [443];
+function agentEgressUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  const user = options.user ?? "forgezero";
+  if (!/^[a-z_][a-z0-9_-]{0,30}$/.test(user))
+    throw new Error("invalid Agent service user");
+  const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const runnerLoopbackPorts = normalizeEgressTcpPorts(options.runnerLoopbackPorts ?? []);
+  const runnerPublicTcpPorts = normalizeEgressTcpPorts(options.runnerPublicTcpPorts ?? DEFAULT_RUNNER_PUBLIC_TCP_PORTS);
+  if (deploymentEnabled && runnerPublicTcpPorts.length < 1) {
+    throw new Error("deployed project runner needs at least one vetted public TCP port");
+  }
+  if (deploymentEnabled)
+    systemdAgentEgressDirectives(runnerLoopbackPorts);
+  const users = [user, ...deploymentEnabled ? [DEPLOYMENT_RUNNER_USER] : []];
+  const runnerGrant = deploymentEnabled ? ` --loopback-user=${DEPLOYMENT_RUNNER_USER}` + runnerLoopbackPorts.map((port) => ` --loopback-tcp-port=${port}`).join("") + runnerPublicTcpPorts.map((port) => ` --public-tcp-port=${port}`).join("") : "";
+  const policyProofs = deploymentEnabled ? [
+    ...runnerLoopbackPorts.length > 0 ? [`loopback=.*:${runnerLoopbackPorts.join(",")}`] : [],
+    `public-tcp=${runnerPublicTcpPorts.join(",")}`
+  ].map((pattern) => `ExecStartPost=/bin/sh -c '/usr/sbin/nft --numeric list table inet ${AGENT_EGRESS_TABLE} | /usr/bin/grep -q "${pattern}"'`).join(`
+`) : "";
+  return `[Unit]
+Description=ForgeZero Agent host egress policy
+Documentation=https://www.forgezero.net/docs/agent
+After=systemd-resolved.service nftables.service
+Requires=systemd-resolved.service
+Before=forgezero-agent-enrol.service forgezero-agent.service
+
+[Service]
+Type=notify
+NotifyAccess=all
+User=root
+Group=root
+ExecStart=${bin} egress-policy ${users.map((name) => `--user=${name}`).join(" ")}${runnerGrant}
+${policyProofs}
+Restart=on-failure
+RestartSec=2
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+CapabilityBoundingSet=CAP_NET_ADMIN
+RestrictAddressFamilies=AF_UNIX AF_NETLINK
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
 function softwareHelperUnit(options) {
   const bin = options.binPath ?? "fz-agent";
   return `[Unit]
@@ -1183,11 +1303,16 @@ function agentEnrolmentUnit(options) {
 ` : ""
   ].join("");
   const stateDir = options.enrolStatePath.replace(/\/[^/]+$/, "");
+  const egressDependency = options.enforceEgress ? `After=forgezero-agent-egress.service
+Requires=forgezero-agent-egress.service
+BindsTo=forgezero-agent-egress.service
+` : "";
+  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives() : "";
   return `[Unit]
 Description=Bind this machine to its ForgeZero compute
 After=network-online.target
 Wants=network-online.target
-Before=forgezero-agent.service
+${egressDependency}Before=forgezero-agent.service
 ConditionPathExists=!${options.enrolStatePath}
 
 [Service]
@@ -1210,6 +1335,7 @@ ProtectSystem=strict
 ProtectHome=true
 ReadWritePaths=${stateDir}
 LimitCORE=0
+${egressDirectives}
 
 [Install]
 WantedBy=multi-user.target
@@ -1219,9 +1345,15 @@ function deploymentRunnerUnit(options) {
   const bin = options.binPath ?? "fz-agent";
   const root = options.deployRoot ?? "/opt/forgezero";
   const agentUser = options.user ?? "forgezero-agent";
+  const egressDependency = options.enforceEgress ? `After=forgezero-agent-egress.service
+Requires=forgezero-agent-egress.service
+BindsTo=forgezero-agent-egress.service
+` : "";
+  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives(options.runnerLoopbackPorts ?? []) : "";
   return `[Unit]
 Description=ForgeZero credential-free project command runner
 Documentation=https://www.forgezero.net/docs/agent
+${egressDependency}
 
 [Service]
 Type=notify
@@ -1252,6 +1384,7 @@ ProtectControlGroups=true
 RestrictRealtime=true
 MemoryDenyWriteExecute=true
 LockPersonality=true
+${egressDirectives}
 ReadWritePaths=${root}/releases ${root}/runner-home
 
 [Install]
@@ -1261,6 +1394,21 @@ WantedBy=multi-user.target
 function agentUnit(options) {
   if (!validNodeHostname(options.nodeHostname))
     throw new Error("node hostname is invalid");
+  if (!options.telemetryEndpoint) {
+    throw new Error("compute Agent provisioning requires OTEL_EXPORTER_OTLP_ENDPOINT as an explicit public HTTPS collector coordinate");
+  }
+  let telemetryEndpoint;
+  {
+    let endpoint;
+    try {
+      endpoint = new URL(options.telemetryEndpoint);
+    } catch {
+      throw new Error("compute telemetry endpoint must be an absolute public HTTPS URL");
+    }
+    if (endpoint.protocol !== "https:" || endpoint.username || endpoint.password || endpoint.search || endpoint.hash || isIP(endpoint.hostname) !== 0 || !endpoint.hostname.includes(".") || endpoint.hostname === "localhost" || endpoint.hostname.endsWith(".local"))
+      throw new Error("compute telemetry endpoint must be an absolute public HTTPS URL without credentials, query or fragment");
+    telemetryEndpoint = endpoint.toString().replace(/\/$/, "");
+  }
   const bin = options.binPath ?? "fz-agent";
   const user = options.user ?? "forgezero";
   const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
@@ -1309,6 +1457,7 @@ function agentUnit(options) {
     }
   }
   const environment = [
+    "NODE_ENV=production",
     `FZ_SOCKET_PATH=${agentBackendSocketPath(options.socketPath)}`,
     `FZ_CONTROL_SOCKET=${controlSocketPath}`,
     `FZ_SEED_CREDENTIAL=agent-seed`,
@@ -1319,12 +1468,15 @@ function agentUnit(options) {
     options.enrolStatePath ? `FZ_ENROL_STATE_FILE=${options.enrolStatePath}` : null,
     options.nodeLabel ? `FZ_NODE_LABEL=${options.nodeLabel}` : null,
     options.nodeHostname ? `FZ_NODE_HOSTNAME=${options.nodeHostname}` : null,
+    `OTEL_EXPORTER_OTLP_ENDPOINT=${telemetryEndpoint}`,
+    "OTEL_SERVICE_NAME=forgezero-agent",
     options.gitPublicKeyPath ? `FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}` : null,
     options.repository ? `FZ_DEPLOY_REPO=${options.repository}` : null,
     options.branch ? `FZ_DEPLOY_BRANCH=${options.branch}` : null,
     options.profile ? `FZ_DEPLOY_PROFILE=${options.profile}` : null,
     options.repository && options.branch ? `FZ_DEPLOY_KEY=${options.project ?? "platform"}:${options.environment ?? "production"}` : null,
     deploymentEnabled ? `FZ_DEPLOY_ROOT=${deployRoot}` : null,
+    deploymentEnabled ? `FZ_CAPACITY_EVIDENCE_DIR=${deployRoot}/capacity` : null,
     deploymentEnabled ? `FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}` : null,
     deploymentEnabled ? `FZ_SOFTWARE_HELPER_SOCKET=${DEFAULT_SOFTWARE_HELPER_SOCKET}` : null,
     Object.keys(deploymentCredentials).length > 0 ? `FZ_DEPLOY_SYSTEMD_SECRETS=${Object.keys(deploymentCredentials).join(",")}` : null,
@@ -1343,7 +1495,7 @@ function agentUnit(options) {
 ` : "";
   const projectCredentials = Object.entries(deploymentCredentials).map(([name, path]) => `LoadCredentialEncrypted=${name}:${path}`).join(`
 `);
-  const deploymentWrites = deploymentEnabled ? `ReadWritePaths=${deployRoot}/releases ${deployRoot}/agent-home ${deployRoot}/cache` : "";
+  const deploymentWrites = deploymentEnabled ? `ReadWritePaths=${deployRoot}/releases ${deployRoot}/agent-home ${deployRoot}/cache ${deployRoot}/capacity` : "";
   const supplementaryGroups = [
     AGENT_UPDATE_GROUP,
     deploymentEnabled ? DEPLOYMENT_GROUP : null,
@@ -1354,6 +1506,7 @@ function agentUnit(options) {
   const after = [
     "network-online.target",
     "forgezero-agent-update-helper.service",
+    options.enforceEgress ? "forgezero-agent-egress.service" : null,
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
     deploymentEnabled ? "forgezero-software-helper.service" : null,
     lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
@@ -1362,6 +1515,7 @@ function agentUnit(options) {
   ].filter((value) => value !== null);
   const requires = [
     "forgezero-agent-update-helper.service",
+    options.enforceEgress ? "forgezero-agent-egress.service" : null,
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
     deploymentEnabled ? "forgezero-software-helper.service" : null,
     lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
@@ -1371,7 +1525,8 @@ function agentUnit(options) {
   const deploymentDependency = [
     `After=${after.join(" ")}`,
     "Wants=network-online.target",
-    requires.length > 0 ? `Requires=${requires.join(" ")}` : null
+    requires.length > 0 ? `Requires=${requires.join(" ")}` : null,
+    options.enforceEgress ? "BindsTo=forgezero-agent-egress.service" : null
   ].filter((value) => value !== null).join(`
 `);
   const snpDevice = options.mode === "attested" ? `DevicePolicy=closed
@@ -1379,6 +1534,7 @@ DeviceAllow=/dev/sev-guest rw` : "";
   const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${VAULT_GROUP} /dev/sev-guest
 ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
 ` : "";
+  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives() : "";
   return `[Unit]
 Description=ForgeZero node agent (${options.mode})
 Documentation=https://www.forgezero.net/docs/agent
@@ -1423,6 +1579,7 @@ RestrictSUIDSGID=true
 RestrictRealtime=true
 MemoryDenyWriteExecute=true
 LockPersonality=true
+${egressDirectives}
 ${snpDevice}
 ${deploymentWrites}
 
@@ -1438,6 +1595,8 @@ function planProvision(options) {
   const credentialDir = seedCredentialPath.replace(/\/[^/]+$/, "");
   const deployRoot = options.deployRoot ?? "/opt/forgezero";
   const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const runnerLoopbackPorts = normalizeEgressTcpPorts(options.runnerLoopbackPorts ?? []);
+  const runnerPublicTcpPorts = normalizeEgressTcpPorts(options.runnerPublicTcpPorts ?? DEFAULT_RUNNER_PUBLIC_TCP_PORTS);
   const lifecycleEnabled = Boolean(options.pullMigrations && options.lifecycleProfilePath);
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
@@ -1478,6 +1637,9 @@ function planProvision(options) {
       { path: AGENT_SOCKET_UNIT_PATH, unit: agentSocketUnit(options) },
       { path: AGENT_SOCKET_PROXY_UNIT_PATH, unit: agentSocketProxyUnit(options) },
       { path: AGENT_UPDATE_HELPER_UNIT_PATH, unit: agentUpdateHelperUnit(options) },
+      ...options.enforceEgress ? [
+        { path: AGENT_EGRESS_UNIT_PATH, unit: agentEgressUnit(options) }
+      ] : [],
       ...deploymentEnabled ? [
         { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) },
         { path: SOFTWARE_HELPER_UNIT_PATH, unit: softwareHelperUnit(options) }
@@ -1504,6 +1666,10 @@ function planProvision(options) {
     socketPath: options.socketPath,
     user,
     steps: [
+      ...options.enforceEgress ? [{
+        label: "Ubuntu Agent egress prerequisites",
+        command: `. /etc/os-release; test "$ID" = ubuntu; ` + `DEBIAN_FRONTEND=noninteractive apt-get update -qq; ` + `DEBIAN_FRONTEND=noninteractive apt-get install -y nftables; ` + `systemctl enable --now systemd-resolved.service; ` + `test "$(readlink -f /etc/resolv.conf)" = /run/systemd/resolve/stub-resolv.conf; ` + `test -s /run/systemd/resolve/stub-resolv.conf`
+      }] : [],
       {
         label: "vault socket access group",
         command: `groupadd --system ${VAULT_GROUP} || true`
@@ -1582,7 +1748,7 @@ function planProvision(options) {
       ] : [],
       ...deploymentEnabled ? [{
         label: "deployment directories",
-        command: `install -d -o root -g root -m 0755 ${deployRoot} && ` + `install -d -o root -g ${DEPLOYMENT_GROUP} -m 3770 ${deployRoot}/releases && ` + `install -d -o ${user} -g ${user} -m 0750 ${deployRoot}/cache && ` + `install -d -o ${user} -g ${user} -m 0700 ${deployRoot}/agent-home && ` + `install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0700 ${deployRoot}/runner-home ${deployRoot}/runner-home/cache`
+        command: `install -d -o root -g root -m 0755 ${deployRoot} && ` + `install -d -o root -g ${DEPLOYMENT_GROUP} -m 3770 ${deployRoot}/releases && ` + `install -d -o ${user} -g ${user} -m 0750 ${deployRoot}/cache && ` + `install -d -o ${user} -g ${user} -m 0700 ${deployRoot}/capacity && ` + `install -d -o ${user} -g ${user} -m 0700 ${deployRoot}/agent-home && ` + `install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0700 ${deployRoot}/runner-home ${deployRoot}/runner-home/cache`
       }] : [],
       { label: "reload units", command: "systemctl daemon-reload" },
       ...deploymentEnabled ? [{
@@ -1594,6 +1760,7 @@ function planProvision(options) {
         command: `systemctl enable ${[
           "forgezero-agent.socket",
           "forgezero-agent-update-helper.service",
+          ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
           ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
           ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
           ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
@@ -1601,6 +1768,7 @@ function planProvision(options) {
           "forgezero-agent.service"
         ].join(" ")}; systemctl reset-failed forgezero-agent.service || true; systemctl restart ${[
           "forgezero-agent-update-helper.service",
+          ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
           ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
           ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
           ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
@@ -1611,6 +1779,10 @@ function planProvision(options) {
         label: "prove the compute binding is durable",
         command: `test -s ${enrolStatePath}`
       }] : [],
+      ...options.enforceEgress ? [{
+        label: "prove the Agent egress policy is active",
+        command: "systemctl is-active forgezero-agent-egress.service && " + "nft --numeric list table inet forgezero_agent_egress | grep -q forgezero-agent-egress-v1" + (deploymentEnabled ? ` && nft --numeric list table inet forgezero_agent_egress | grep -q 'public-tcp=${runnerPublicTcpPorts.join(",")}'` + (runnerLoopbackPorts.length > 0 ? ` && nft --numeric list table inet forgezero_agent_egress | grep -Eq 'loopback=[0-9]+:${runnerLoopbackPorts.join(",")}( |")'` : "") : "")
+      }] : [],
       { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
       { label: "prove the public Vault socket exists", command: awaitSocketCommand(options.socketPath) },
       { label: "prove the Agent Vault backend exists", command: awaitSocketCommand(agentBackendSocketPath(options.socketPath)) },
@@ -1652,6 +1824,7 @@ export {
   agentSocketUnit,
   agentSocketProxyUnit,
   agentEnrolmentUnit,
+  agentEgressUnit,
   agentBackendSocketPath,
   WARP_SERVICE_DROP_IN_PATH,
   WARP_CONFIG_UNIT_PATH,
@@ -1665,7 +1838,9 @@ export {
   DEPLOYMENT_RUNNER_UNIT_PATH,
   DEPLOYMENT_RUNNER_SOCKET,
   DEPLOYMENT_GROUP,
+  DEFAULT_RUNNER_PUBLIC_TCP_PORTS,
   CAPABILITY_CHECKS,
   AGENT_SOCKET_UNIT_PATH,
-  AGENT_SOCKET_PROXY_UNIT_PATH
+  AGENT_SOCKET_PROXY_UNIT_PATH,
+  AGENT_EGRESS_UNIT_PATH
 };

package/dist/provisioning-pull.d.ts

@@ -1,5 +1,6 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import { type SignedNodeHttpOptions } from './signed-node-http';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 interface RemoteProvisionClaimBase {
     computeKey: string;
     claimToken: string;
@@ -73,6 +74,7 @@ export interface ProvisioningPullOptions extends SignedNodeHttpOptions {
         kvm: boolean;
         helper: boolean;
     };
+    telemetry?: AgentOperationTelemetry;
 }
 export type ProvisionPullResult = {
     status: 'idle';

package/dist/provisioning-pull.js

@@ -70,6 +70,7 @@ async function postSignedNode(options, path, body) {
 // src/provisioning-pull.ts
 class ProvisionClaimLostError extends Error {
 }
+var remoteOutcome = (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));
@@ -88,10 +89,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", remoteOutcome) : renew()).then((response) => {
         expires = response.claimExpiresAtTs;
         options.onEvent?.("lease-renewed", { computeKey: claim.computeKey, claimExpiresAtTs: expires });
       }).catch((cause) => {
@@ -112,7 +114,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);
@@ -143,7 +146,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", remoteOutcome) : 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.`);
     }
@@ -156,7 +160,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", remoteOutcome) : await claimWork();
   if (!response.claim)
     return { status: "idle" };
   const claim = response.claim;
@@ -167,20 +172,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", remoteOutcome);
+    } 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", remoteOutcome);
+  } else
+    await acknowledge();
   return { status: claim.action === "delete" ? "terminated" : "running", claim, result };
 }
 function startProvisioningPull(options) {

package/dist/telemetry-runtime.d.ts

@@ -0,0 +1,20 @@
+import type { AgentTelemetry, AgentTelemetryEvent, AgentTelemetryOperation, AgentTelemetryOutcome } from './telemetry';
+/**
+ * Process-wide operation/state accounting layered over the deliberately small
+ * OTLP emitter. Callers still cannot attach arbitrary attributes or payloads.
+ */
+export declare class AgentTelemetryRuntime {
+    private readonly telemetry;
+    private readonly now;
+    private active;
+    private completed;
+    private failed;
+    private draining;
+    constructor(telemetry: AgentTelemetry, now?: () => number);
+    event(event: AgentTelemetryEvent): void;
+    setDraining(draining: boolean): void;
+    observe<T>(operation: AgentTelemetryOperation, work: () => Promise<T>, outcome?: (value: T) => AgentTelemetryOutcome, errorOutcome?: (cause: unknown) => AgentTelemetryOutcome): Promise<T>;
+    close(): Promise<void>;
+    private recordState;
+}
+export type AgentOperationTelemetry = Pick<AgentTelemetryRuntime, 'observe'>;

package/dist/telemetry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Dependency-free OTLP/HTTP telemetry for the machine Agent.
+ *
+ * Callers can name only reviewed operations, outcomes and lifecycle events.
+ * There is deliberately no field for a URL, request/response body, header,
+ * credential, tenant coordinate, command, error detail or arbitrary label.
+ */
+export declare const AGENT_TELEMETRY_OPERATIONS: readonly ["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"];
+export type AgentTelemetryOperation = (typeof AGENT_TELEMETRY_OPERATIONS)[number];
+export declare const AGENT_TELEMETRY_OUTCOMES: readonly ["success", "idle", "refused", "retryable", "failed"];
+export type AgentTelemetryOutcome = (typeof AGENT_TELEMETRY_OUTCOMES)[number];
+export declare const AGENT_TELEMETRY_EVENTS: readonly ["agent.started", "agent.draining", "agent.stopped", "agent.update_prepared", "agent.update_recovered", "telemetry.queue_overflow"];
+export type AgentTelemetryEvent = (typeof AGENT_TELEMETRY_EVENTS)[number];
+export interface AgentTelemetryConfig {
+    endpoint: string;
+    serviceName: string;
+    instanceId: string;
+    environment: 'production' | 'development';
+    flushIntervalMs: number;
+    traceSampleRatio: number;
+}
+export interface AgentOperationObservation {
+    operation: AgentTelemetryOperation;
+    outcome: AgentTelemetryOutcome;
+    startedAtMs: number;
+    durationMs: number;
+}
+export interface AgentTelemetryState {
+    active: number;
+    completed: number;
+    failed: number;
+    draining: boolean;
+}
+export interface AgentTelemetry {
+    recordOperation(observation: AgentOperationObservation): void;
+    recordEvent(event: AgentTelemetryEvent): void;
+    recordState(state: AgentTelemetryState): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare const AGENT_OTLP_EXPORT_TIMEOUT_MS = 5000;
+export declare const AGENT_OTLP_MAX_ATTEMPTS = 2;
+export declare const AGENT_OTLP_MAX_RETRY_DELAY_MS = 1000;
+export declare const AGENT_TELEMETRY_MAX_SPANS = 256;
+export declare const AGENT_TELEMETRY_MAX_LOGS = 64;
+/** Resolve once at process startup; production refuses to run without an exporter. */
+export declare function resolveAgentTelemetryConfig(env?: Record<string, string | undefined>): AgentTelemetryConfig | null;
+export declare function createAgentTelemetry(input: AgentTelemetryConfig | null, options?: {
+    fetch?: FetchLike;
+    warn?: (message: string) => void;
+    now?: () => number;
+    random?: () => number;
+    wait?: (milliseconds: number) => Promise<void>;
+}): AgentTelemetry;
+export {};

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.32";
+export declare const VERSION = "0.1.34";

package/package.json

@@ -1,12 +1,11 @@
 {
-	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/agent",
-	"version": "0.1.32",
+	"version": "0.1.34",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",
 		"prebuild": "rm -rf dist",
-		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/deploy-file.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/agent-update.ts src/agent-update-helper.ts src/agent-heartbeat.ts src/software.ts src/software-helper.ts src/ubuntu.ts --root src --outdir dist --target browser --format esm --packages external && bun build src/project-context.ts --root src --outdir dist --target bun --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/deploy-file.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/agent-update.ts src/agent-update-helper.ts src/agent-heartbeat.ts src/software.ts src/software-helper.ts src/ubuntu.ts src/capacity-calibration.ts --root src --outdir dist --target browser --format esm --packages external && bun build src/project-context.ts --root src --outdir dist --target bun --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"devDependencies": {
@@ -18,19 +17,20 @@
 		"@noble/post-quantum": "^0.6.1"
 	},
 	"dependencies": {
-		"@forgezero/runtime": "^0.1.4",
-		"@forgezero/vault": "^0.1.7",
-		"@noble/curves": "^2.2.0",
-		"@noble/hashes": "^2.2.0",
-		"@noble/post-quantum": "^0.6.1",
-		"@scure/bip39": "^2.2.0"
+		"@forgezero/runtime": "0.1.5",
+		"@forgezero/vault": "0.1.8",
+		"@noble/curves": "2.2.0",
+		"@noble/hashes": "2.2.0",
+		"@noble/post-quantum": "0.6.1",
+		"@scure/bip39": "2.2.0"
 	},
 	"bin": {
 		"fz-agent": "dist/fz-agent.js",
 		"fz": "dist/fz.js"
 	},
 	"publishConfig": {
-		"access": "public"
+		"access": "public",
+		"provenance": true
 	},
 	"files": [
 		"dist",
@@ -53,7 +53,7 @@
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/forgezero-net/packages.git",
-		"directory": "packages/agent"
+		"directory": "agent"
 	},
 	"bugs": "https://github.com/forgezero-net/packages/issues",
 	"exports": {
@@ -133,6 +133,10 @@
 		"./project-context": {
 			"types": "./dist/project-context.d.ts",
 			"default": "./dist/project-context.js"
+		},
+		"./capacity-calibration": {
+			"types": "./dist/capacity-calibration.d.ts",
+			"default": "./dist/capacity-calibration.js"
 		}
 	}
 }

package/schema/deploy-v2.json

@@ -32,6 +32,20 @@
                 "version": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$" }
               }
             }
+          },
+          "capacityCalibration": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["endpoint"],
+            "properties": {
+              "endpoint": { "type": "string", "pattern": "^http://(?:localhost|127\\.0\\.0\\.1|\\[::1\\]):[1-9][0-9]{0,4}/" },
+              "maxConcurrency": { "type": "integer", "minimum": 1, "maximum": 4096 },
+              "requestsPerWorker": { "type": "integer", "minimum": 2, "maximum": 100 },
+              "maxP95Ms": { "type": "number", "exclusiveMinimum": 0 },
+              "maxErrorRate": { "type": "number", "minimum": 0, "maximum": 0.2 },
+              "headroomRatio": { "type": "number", "minimum": 0.25, "maximum": 0.95 },
+              "requestTimeoutMs": { "type": "integer", "minimum": 100, "maximum": 30000 }
+            }
           }
         }
       }