@forgezero/agent 0.1.88 → 0.1.90

package/dist/platform-genesis.js

@@ -355,7 +355,12 @@ async function executeSoftwareOperation(operation) {
     }
     if (software === "nginx") {
       const binary = await run(["/usr/sbin/nginx", "-v"]);
-      return binary.exitCode === 0 ? run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]) : binary;
+      if (binary.exitCode !== 0)
+        return binary;
+      if (!existsSync("/usr/lib/nginx/modules/ngx_http_headers_more_filter_module.so")) {
+        return { exitCode: 1, output: "Nginx response-header suppression module is unavailable" };
+      }
+      return run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]);
     }
     if (software === "arangodb") {
       const binary = await run(["/usr/sbin/arangod", "--version"]);
@@ -387,7 +392,7 @@ async function executeSoftwareOperation(operation) {
   }
   if (software === "docker" || software === "nginx" || software === "ufw" || software === "openssh-client" || software === "git") {
     const packageName = software === "openssh-client" ? "openssh-client" : software === "docker" ? "docker.io" : software;
-    const installed = await aptInstall(packageName);
+    const installed = software === "nginx" ? await aptInstallMany(["nginx", "libnginx-mod-http-headers-more-filter"]) : await aptInstall(packageName);
     if (installed.exitCode !== 0 || software !== "nginx" && software !== "docker")
       return installed;
     if (software === "docker") {

package/dist/platform-launch-profile.d.ts

@@ -17,6 +17,7 @@ export interface ForgeZeroLaunchProfile {
         city?: string;
     };
     agentOtlpEndpoint: string;
+    seedSyncEpoch: string;
     privateCidrs: readonly string[];
     nodeHostname(nodeIndex: number): string;
 }

package/dist/provision.d.ts

@@ -112,6 +112,8 @@ export interface UnitOptions {
     enforceEgress?: boolean;
     /** Provisioning-owned runner health endpoints; repository commands cannot change them. */
     runnerLoopbackPorts?: readonly number[];
+    /** Local platform API ports needed by the credential-bearing Agent. */
+    agentLoopbackPorts?: readonly number[];
     /** Vetted public TCP surface for project commands. Defaults to HTTPS only. */
     runnerPublicTcpPorts?: readonly number[];
     /** Enable PQ-authenticated lifecycle claims through a constrained root helper. */
@@ -172,7 +174,7 @@ export declare const WARP_SERVICE_DROP_IN_PATH = "/etc/systemd/system/warp-svc.s
 export declare const AGENT_EGRESS_UNIT_PATH = "/etc/systemd/system/forgezero-agent-egress.service";
 export declare const DEFAULT_RUNNER_PUBLIC_TCP_PORTS: readonly [443];
 /** Root-owned policy monitor. The credential-bearing Agent is bound to it. */
-export declare function agentEgressUnit(options: Pick<UnitOptions, 'binPath' | 'user' | 'repository' | 'pullDeployments' | 'bootstrapBundlePath' | 'bootstrapBundleManifestPath' | 'runnerLoopbackPorts' | 'runnerPublicTcpPorts'>): string;
+export declare function agentEgressUnit(options: Pick<UnitOptions, 'binPath' | 'user' | 'repository' | 'pullDeployments' | 'bootstrapBundlePath' | 'bootstrapBundleManifestPath' | 'runnerLoopbackPorts' | 'runnerPublicTcpPorts' | 'agentLoopbackPorts'>): string;
 /** Root may execute only package-owned OS strategies selected by id + version. */
 export declare function softwareHelperUnit(options: Pick<UnitOptions, 'binPath' | 'deployRoot'>): string;
 /** Fixed root boundary for verified, health-gated Agent replacement. */
@@ -281,8 +283,10 @@ export type ProvisionOperation = {
     path: string;
 } | {
     kind: 'verify-egress';
+    deploymentEnabled: boolean;
     runnerPublicTcpPorts: readonly number[];
     runnerLoopbackPorts: readonly number[];
+    agentLoopbackPorts: readonly number[];
 } | {
     kind: 'verify-resolved-stub';
 } | {

package/dist/provision.js

@@ -1198,7 +1198,12 @@ async function executeSoftwareOperation(operation) {
     }
     if (software === "nginx") {
       const binary = await run(["/usr/sbin/nginx", "-v"]);
-      return binary.exitCode === 0 ? run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]) : binary;
+      if (binary.exitCode !== 0)
+        return binary;
+      if (!existsSync4("/usr/lib/nginx/modules/ngx_http_headers_more_filter_module.so")) {
+        return { exitCode: 1, output: "Nginx response-header suppression module is unavailable" };
+      }
+      return run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]);
     }
     if (software === "arangodb") {
       const binary = await run(["/usr/sbin/arangod", "--version"]);
@@ -1230,7 +1235,7 @@ async function executeSoftwareOperation(operation) {
   }
   if (software === "docker" || software === "nginx" || software === "ufw" || software === "openssh-client" || software === "git") {
     const packageName = software === "openssh-client" ? "openssh-client" : software === "docker" ? "docker.io" : software;
-    const installed = await aptInstall(packageName);
+    const installed = software === "nginx" ? await aptInstallMany(["nginx", "libnginx-mod-http-headers-more-filter"]) : await aptInstall(packageName);
     if (installed.exitCode !== 0 || software !== "nginx" && software !== "docker")
       return installed;
     if (software === "docker") {
@@ -1382,11 +1387,22 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
 }
 
 // src/capacity-calibration.ts
-var percentile95 = (values) => {
+import { cpus, freemem, totalmem } from "node:os";
+var percentile = (values, quantile) => {
   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)];
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * quantile) - 1)];
+};
+var hostSample = () => {
+  let cpuIdle = 0;
+  let cpuTotal = 0;
+  for (const cpu of cpus()) {
+    cpuIdle += cpu.times.idle;
+    cpuTotal += Object.values(cpu.times).reduce((sum, value) => sum + value, 0);
+  }
+  const memoryTotal = totalmem();
+  return { cpuIdle, cpuTotal, memoryUsed: memoryTotal - freemem(), memoryTotal };
 };
 function localCalibrationEndpoint(value) {
   const endpoint = new URL(value);
@@ -1401,9 +1417,12 @@ function validateCapacityCalibrationOptions(options) {
   const requestsPerWorker = options.requestsPerWorker ?? 8;
   const maxP95Ms = options.maxP95Ms ?? 250;
   const maxErrorRate = options.maxErrorRate ?? 0.01;
-  const headroomRatio = options.headroomRatio ?? 0.8;
+  const safetyRatio = options.safetyRatio ?? 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) {
+  const minimumStageDurationMs = options.minimumStageDurationMs ?? 5000;
+  const maxCpuUtilizationPercent = options.maxCpuUtilizationPercent ?? 90;
+  const maxMemoryUtilizationPercent = options.maxMemoryUtilizationPercent ?? 90;
+  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(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
     throw new Error("Capacity calibration bounds are invalid.");
   }
   return {
@@ -1412,18 +1431,24 @@ function validateCapacityCalibrationOptions(options) {
     requestsPerWorker,
     maxP95Ms,
     maxErrorRate,
-    headroomRatio,
-    requestTimeoutMs
+    safetyRatio,
+    requestTimeoutMs,
+    minimumStageDurationMs,
+    maxCpuUtilizationPercent,
+    maxMemoryUtilizationPercent
   };
 }
-async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher) {
+async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimumDurationMs, fetcher, sampler) {
   const latencies = [];
   let succeeded = 0;
   let failed = 0;
   let overloaded = 0;
+  const systemBefore = sampler();
   const started = performance.now();
   await Promise.all(Array.from({ length: concurrency }, async () => {
-    for (let request = 0;request < requestsPerWorker; request += 1) {
+    let request = 0;
+    while (request < requestsPerWorker || performance.now() - started < minimumDurationMs) {
+      request += 1;
       const requestStarted = performance.now();
       try {
         const response = await fetcher(endpoint, {
@@ -1447,50 +1472,74 @@ async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetche
       }
     }
   }));
-  const elapsedSeconds = Math.max((performance.now() - started) / 1000, 0.001);
+  const durationMs = Math.max(performance.now() - started, 1);
+  const elapsedSeconds = durationMs / 1000;
+  const systemAfter = sampler();
+  const cpuTotal = Math.max(0, systemAfter.cpuTotal - systemBefore.cpuTotal);
+  const cpuIdle = Math.max(0, systemAfter.cpuIdle - systemBefore.cpuIdle);
+  const cpuUtilizationPercent = cpuTotal === 0 ? 0 : (cpuTotal - cpuIdle) / cpuTotal * 100;
+  const memoryUtilizationPercent = Math.max(systemBefore.memoryTotal > 0 ? systemBefore.memoryUsed / systemBefore.memoryTotal * 100 : 0, systemAfter.memoryTotal > 0 ? systemAfter.memoryUsed / systemAfter.memoryTotal * 100 : 0);
+  const requests = succeeded + failed;
   return {
     concurrency,
-    requests: concurrency * requestsPerWorker,
+    requests,
     succeeded,
     failed,
     overloaded,
-    throughputPerSecond: Number(((succeeded + failed) / elapsedSeconds).toFixed(2)),
-    p95Ms: Number(percentile95(latencies).toFixed(2))
+    successfulRequestsPerSecond: Number((succeeded / elapsedSeconds).toFixed(2)),
+    attemptedRequestsPerSecond: Number((requests / elapsedSeconds).toFixed(2)),
+    durationMs: Number(durationMs.toFixed(2)),
+    errorRate: Number((failed / Math.max(requests, 1)).toFixed(6)),
+    p95Ms: Number(percentile(latencies, 0.95).toFixed(2)),
+    p99Ms: Number(percentile(latencies, 0.99).toFixed(2)),
+    cpuUtilizationPercent: Number(cpuUtilizationPercent.toFixed(2)),
+    memoryUtilizationPercent: Number(memoryUtilizationPercent.toFixed(2))
   };
 }
-async function calibrateHttpConcurrency(options, fetcher = fetch) {
+async function calibrateHttpConcurrency(options, fetcher = fetch, sampler = hostSample) {
   const {
     endpoint,
     maxConcurrency,
     requestsPerWorker,
     maxP95Ms,
     maxErrorRate,
-    headroomRatio,
-    requestTimeoutMs: timeoutMs
+    safetyRatio,
+    requestTimeoutMs: timeoutMs,
+    minimumStageDurationMs,
+    maxCpuUtilizationPercent,
+    maxMemoryUtilizationPercent
   } = validateCapacityCalibrationOptions(options);
   const stages = [];
-  let lastSafe = 1;
+  let lastSafe;
   let stopReason = "maximum-tested";
   for (let concurrency = 1;; concurrency = Math.min(maxConcurrency, concurrency * 2)) {
-    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher);
+    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimumStageDurationMs, fetcher, sampler);
     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)
+    const throughputRegressed = Boolean(previous && concurrency > 1 && measured.successfulRequestsPerSecond < previous.successfulRequestsPerSecond * 0.9);
+    if (measured.overloaded > 0 || measured.errorRate > maxErrorRate)
       stopReason = "errors";
     else if (measured.p95Ms > maxP95Ms)
       stopReason = "latency";
+    else if (measured.cpuUtilizationPercent > maxCpuUtilizationPercent)
+      stopReason = "cpu";
+    else if (measured.memoryUtilizationPercent > maxMemoryUtilizationPercent)
+      stopReason = "memory";
     else if (throughputRegressed)
       stopReason = "throughput-regression";
     else
-      lastSafe = concurrency;
+      lastSafe = measured;
     if (stopReason !== "maximum-tested" || concurrency === maxConcurrency)
       break;
   }
+  if (!lastSafe)
+    throw new Error("Capacity calibration found no safe request stage.");
   return {
     endpoint: endpoint.toString(),
-    recommendedConcurrency: Math.max(1, Math.floor(lastSafe * headroomRatio)),
+    measuredSustainableRequestsPerSecond: lastSafe.successfulRequestsPerSecond,
+    allowedRequestsPerSecond: Math.max(1, Math.floor(lastSafe.successfulRequestsPerSecond * safetyRatio)),
+    safetyRatio,
+    recommendedConcurrency: Math.max(1, Math.floor(lastSafe.concurrency * safetyRatio)),
     stopReason,
     stages
   };
@@ -1567,8 +1616,11 @@ function capacityCalibration(value, where) {
     "requestsPerWorker",
     "maxP95Ms",
     "maxErrorRate",
-    "headroomRatio",
-    "requestTimeoutMs"
+    "safetyRatio",
+    "requestTimeoutMs",
+    "minimumStageDurationMs",
+    "maxCpuUtilizationPercent",
+    "maxMemoryUtilizationPercent"
   ], where);
   const endpoint = text(calibration.endpoint, `${where}.endpoint`);
   try {
@@ -1592,8 +1644,11 @@ function capacityCalibration(value, where) {
       "requestsPerWorker",
       "maxP95Ms",
       "maxErrorRate",
-      "headroomRatio",
-      "requestTimeoutMs"
+      "safetyRatio",
+      "requestTimeoutMs",
+      "minimumStageDurationMs",
+      "maxCpuUtilizationPercent",
+      "maxMemoryUtilizationPercent"
     ].flatMap((name) => {
       const found = optionalNumber(name);
       return found === undefined ? [] : [[name, found]];
@@ -2784,35 +2839,76 @@ function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_
 function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
   validateSoftwareRequirements(requirements);
   return new Promise((resolve5, reject) => {
-    const socket = connect3(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
-`));
-    let buffer = "";
-    socket.setTimeout(timeoutMs, () => {
-      socket.destroy();
-      reject(new Error("software helper did not answer before its deadline"));
-    });
-    socket.on("data", (chunk) => {
-      buffer += chunk.toString("utf8");
-      const newline = buffer.indexOf(`
-`);
-      if (newline < 0)
+    const deadline = Date.now() + timeoutMs;
+    let settled = false;
+    const finish = (cause, results) => {
+      if (settled)
         return;
-      socket.end();
+      settled = true;
+      if (cause)
+        reject(cause);
+      else
+        resolve5(results);
+    };
+    const attempt = () => {
+      if (settled)
+        return;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0)
+        return finish(new Error("software helper did not answer before its deadline"));
+      if (!existsSync7(socketPath)) {
+        setTimeout(attempt, Math.min(100, Math.max(1, remaining)));
+        return;
+      }
+      let buffer = "";
+      let socket;
       try {
-        const response = JSON.parse(buffer.slice(0, newline));
-        if (!response.ok || !response.results)
-          throw new Error(response.error?.message ?? "software helper refused the request");
-        resolve5(response.results);
+        socket = connect3(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
+`));
       } catch (cause) {
-        reject(cause);
+        const error = cause;
+        if ((error.code === "ENOENT" || error.code === "ECONNREFUSED") && Date.now() < deadline) {
+          setTimeout(attempt, Math.min(100, Math.max(1, deadline - Date.now())));
+          return;
+        }
+        finish(error);
+        return;
       }
-    });
-    socket.on("error", reject);
+      socket.setTimeout(remaining, () => {
+        socket.destroy();
+        finish(new Error("software helper did not answer before its deadline"));
+      });
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        const newline = buffer.indexOf(`
+`);
+        if (newline < 0)
+          return;
+        socket.end();
+        try {
+          const response = JSON.parse(buffer.slice(0, newline));
+          if (!response.ok || !response.results)
+            throw new Error(response.error?.message ?? "software helper refused the request");
+          finish(undefined, response.results);
+        } catch (cause) {
+          finish(cause);
+        }
+      });
+      socket.on("error", (cause) => {
+        socket.destroy();
+        if ((cause.code === "ENOENT" || cause.code === "ECONNREFUSED") && Date.now() < deadline) {
+          setTimeout(attempt, Math.min(100, Math.max(1, deadline - Date.now())));
+          return;
+        }
+        finish(cause);
+      });
+    };
+    attempt();
   });
 }
 
 // src/version.ts
-var VERSION3 = "0.1.88";
+var VERSION3 = "0.1.90";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";
@@ -2948,6 +3044,7 @@ function agentEgressUnit(options) {
   }
   const deploymentEnabled = Boolean(options.repository || bootstrapBundleEnabled || options.pullDeployments);
   const runnerLoopbackPorts = normalizeEgressTcpPorts(options.runnerLoopbackPorts ?? []);
+  const agentLoopbackPorts = normalizeEgressTcpPorts(options.agentLoopbackPorts ?? []);
   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");
@@ -2955,8 +3052,10 @@ function agentEgressUnit(options) {
   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 policyProof = `ExecStartPost=${bin} egress-policy-check ${users.map((name) => `--user=${name}`).join(" ")}${runnerGrant}`;
+  const portGrantEnabled = deploymentEnabled || agentLoopbackPorts.length > 0;
+  const restrictedUser = deploymentEnabled ? DEPLOYMENT_RUNNER_USER : user;
+  const portGrant = portGrantEnabled ? ` --loopback-user=${restrictedUser}` + (deploymentEnabled ? runnerLoopbackPorts.map((port) => ` --loopback-tcp-port=${port}`).join("") : "") + agentLoopbackPorts.map((port) => ` --shared-loopback-tcp-port=${port}`).join("") + (deploymentEnabled ? runnerPublicTcpPorts.map((port) => ` --public-tcp-port=${port}`).join("") : "") : "";
+  const policyProof = `ExecStartPost=${bin} egress-policy-check ${users.map((name) => `--user=${name}`).join(" ")}${portGrant}`;
   return `[Unit]
 Description=ForgeZero Agent host egress policy
 Documentation=https://www.forgezero.net/docs/agent
@@ -2969,7 +3068,7 @@ Type=notify
 NotifyAccess=all
 User=root
 Group=root
-ExecStart=${bin} egress-policy ${users.map((name) => `--user=${name}`).join(" ")}${runnerGrant}
+ExecStart=${bin} egress-policy ${users.map((name) => `--user=${name}`).join(" ")}${portGrant}
 ${policyProof}
 Restart=on-failure
 RestartSec=2
@@ -3253,7 +3352,7 @@ function agentEnrolmentUnit(options) {
 Requires=forgezero-agent-egress.service
 BindsTo=forgezero-agent-egress.service
 ` : "";
-  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives() : "";
+  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives(options.agentLoopbackPorts ?? []) : "";
   return `[Unit]
 Description=Bind this machine to its ForgeZero compute
 After=network-online.target
@@ -3290,7 +3389,7 @@ WantedBy=multi-user.target
 function deploymentRunnerUnit(options) {
   const bin = options.binPath ?? "fz-agent";
   const root = options.deployRoot ?? "/opt/forgezero";
-  const agentUser = options.user ?? "forgezero-agent";
+  const agentUser = options.user ?? "forgezero";
   const egressDependency = options.enforceEgress ? `After=forgezero-agent-egress.service
 Requires=forgezero-agent-egress.service
 BindsTo=forgezero-agent-egress.service
@@ -3331,7 +3430,7 @@ RestrictRealtime=true
 MemoryDenyWriteExecute=true
 LockPersonality=true
 ${egressDirectives}
-ReadWritePaths=${root}/releases ${root}/runner-home
+ReadWritePaths=${root}/releases ${root}/runner-home ${root}/slots /etc/nginx/conf.d /var/log/nginx
 
 [Install]
 WantedBy=multi-user.target
@@ -3341,7 +3440,7 @@ 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");
+    throw new Error("compute Agent provisioning requires an explicit supervised OTLP collector coordinate");
   }
   let telemetryEndpoint;
   {
@@ -3349,10 +3448,13 @@ function agentUnit(options) {
     try {
       endpoint = new URL(options.telemetryEndpoint);
     } catch {
-      throw new Error("compute telemetry endpoint must be an absolute public HTTPS URL");
+      throw new Error("compute telemetry endpoint must be an absolute collector URL");
+    }
+    const localCollector = endpoint.protocol === "http:" && endpoint.hostname === "127.0.0.1" && endpoint.port === "4318" && endpoint.pathname === "/";
+    const publicCollector = 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");
+    if (!localCollector && !publicCollector || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+      throw new Error("compute telemetry endpoint must be the supervised loopback collector or credential-free public HTTPS");
     }
-    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";
@@ -3466,7 +3568,7 @@ function agentUnit(options) {
   const supplementaryGroups = [
     AGENT_UPDATE_GROUP,
     deploymentEnabled ? DEPLOYMENT_GROUP : null,
-    deploymentEnabled ? SOFTWARE_HELPER_GROUP : null,
+    SOFTWARE_HELPER_GROUP,
     lifecycleEnabled ? LIFECYCLE_GROUP : null
   ].filter((value) => value !== null);
   const deploymentGroup = supplementaryGroups.length > 0 ? `SupplementaryGroups=${supplementaryGroups.join(" ")}` : "";
@@ -3475,7 +3577,7 @@ function agentUnit(options) {
     "forgezero-agent-update-helper.service",
     options.enforceEgress ? "forgezero-agent-egress.service" : null,
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
-    deploymentEnabled ? "forgezero-software-helper.service" : null,
+    "forgezero-software-helper.service",
     lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
     warpEnabled ? "warp-svc.service" : null,
     enrolmentEnabled ? "forgezero-agent-enrol.service" : null
@@ -3484,7 +3586,7 @@ function agentUnit(options) {
     "forgezero-agent-update-helper.service",
     options.enforceEgress ? "forgezero-agent-egress.service" : null,
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
-    deploymentEnabled ? "forgezero-software-helper.service" : null,
+    "forgezero-software-helper.service",
     lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
     warpEnabled ? "warp-svc.service" : null,
     enrolmentEnabled ? "forgezero-agent-enrol.service" : null
@@ -3499,9 +3601,9 @@ function agentUnit(options) {
   const snpDevice = options.mode === "attested" ? `DevicePolicy=closed
 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
+ExecStartPre=+/bin/chmod 0660 /dev/sev-guest
 ` : "";
-  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives() : "";
+  const egressDirectives = options.enforceEgress ? systemdAgentEgressDirectives(options.agentLoopbackPorts ?? []) : "";
   return `[Unit]
 Description=ForgeZero node agent (${options.mode})
 Documentation=https://www.forgezero.net/docs/agent
@@ -3632,6 +3734,7 @@ function planProvision(options) {
   const deployRoot = options.deployRoot ?? "/opt/forgezero";
   const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
   const runnerLoopbackPorts = normalizeEgressTcpPorts(options.runnerLoopbackPorts ?? []);
+  const agentLoopbackPorts = normalizeEgressTcpPorts(options.agentLoopbackPorts ?? []);
   const runnerPublicTcpPorts = normalizeEgressTcpPorts(options.runnerPublicTcpPorts ?? DEFAULT_RUNNER_PUBLIC_TCP_PORTS);
   const lifecycleEnabled = Boolean(options.pullMigrations && options.lifecycleProfilePath);
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
@@ -3680,8 +3783,9 @@ function planProvision(options) {
   const enabledUnits = [
     "forgezero-agent.socket",
     "forgezero-agent-update-helper.service",
+    "forgezero-software-helper.service",
     ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
-    ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
+    ...deploymentEnabled ? ["forgezero-deploy-runner.service"] : [],
     ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
     ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
     ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : [],
@@ -3689,8 +3793,9 @@ function planProvision(options) {
   ];
   const restartedUnits = [
     "forgezero-agent-update-helper.service",
+    "forgezero-software-helper.service",
     ...options.enforceEgress ? ["forgezero-agent-egress.service"] : [],
-    ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
+    ...deploymentEnabled ? ["forgezero-deploy-runner.service"] : [],
     ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
     ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
     ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : []
@@ -3714,9 +3819,9 @@ function planProvision(options) {
       ...options.enforceEgress ? [
         { path: AGENT_EGRESS_UNIT_PATH, unit: agentEgressUnit(options) }
       ] : [],
+      { path: SOFTWARE_HELPER_UNIT_PATH, unit: softwareHelperUnit(options) },
       ...deploymentEnabled ? [
-        { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) },
-        { path: SOFTWARE_HELPER_UNIT_PATH, unit: softwareHelperUnit(options) }
+        { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) }
       ] : [],
       ...enrolmentEnabled ? [
         { path: ENROLMENT_UNIT_PATH, unit: agentEnrolmentUnit(options) }
@@ -3749,24 +3854,29 @@ function planProvision(options) {
       step("Agent update helper access group", { kind: "commands", commands: [{ argv: ["/usr/sbin/groupadd", "--system", AGENT_UPDATE_GROUP], acceptedExitCodes: [0, 9] }] }),
       ...sourceBinPath && binPath ? [step("root-owned agent runtime", { kind: "install-runtime", source: sourceBinPath, binary: binPath, version: VERSION3 })] : [],
       ...warpEnabled ? [step("Cloudflare One client for Ubuntu 26.04", { kind: "install-warp" })] : [],
-      ...deploymentEnabled ? [step("deployment isolation group", { kind: "commands", commands: [
-        { argv: ["/usr/sbin/groupadd", "--system", DEPLOYMENT_GROUP], acceptedExitCodes: [0, 9] },
+      step("software strategy helper group", { kind: "commands", commands: [
         { argv: ["/usr/sbin/groupadd", "--system", SOFTWARE_HELPER_GROUP], acceptedExitCodes: [0, 9] }
+      ] }),
+      ...deploymentEnabled ? [step("deployment isolation group", { kind: "commands", commands: [
+        { argv: ["/usr/sbin/groupadd", "--system", DEPLOYMENT_GROUP], acceptedExitCodes: [0, 9] }
       ] })] : [],
       ...lifecycleEnabled ? [step("lifecycle helper access group", { kind: "commands", commands: [{ argv: ["/usr/sbin/groupadd", "--system", LIFECYCLE_GROUP], acceptedExitCodes: [0, 9] }] })] : [],
       step("service account", { kind: "commands", commands: [{ argv: ["/usr/sbin/useradd", "--system", "--no-create-home", "--shell", "/usr/sbin/nologin", user], acceptedExitCodes: [0, 9] }] }),
       step("bind service account to vault group", { kind: "commands", commands: [{ argv: ["/usr/sbin/usermod", "-g", VAULT_GROUP, user] }] }),
       step("grant verified Agent update access", { kind: "commands", commands: [{ argv: ["/usr/sbin/usermod", "-a", "-G", AGENT_UPDATE_GROUP, user] }] }),
+      step("grant software helper socket access", { kind: "commands", commands: [
+        { argv: ["/usr/sbin/usermod", "-a", "-G", SOFTWARE_HELPER_GROUP, user] }
+      ] }),
       ...lifecycleEnabled ? [step("grant lifecycle helper socket access", { kind: "commands", commands: [{ argv: ["/usr/sbin/usermod", "-a", "-G", LIFECYCLE_GROUP, user] }] })] : [],
       ...deploymentEnabled ? [step("credential-free deployment account", { kind: "commands", commands: [
         { argv: ["/usr/sbin/useradd", "--system", "--no-create-home", "--shell", "/usr/sbin/nologin", "--gid", DEPLOYMENT_GROUP, DEPLOYMENT_RUNNER_USER], acceptedExitCodes: [0, 9] },
         { argv: ["/usr/sbin/useradd", "--system", "--no-create-home", "--shell", "/usr/sbin/nologin", "--gid", VAULT_GROUP, APPLICATION_RUNTIME_USER], acceptedExitCodes: [0, 9] },
         { argv: ["/usr/sbin/usermod", "-a", "-G", DEPLOYMENT_GROUP, APPLICATION_RUNTIME_USER] },
-        { argv: ["/usr/sbin/usermod", "-a", "-G", `${DEPLOYMENT_GROUP},${SOFTWARE_HELPER_GROUP}`, user] }
+        { argv: ["/usr/sbin/usermod", "-a", "-G", DEPLOYMENT_GROUP, user] }
       ] })] : [],
       step("credential and state directories", { kind: "directories", directories: [
         { path: credentialDir, mode: 448, owner: "root", group: "root" },
-        { path: "/var/lib/forgezero", mode: 488, owner: "root", group: "root" }
+        { path: "/var/lib/forgezero", mode: 488, owner: "root", group: VAULT_GROUP }
       ] }),
       step("encrypted node identity", { kind: "ensure-seed", credential: seedCredentialPath }),
       ...options.generateGitIdentity && gitCredentialPath && gitPublicKeyPath ? [
@@ -3817,19 +3927,26 @@ function planProvision(options) {
         { argv: ["/usr/bin/systemctl", "enable", ...enabledUnits] },
         { argv: ["/usr/bin/systemctl", "reset-failed", "forgezero-agent.service"], acceptedExitCodes: [0, 1] },
         ...restartedUnits.length ? [{ argv: ["/usr/bin/systemctl", "restart", ...restartedUnits] }] : [],
+        { argv: ["/usr/bin/systemctl", "stop", "forgezero-agent-proxy.service"], acceptedExitCodes: [0, 1, 5] },
         { argv: ["/usr/bin/systemctl", "restart", "forgezero-agent.socket"] },
         { argv: ["/usr/bin/systemctl", "reset-failed", "forgezero-agent.service"], acceptedExitCodes: [0, 1] },
         { argv: ["/usr/bin/systemctl", "restart", "forgezero-agent.service"] }
       ] }),
       ...enrolmentEnabled ? [step("prove the compute binding is durable", { kind: "verify-file", path: enrolStatePath })] : [],
-      ...options.enforceEgress ? [step("prove the Agent egress policy is active", { kind: "verify-egress", runnerPublicTcpPorts, runnerLoopbackPorts })] : [],
+      ...options.enforceEgress ? [step("prove the Agent egress policy is active", {
+        kind: "verify-egress",
+        deploymentEnabled,
+        runnerPublicTcpPorts,
+        runnerLoopbackPorts,
+        agentLoopbackPorts
+      })] : [],
       step("prove it is running", { kind: "commands", commands: [{ argv: ["/usr/bin/systemctl", "is-active", "forgezero-agent.service"] }] }),
       step("prove the public Vault socket exists", { kind: "wait-socket", path: options.socketPath, attempts: 100, intervalMs: 100 }),
       step("prove the Agent Vault backend exists", { kind: "wait-socket", path: agentBackendSocketPath(options.socketPath), attempts: 100, intervalMs: 100 }),
       step("prove the Agent update helper exists", { kind: "wait-socket", path: DEFAULT_AGENT_UPDATE_SOCKET, attempts: 100, intervalMs: 100 }),
+      step("prove the software strategy helper socket exists", { kind: "wait-socket", path: DEFAULT_SOFTWARE_HELPER_SOCKET, attempts: 100, intervalMs: 100 }),
       ...deploymentEnabled ? [
-        step("prove the deployment runner socket exists", { kind: "wait-socket", path: DEPLOYMENT_RUNNER_SOCKET, attempts: 100, intervalMs: 100 }),
-        step("prove the software strategy helper socket exists", { kind: "wait-socket", path: DEFAULT_SOFTWARE_HELPER_SOCKET, attempts: 100, intervalMs: 100 })
+        step("prove the deployment runner socket exists", { kind: "wait-socket", path: DEPLOYMENT_RUNNER_SOCKET, attempts: 100, intervalMs: 100 })
       ] : [],
       ...lifecycleEnabled ? [step("prove the lifecycle helper socket exists", { kind: "wait-socket", path: lifecycleHelperSocketPath, attempts: 100, intervalMs: 100 })] : [],
       ...warpEnabled ? [step("prove Cloudflare WARP is connected", { kind: "verify-warp" })] : [],

package/dist/recovery-host.js

@@ -14,7 +14,7 @@ var checked = async (run, argv, expected = 0) => {
   return result;
 };
 var activeSlot = () => {
-  const slot = readFileSync("/opt/forgezero/.forge-slot", "utf8").trim();
+  const slot = readFileSync("/opt/forgezero/slots/.active", "utf8").trim();
   if (slot !== "blue" && slot !== "green")
     throw new Error("invalid active slot");
   return slot;