@forgezero/agent 0.1.27 → 0.1.29

package/README.md

@@ -180,8 +180,9 @@ compute's systemd-sealed SSH deploy key, or a fine-grained HTTPS token selected
 by a project-vault secret name. A signed claim contains the mode and secret name
 only. The agent resolves the value from its scoped memory cache, limits the Git
 header to the repository origin, never writes the token into a command, and
-never exposes it to tenant pipeline steps. Automatic GitHub App token minting
-can feed the same short-lived token mode later; it is not implemented today.
+never exposes it to tenant pipeline steps. These provider-neutral modes are the
+complete contract; a GitHub App is not a missing dependency and would be added
+later only as an explicit provider-specific mode with expiry and revocation tests.
 
 An operator may also force a deployment and await the complete result over the
 private control socket:

package/dist/agent-heartbeat.js

@@ -376,8 +376,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";
@@ -416,7 +429,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION2 = "0.1.27";
+var VERSION2 = "0.1.29";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");

package/dist/fz-agent.js

@@ -4267,8 +4267,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";
@@ -4328,7 +4341,7 @@ function projectVaultCoordinate(key) {
 function tenantNodeApiUrl(apiUrl, tenantSlug) {
   if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(tenantSlug))
     throw new Error("tenant slug is malformed");
-  const url = new URL(apiUrl);
+  const url = signedNodeApiUrl(apiUrl);
   url.pathname = `/api/t/${encodeURIComponent(tenantSlug)}`;
   url.search = "";
   url.hash = "";
@@ -6364,11 +6377,10 @@ ${attestationSetup}if [[ ! -x /usr/local/bin/bun ]]; then
   install -m 0755 ${agentBun}/bin/bun /usr/local/bin/bun
   rm -f /run/fz-bun-install
 fi
-if [[ ! -x /usr/local/bin/fz-agent ]] || [[ "$(/usr/local/bin/fz-agent --version 2>/dev/null || true)" != "${profile.agentVersion}" ]]; then
+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}
-  ln -sfn ${agentBun}/bin/fz-agent /usr/local/bin/fz-agent
 fi
-env   FZ_API=${profile.apiUrl}   FZ_AGENT_BIN=/usr/local/bin/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}   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" : ""}
 `;
 }
 function cloudInit(profile, claim, manifest) {
@@ -6564,16 +6576,36 @@ async function removeMetalGuest(profile, claim, exec) {
     throw new MetalProvisionError("create claim cannot remove a guest");
   const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
   const manifestPath = join2(profile.stateDir, `${name}.json`);
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join2(profile.unitDir, service);
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
   const manifest = existsSync5(manifestPath) ? JSON.parse(readFileSync4(manifestPath, "utf8")) : legacyPlatformManifest(profile, claim, name);
-  if (!manifest)
+  if (!manifest) {
+    const seedBase = join2(profile.seedDir, name);
+    const localArtifacts = [
+      unitPath,
+      `${seedBase}-seed.iso`,
+      `${seedBase}-user-data`,
+      `${seedBase}-meta-data`,
+      `${seedBase}-network-config`
+    ];
+    if (localArtifacts.some(existsSync5)) {
+      throw new MetalProvisionError("guest artifacts exist without owned inventory");
+    }
+    const [volume, active] = await Promise.all([
+      exec(["lvs", "--noheadings", lv]),
+      exec(["systemctl", "is-active", service])
+    ]);
+    if (volume.exitCode === 0 || active.exitCode === 0) {
+      throw new MetalProvisionError("guest runtime exists without owned inventory");
+    }
     return {};
+  }
   const currentIdentity = manifest.computeKey === claim.computeKey && manifest.reference === claim.spec.reference && manifest.name === name;
   const legacyPlatformIdentity = claim.bootstrap?.kind === "platform-genesis" && claim.computeKey === `platform:${name}` && claim.spec.reference === `platform:${name}` && manifest.name === name && manifest.disk === `/dev/${profile.volumeGroup}/${name}` && manifest.address === claim.spec.guestAddress && (manifest.unit === `fz-guest@${name}.service` || manifest.unit === `forgezero-guest@${name}.service`);
   if (!currentIdentity && !legacyPlatformIdentity) {
     throw new MetalProvisionError("compute identity conflicts with host inventory");
   }
-  const service = `forgezero-guest@${name}.service`;
-  const unitPath = join2(profile.unitDir, service);
   if (existsSync5(unitPath))
     await checked(exec, ["systemctl", "disable", "--now", service]);
   else if (legacyPlatformIdentity)
@@ -6581,7 +6613,6 @@ async function removeMetalGuest(profile, claim, exec) {
   else if ((await exec(["systemctl", "is-active", service])).exitCode === 0) {
     throw new MetalProvisionError("guest unit is active but its owned unit file is missing");
   }
-  const lv = `/dev/${profile.volumeGroup}/${name}`;
   if ((await exec(["lvs", "--noheadings", lv])).exitCode === 0)
     await checked(exec, ["lvremove", "-fy", lv]);
   for (const path of [
@@ -7844,7 +7875,7 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 import { readFileSync as readFileSync7 } from "fs";
 
 // src/version.ts
-var VERSION2 = "0.1.27";
+var VERSION2 = "0.1.29";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");
@@ -8455,7 +8486,6 @@ if (import.meta.main) {
   const attestationSource = existsSync13("/dev/sev-guest") ? createSnpAttestationSource() : undefined;
   const running = runAgent({
     socketPath: process.env.FZ_SOCKET_PATH ?? DEFAULT_SOCKET_PATH,
-    listenFd: systemdListenFd(),
     seedCredential: process.env.FZ_SEED_CREDENTIAL,
     seedPath: process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH,
     nodeKey: process.env.FZ_NODE_KEY,

package/dist/fz.js

@@ -4886,7 +4886,7 @@ var AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-
 var MAX_REQUEST_BYTES = 8 * 1024;
 
 // src/version.ts
-var VERSION2 = "0.1.27";
+var VERSION2 = "0.1.29";
 
 // src/software.ts
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
@@ -4973,6 +4973,7 @@ var VAULT_GROUP = "forgezero-vault";
 var LIFECYCLE_GROUP = "forgezero-lifecycle";
 var DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
 var AGENT_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-agent.socket";
+var AGENT_SOCKET_PROXY_UNIT_PATH = "/etc/systemd/system/forgezero-agent-proxy.service";
 var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
 var ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
 var LIFECYCLE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-lifecycle-helper.service";
@@ -5062,17 +5063,55 @@ SocketGroup=${VAULT_GROUP}
 SocketMode=0660
 DirectoryMode=0750
 RemoveOnStop=true
-Service=forgezero-agent.service
+Service=forgezero-agent-proxy.service
 
 [Install]
 WantedBy=sockets.target
 `;
 }
+function agentSocketProxyUnit(options) {
+  const backend = agentBackendSocketPath(options.socketPath);
+  const user = options.user ?? "forgezero";
+  return `[Unit]
+Description=ForgeZero application Vault socket proxy
+Documentation=https://www.forgezero.net/docs/agent
+Requires=forgezero-agent.service
+After=forgezero-agent.service
+
+[Service]
+User=${user}
+Group=${VAULT_GROUP}
+ExecStart=/usr/lib/systemd/systemd-socket-proxyd ${backend}
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+RestrictAddressFamilies=AF_UNIX
+`;
+}
+function agentBackendSocketPath(publicSocketPath) {
+  const socket = systemdPath(publicSocketPath, "agent socket");
+  const backend = `${socket}.backend`;
+  if (Buffer.byteLength(backend) > 100)
+    throw new Error("agent socket path is too long for a Unix socket");
+  return backend;
+}
 var systemdPath = (value, label) => {
   if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
     throw new Error(`invalid ${label} path`);
   return value;
 };
+var awaitSocketCommand = (path) => {
+  const socket = systemdPath(path, "readiness socket");
+  return `for attempt in $(seq 1 100); do test -S ${socket} && exit 0; sleep 0.1; done; exit 1`;
+};
 var validNodeHostname = (value) => !value || value.length <= 253 && value === value.toLowerCase() && value.split(".").length >= 3 && value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
 function warpConfigUnit(options) {
   if (!options.warpOrganization || !/^[a-z0-9][a-z0-9-]{0,62}$/i.test(options.warpOrganization)) {
@@ -5311,7 +5350,7 @@ function agentUnit(options) {
     }
   }
   const environment = [
-    `FZ_SOCKET_PATH=${options.socketPath}`,
+    `FZ_SOCKET_PATH=${agentBackendSocketPath(options.socketPath)}`,
     `FZ_CONTROL_SOCKET=${controlSocketPath}`,
     `FZ_SEED_CREDENTIAL=agent-seed`,
     `FZ_AGENT_MODE=${options.mode}`,
@@ -5391,7 +5430,6 @@ Type=simple
 User=${user}
 Group=${VAULT_GROUP}
 ${deploymentGroup}
-Sockets=forgezero-agent.socket
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
 ${gitCredential}${projectCredentials}${projectCredentials ? `
 ` : ""}${snpPrepare}ExecStart=${bin}
@@ -5479,6 +5517,7 @@ function planProvision(options) {
     unit: agentUnit({ ...options, mode, lifecycleProfilePath, lifecycleHelperSocketPath }),
     auxiliaryUnits: [
       { 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) },
       ...deploymentEnabled ? [
         { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) },
@@ -5554,6 +5593,10 @@ function planProvision(options) {
         label: "credential directory",
         command: `install -d -o root -g root -m 0700 ${credentialDir}`
       },
+      {
+        label: "Agent state directory",
+        command: "install -d -o root -g root -m 0750 /var/lib/forgezero"
+      },
       {
         label: "encrypted node identity",
         command: `test -s ${seedCredentialPath} || { ` + `openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\\n' | ` + `systemd-creds encrypt --name=agent-seed - ${seedCredentialPath}; ` + `chmod 0400 ${seedCredentialPath}; }`
@@ -5588,8 +5631,8 @@ function planProvision(options) {
         command: "systemctl disable --now forgezero-deploy-runner.socket 2>/dev/null || true; rm -f /etc/systemd/system/forgezero-deploy-runner.socket; systemctl daemon-reload"
       }] : [],
       {
-        label: "enable and start",
-        command: `systemctl enable --now ${[
+        label: "enable and converge services",
+        command: `systemctl enable ${[
           "forgezero-agent.socket",
           "forgezero-agent-update-helper.service",
           ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
@@ -5597,25 +5640,32 @@ function planProvision(options) {
           ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
           ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : [],
           "forgezero-agent.service"
-        ].join(" ")}`
+        ].join(" ")}; systemctl reset-failed forgezero-agent.service || true; systemctl restart ${[
+          "forgezero-agent-update-helper.service",
+          ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
+          ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
+          ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
+          ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : []
+        ].join(" ")}; systemctl restart forgezero-agent.socket; systemctl reset-failed forgezero-agent.service || true; systemctl restart forgezero-agent.service`
       },
       ...enrolmentEnabled ? [{
         label: "prove the compute binding is durable",
         command: `test -s ${enrolStatePath}`
       }] : [],
       { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
-      { label: "prove the vault socket exists", command: `test -S ${options.socketPath}` },
-      { label: "prove the Agent update helper exists", command: `test -S ${DEFAULT_AGENT_UPDATE_SOCKET}` },
+      { label: "prove the public Vault socket exists", command: awaitSocketCommand(options.socketPath) },
+      { label: "prove the Agent Vault backend exists", command: awaitSocketCommand(agentBackendSocketPath(options.socketPath)) },
+      { label: "prove the Agent update helper exists", command: awaitSocketCommand(DEFAULT_AGENT_UPDATE_SOCKET) },
       ...deploymentEnabled ? [{
         label: "prove the deployment runner socket exists",
-        command: `test -S ${DEPLOYMENT_RUNNER_SOCKET}`
+        command: awaitSocketCommand(DEPLOYMENT_RUNNER_SOCKET)
       }, {
         label: "prove the software strategy helper socket exists",
-        command: `test -S ${DEFAULT_SOFTWARE_HELPER_SOCKET}`
+        command: awaitSocketCommand(DEFAULT_SOFTWARE_HELPER_SOCKET)
       }] : [],
       ...lifecycleEnabled ? [{
         label: "prove the lifecycle helper socket exists",
-        command: `test -S ${lifecycleHelperSocketPath}`
+        command: awaitSocketCommand(lifecycleHelperSocketPath)
       }] : [],
       ...warpEnabled ? [{
         label: "prove Cloudflare WARP is connected",
@@ -5623,7 +5673,7 @@ function planProvision(options) {
       }] : [],
       ...options.repository ? [{
         label: "prove the deployment control socket exists",
-        command: `test -S ${options.controlSocketPath ?? "/run/forgezero/control.sock"}`
+        command: awaitSocketCommand(options.controlSocketPath ?? "/run/forgezero/control.sock")
       }] : []
     ]
   };

package/dist/guest-enrolment.js

@@ -28,8 +28,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";

package/dist/metal-helper-socket.js

@@ -352,11 +352,10 @@ ${attestationSetup}if [[ ! -x /usr/local/bin/bun ]]; then
   install -m 0755 ${agentBun}/bin/bun /usr/local/bin/bun
   rm -f /run/fz-bun-install
 fi
-if [[ ! -x /usr/local/bin/fz-agent ]] || [[ "$(/usr/local/bin/fz-agent --version 2>/dev/null || true)" != "${profile.agentVersion}" ]]; then
+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}
-  ln -sfn ${agentBun}/bin/fz-agent /usr/local/bin/fz-agent
 fi
-env   FZ_API=${profile.apiUrl}   FZ_AGENT_BIN=/usr/local/bin/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}   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" : ""}
 `;
 }
 function cloudInit(profile, claim, manifest) {
@@ -552,16 +551,36 @@ async function removeMetalGuest(profile, claim, exec) {
     throw new MetalProvisionError("create claim cannot remove a guest");
   const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
   const manifestPath = join(profile.stateDir, `${name}.json`);
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join(profile.unitDir, service);
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
   const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : legacyPlatformManifest(profile, claim, name);
-  if (!manifest)
+  if (!manifest) {
+    const seedBase = join(profile.seedDir, name);
+    const localArtifacts = [
+      unitPath,
+      `${seedBase}-seed.iso`,
+      `${seedBase}-user-data`,
+      `${seedBase}-meta-data`,
+      `${seedBase}-network-config`
+    ];
+    if (localArtifacts.some(existsSync)) {
+      throw new MetalProvisionError("guest artifacts exist without owned inventory");
+    }
+    const [volume, active] = await Promise.all([
+      exec(["lvs", "--noheadings", lv]),
+      exec(["systemctl", "is-active", service])
+    ]);
+    if (volume.exitCode === 0 || active.exitCode === 0) {
+      throw new MetalProvisionError("guest runtime exists without owned inventory");
+    }
     return {};
+  }
   const currentIdentity = manifest.computeKey === claim.computeKey && manifest.reference === claim.spec.reference && manifest.name === name;
   const legacyPlatformIdentity = claim.bootstrap?.kind === "platform-genesis" && claim.computeKey === `platform:${name}` && claim.spec.reference === `platform:${name}` && manifest.name === name && manifest.disk === `/dev/${profile.volumeGroup}/${name}` && manifest.address === claim.spec.guestAddress && (manifest.unit === `fz-guest@${name}.service` || manifest.unit === `forgezero-guest@${name}.service`);
   if (!currentIdentity && !legacyPlatformIdentity) {
     throw new MetalProvisionError("compute identity conflicts with host inventory");
   }
-  const service = `forgezero-guest@${name}.service`;
-  const unitPath = join(profile.unitDir, service);
   if (existsSync(unitPath))
     await checked(exec, ["systemctl", "disable", "--now", service]);
   else if (legacyPlatformIdentity)
@@ -569,7 +588,6 @@ async function removeMetalGuest(profile, claim, exec) {
   else if ((await exec(["systemctl", "is-active", service])).exitCode === 0) {
     throw new MetalProvisionError("guest unit is active but its owned unit file is missing");
   }
-  const lv = `/dev/${profile.volumeGroup}/${name}`;
   if ((await exec(["lvs", "--noheadings", lv])).exitCode === 0)
     await checked(exec, ["lvremove", "-fy", lv]);
   for (const path of [

package/dist/metal-provision.js

@@ -352,11 +352,10 @@ ${attestationSetup}if [[ ! -x /usr/local/bin/bun ]]; then
   install -m 0755 ${agentBun}/bin/bun /usr/local/bin/bun
   rm -f /run/fz-bun-install
 fi
-if [[ ! -x /usr/local/bin/fz-agent ]] || [[ "$(/usr/local/bin/fz-agent --version 2>/dev/null || true)" != "${profile.agentVersion}" ]]; then
+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}
-  ln -sfn ${agentBun}/bin/fz-agent /usr/local/bin/fz-agent
 fi
-env   FZ_API=${profile.apiUrl}   FZ_AGENT_BIN=/usr/local/bin/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}   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" : ""}
 `;
 }
 function cloudInit(profile, claim, manifest) {
@@ -552,16 +551,36 @@ async function removeMetalGuest(profile, claim, exec) {
     throw new MetalProvisionError("create claim cannot remove a guest");
   const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
   const manifestPath = join(profile.stateDir, `${name}.json`);
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join(profile.unitDir, service);
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
   const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : legacyPlatformManifest(profile, claim, name);
-  if (!manifest)
+  if (!manifest) {
+    const seedBase = join(profile.seedDir, name);
+    const localArtifacts = [
+      unitPath,
+      `${seedBase}-seed.iso`,
+      `${seedBase}-user-data`,
+      `${seedBase}-meta-data`,
+      `${seedBase}-network-config`
+    ];
+    if (localArtifacts.some(existsSync)) {
+      throw new MetalProvisionError("guest artifacts exist without owned inventory");
+    }
+    const [volume, active] = await Promise.all([
+      exec(["lvs", "--noheadings", lv]),
+      exec(["systemctl", "is-active", service])
+    ]);
+    if (volume.exitCode === 0 || active.exitCode === 0) {
+      throw new MetalProvisionError("guest runtime exists without owned inventory");
+    }
     return {};
+  }
   const currentIdentity = manifest.computeKey === claim.computeKey && manifest.reference === claim.spec.reference && manifest.name === name;
   const legacyPlatformIdentity = claim.bootstrap?.kind === "platform-genesis" && claim.computeKey === `platform:${name}` && claim.spec.reference === `platform:${name}` && manifest.name === name && manifest.disk === `/dev/${profile.volumeGroup}/${name}` && manifest.address === claim.spec.guestAddress && (manifest.unit === `fz-guest@${name}.service` || manifest.unit === `forgezero-guest@${name}.service`);
   if (!currentIdentity && !legacyPlatformIdentity) {
     throw new MetalProvisionError("compute identity conflicts with host inventory");
   }
-  const service = `forgezero-guest@${name}.service`;
-  const unitPath = join(profile.unitDir, service);
   if (existsSync(unitPath))
     await checked(exec, ["systemctl", "disable", "--now", service]);
   else if (legacyPlatformIdentity)
@@ -569,7 +588,6 @@ async function removeMetalGuest(profile, claim, exec) {
   else if ((await exec(["systemctl", "is-active", service])).exitCode === 0) {
     throw new MetalProvisionError("guest unit is active but its owned unit file is missing");
   }
-  const lv = `/dev/${profile.volumeGroup}/${name}`;
   if ((await exec(["lvs", "--noheadings", lv])).exitCode === 0)
     await checked(exec, ["lvremove", "-fy", lv]);
   for (const path of [

package/dist/migration-pull.js

@@ -15,8 +15,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";

package/dist/node-vault.js

@@ -135,8 +135,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";
@@ -196,7 +209,7 @@ function projectVaultCoordinate(key) {
 function tenantNodeApiUrl(apiUrl, tenantSlug) {
   if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(tenantSlug))
     throw new Error("tenant slug is malformed");
-  const url = new URL(apiUrl);
+  const url = signedNodeApiUrl(apiUrl);
   url.pathname = `/api/t/${encodeURIComponent(tenantSlug)}`;
   url.search = "";
   url.hash = "";

package/dist/provision.d.ts

@@ -128,6 +128,7 @@ export declare const VAULT_GROUP = "forgezero-vault";
 export declare const LIFECYCLE_GROUP = "forgezero-lifecycle";
 export declare const DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
 export declare const AGENT_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-agent.socket";
+export declare const AGENT_SOCKET_PROXY_UNIT_PATH = "/etc/systemd/system/forgezero-agent-proxy.service";
 export declare const DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
 export declare const ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
 export declare const LIFECYCLE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-lifecycle-helper.service";
@@ -146,6 +147,13 @@ export declare function agentUpdateHelperUnit(options: Pick<UnitOptions, 'binPat
  * terminal, and it works identically on platform and tenant computes.
  */
 export declare function agentSocketUnit(options: Pick<UnitOptions, 'socketPath'>): string;
+/**
+ * Bun does not support inheriting systemd's listening file descriptor. Keep
+ * PID 1 as the owner of the stable application socket and let systemd's small,
+ * credential-free proxy bridge it to the Agent-owned backend Unix socket.
+ */
+export declare function agentSocketProxyUnit(options: Pick<UnitOptions, 'socketPath' | 'user'>): string;
+export declare function agentBackendSocketPath(publicSocketPath: string): string;
 export declare function warpConfigUnit(options: Pick<UnitOptions, 'binPath' | 'warpOrganization' | 'warpClientIdCredentialPath' | 'warpClientSecretCredentialPath'>): string;
 export declare function warpServiceDropIn(): string;
 export declare function lifecycleHelperUnit(options: Pick<UnitOptions, 'binPath' | 'lifecycleProfilePath' | 'lifecycleHelperSocketPath'>): string;

package/dist/provision.js

@@ -554,7 +554,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION2 = "0.1.27";
+var VERSION2 = "0.1.29";
 
 // src/provision.ts
 function atLeast(version, floor) {
@@ -603,6 +603,7 @@ var VAULT_GROUP = "forgezero-vault";
 var LIFECYCLE_GROUP = "forgezero-lifecycle";
 var DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
 var AGENT_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-agent.socket";
+var AGENT_SOCKET_PROXY_UNIT_PATH = "/etc/systemd/system/forgezero-agent-proxy.service";
 var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
 var ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
 var LIFECYCLE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-lifecycle-helper.service";
@@ -692,17 +693,55 @@ SocketGroup=${VAULT_GROUP}
 SocketMode=0660
 DirectoryMode=0750
 RemoveOnStop=true
-Service=forgezero-agent.service
+Service=forgezero-agent-proxy.service
 
 [Install]
 WantedBy=sockets.target
 `;
 }
+function agentSocketProxyUnit(options) {
+  const backend = agentBackendSocketPath(options.socketPath);
+  const user = options.user ?? "forgezero";
+  return `[Unit]
+Description=ForgeZero application Vault socket proxy
+Documentation=https://www.forgezero.net/docs/agent
+Requires=forgezero-agent.service
+After=forgezero-agent.service
+
+[Service]
+User=${user}
+Group=${VAULT_GROUP}
+ExecStart=/usr/lib/systemd/systemd-socket-proxyd ${backend}
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+RestrictAddressFamilies=AF_UNIX
+`;
+}
+function agentBackendSocketPath(publicSocketPath) {
+  const socket = systemdPath(publicSocketPath, "agent socket");
+  const backend = `${socket}.backend`;
+  if (Buffer.byteLength(backend) > 100)
+    throw new Error("agent socket path is too long for a Unix socket");
+  return backend;
+}
 var systemdPath = (value, label) => {
   if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
     throw new Error(`invalid ${label} path`);
   return value;
 };
+var awaitSocketCommand = (path) => {
+  const socket = systemdPath(path, "readiness socket");
+  return `for attempt in $(seq 1 100); do test -S ${socket} && exit 0; sleep 0.1; done; exit 1`;
+};
 var validNodeHostname = (value) => !value || value.length <= 253 && value === value.toLowerCase() && value.split(".").length >= 3 && value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
 function warpConfigUnit(options) {
   if (!options.warpOrganization || !/^[a-z0-9][a-z0-9-]{0,62}$/i.test(options.warpOrganization)) {
@@ -941,7 +980,7 @@ function agentUnit(options) {
     }
   }
   const environment = [
-    `FZ_SOCKET_PATH=${options.socketPath}`,
+    `FZ_SOCKET_PATH=${agentBackendSocketPath(options.socketPath)}`,
     `FZ_CONTROL_SOCKET=${controlSocketPath}`,
     `FZ_SEED_CREDENTIAL=agent-seed`,
     `FZ_AGENT_MODE=${options.mode}`,
@@ -1021,7 +1060,6 @@ Type=simple
 User=${user}
 Group=${VAULT_GROUP}
 ${deploymentGroup}
-Sockets=forgezero-agent.socket
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
 ${gitCredential}${projectCredentials}${projectCredentials ? `
 ` : ""}${snpPrepare}ExecStart=${bin}
@@ -1109,6 +1147,7 @@ function planProvision(options) {
     unit: agentUnit({ ...options, mode, lifecycleProfilePath, lifecycleHelperSocketPath }),
     auxiliaryUnits: [
       { 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) },
       ...deploymentEnabled ? [
         { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) },
@@ -1184,6 +1223,10 @@ function planProvision(options) {
         label: "credential directory",
         command: `install -d -o root -g root -m 0700 ${credentialDir}`
       },
+      {
+        label: "Agent state directory",
+        command: "install -d -o root -g root -m 0750 /var/lib/forgezero"
+      },
       {
         label: "encrypted node identity",
         command: `test -s ${seedCredentialPath} || { ` + `openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\\n' | ` + `systemd-creds encrypt --name=agent-seed - ${seedCredentialPath}; ` + `chmod 0400 ${seedCredentialPath}; }`
@@ -1218,8 +1261,8 @@ function planProvision(options) {
         command: "systemctl disable --now forgezero-deploy-runner.socket 2>/dev/null || true; rm -f /etc/systemd/system/forgezero-deploy-runner.socket; systemctl daemon-reload"
       }] : [],
       {
-        label: "enable and start",
-        command: `systemctl enable --now ${[
+        label: "enable and converge services",
+        command: `systemctl enable ${[
           "forgezero-agent.socket",
           "forgezero-agent-update-helper.service",
           ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
@@ -1227,25 +1270,32 @@ function planProvision(options) {
           ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
           ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : [],
           "forgezero-agent.service"
-        ].join(" ")}`
+        ].join(" ")}; systemctl reset-failed forgezero-agent.service || true; systemctl restart ${[
+          "forgezero-agent-update-helper.service",
+          ...deploymentEnabled ? ["forgezero-deploy-runner.service", "forgezero-software-helper.service"] : [],
+          ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
+          ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
+          ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : []
+        ].join(" ")}; systemctl restart forgezero-agent.socket; systemctl reset-failed forgezero-agent.service || true; systemctl restart forgezero-agent.service`
       },
       ...enrolmentEnabled ? [{
         label: "prove the compute binding is durable",
         command: `test -s ${enrolStatePath}`
       }] : [],
       { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
-      { label: "prove the vault socket exists", command: `test -S ${options.socketPath}` },
-      { label: "prove the Agent update helper exists", command: `test -S ${DEFAULT_AGENT_UPDATE_SOCKET}` },
+      { label: "prove the public Vault socket exists", command: awaitSocketCommand(options.socketPath) },
+      { label: "prove the Agent Vault backend exists", command: awaitSocketCommand(agentBackendSocketPath(options.socketPath)) },
+      { label: "prove the Agent update helper exists", command: awaitSocketCommand(DEFAULT_AGENT_UPDATE_SOCKET) },
       ...deploymentEnabled ? [{
         label: "prove the deployment runner socket exists",
-        command: `test -S ${DEPLOYMENT_RUNNER_SOCKET}`
+        command: awaitSocketCommand(DEPLOYMENT_RUNNER_SOCKET)
       }, {
         label: "prove the software strategy helper socket exists",
-        command: `test -S ${DEFAULT_SOFTWARE_HELPER_SOCKET}`
+        command: awaitSocketCommand(DEFAULT_SOFTWARE_HELPER_SOCKET)
       }] : [],
       ...lifecycleEnabled ? [{
         label: "prove the lifecycle helper socket exists",
-        command: `test -S ${lifecycleHelperSocketPath}`
+        command: awaitSocketCommand(lifecycleHelperSocketPath)
       }] : [],
       ...warpEnabled ? [{
         label: "prove Cloudflare WARP is connected",
@@ -1253,7 +1303,7 @@ function planProvision(options) {
       }] : [],
       ...options.repository ? [{
         label: "prove the deployment control socket exists",
-        command: `test -S ${options.controlSocketPath ?? "/run/forgezero/control.sock"}`
+        command: awaitSocketCommand(options.controlSocketPath ?? "/run/forgezero/control.sock")
       }] : []
     ]
   };
@@ -1271,7 +1321,9 @@ export {
   agentUpdateHelperUnit,
   agentUnit,
   agentSocketUnit,
+  agentSocketProxyUnit,
   agentEnrolmentUnit,
+  agentBackendSocketPath,
   WARP_SERVICE_DROP_IN_PATH,
   WARP_CONFIG_UNIT_PATH,
   VAULT_GROUP,
@@ -1285,5 +1337,6 @@ export {
   DEPLOYMENT_RUNNER_SOCKET,
   DEPLOYMENT_GROUP,
   CAPABILITY_CHECKS,
-  AGENT_SOCKET_UNIT_PATH
+  AGENT_SOCKET_UNIT_PATH,
+  AGENT_SOCKET_PROXY_UNIT_PATH
 };

package/dist/provisioning-pull.js

@@ -15,8 +15,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";

package/dist/signed-node-http.d.ts

@@ -10,5 +10,15 @@ export declare class SignedNodeHttpError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/**
+ * Validate the one origin every outbound Agent client shares.
+ *
+ * Hybrid request authentication and a sealed response protect the payload, but
+ * they do not hide routing metadata. Accepting plain HTTP for a remote API
+ * would still expose node identity, operation timing and ciphertext to an
+ * on-path observer. Loopback HTTP remains available for local development and
+ * for a supervised same-host API; production traffic must use HTTPS.
+ */
+export declare function signedNodeApiUrl(value: string): URL;
 /** One implementation of the hybrid-signed machine HTTP contract. */
 export declare function postSignedNode<T>(options: SignedNodeHttpOptions, path: string, body: object): Promise<T>;

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.27";
+export declare const VERSION = "0.1.29";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"//": "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.27",
+	"version": "0.1.29",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",