@forgezero/agent 0.1.28 → 0.1.30

package/dist/project-context.d.ts

@@ -0,0 +1,37 @@
+export declare const PROJECT_CONTEXT_VERSION: 1;
+export interface ProjectTruthSource {
+    area: string;
+    path: string;
+    description: string;
+}
+export interface ProjectContextManifest {
+    schemaVersion: typeof PROJECT_CONTEXT_VERSION;
+    name: string;
+    purpose: string;
+    truth: readonly ProjectTruthSource[];
+    readFirst: readonly string[];
+    verify: readonly string[];
+    rules: readonly string[];
+    /** Files or directories that are generated, historical, or otherwise not authoritative. */
+    nonAuthoritative: readonly string[];
+}
+export interface ContextFile {
+    path: string;
+    content: string;
+}
+export interface ContextCheck {
+    ok: boolean;
+    problems: string[];
+}
+export declare class ProjectContextError extends Error {
+    constructor(message: string);
+}
+export declare function parseProjectContext(value: unknown): ProjectContextManifest;
+export declare function defaultProjectContext(root?: string): ProjectContextManifest;
+export declare function renderProjectContext(manifest: ProjectContextManifest): string;
+export declare function projectContextFiles(manifestInput: ProjectContextManifest): ContextFile[];
+export declare function initializeProjectContext(rootInput: string, manifestInput?: ProjectContextManifest, options?: {
+    force?: boolean;
+}): ContextFile[];
+export declare function syncProjectContext(rootInput: string): ContextFile[];
+export declare function checkProjectContext(rootInput: string): ContextCheck;

package/dist/project-context.js

@@ -0,0 +1,266 @@
+// @bun
+// src/project-context.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+var PROJECT_CONTEXT_VERSION = 1;
+var GENERATED = "<!-- Generated by @forgezero/agent project context. Edit .forgezero/project.json, then run `fz project sync`. -->";
+
+class ProjectContextError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProjectContextError";
+  }
+}
+var text = (value, where) => {
+  if (typeof value !== "string" || !value.trim() || /[\r\0]/.test(value)) {
+    throw new ProjectContextError(`${where} must be non-empty text.`);
+  }
+  return value.trim();
+};
+var relativePath = (value, where) => {
+  const path = text(value, where);
+  if (path.startsWith("/") || path.split("/").includes("..")) {
+    throw new ProjectContextError(`${where} must stay inside the repository.`);
+  }
+  return path.replace(/^\.\//, "");
+};
+var stringList = (value, where, paths = false) => {
+  if (!Array.isArray(value) || value.length > 128) {
+    throw new ProjectContextError(`${where} must be an array of at most 128 entries.`);
+  }
+  const items = value.map((item, index) => paths ? relativePath(item, `${where}[${index}]`) : text(item, `${where}[${index}]`));
+  if (new Set(items).size !== items.length)
+    throw new ProjectContextError(`${where} must not contain duplicates.`);
+  return items;
+};
+function parseProjectContext(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ProjectContextError("project context must be an object.");
+  }
+  const row = value;
+  const allowed = ["schemaVersion", "name", "purpose", "truth", "readFirst", "verify", "rules", "nonAuthoritative"];
+  const unknown = Object.keys(row).filter((key) => !allowed.includes(key));
+  if (unknown.length)
+    throw new ProjectContextError(`project context contains unknown field(s): ${unknown.join(", ")}.`);
+  if (row.schemaVersion !== PROJECT_CONTEXT_VERSION) {
+    throw new ProjectContextError(`project context schemaVersion must be ${PROJECT_CONTEXT_VERSION}.`);
+  }
+  if (!Array.isArray(row.truth) || row.truth.length === 0 || row.truth.length > 64) {
+    throw new ProjectContextError("project context truth must contain from 1 to 64 sources.");
+  }
+  const truth = row.truth.map((item, index) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new ProjectContextError(`truth[${index}] must be an object.`);
+    }
+    const source = item;
+    if (Object.keys(source).some((key) => !["area", "path", "description"].includes(key))) {
+      throw new ProjectContextError(`truth[${index}] contains an unknown field.`);
+    }
+    return {
+      area: text(source.area, `truth[${index}].area`),
+      path: relativePath(source.path, `truth[${index}].path`),
+      description: text(source.description, `truth[${index}].description`)
+    };
+  });
+  const areas = truth.map((source) => source.area);
+  if (new Set(areas).size !== areas.length)
+    throw new ProjectContextError("project context truth areas must be unique.");
+  return {
+    schemaVersion: PROJECT_CONTEXT_VERSION,
+    name: text(row.name, "project context name"),
+    purpose: text(row.purpose, "project context purpose"),
+    truth,
+    readFirst: stringList(row.readFirst, "project context readFirst", true),
+    verify: stringList(row.verify, "project context verify"),
+    rules: stringList(row.rules, "project context rules"),
+    nonAuthoritative: stringList(row.nonAuthoritative, "project context nonAuthoritative", true)
+  };
+}
+function defaultProjectContext(root = process.cwd()) {
+  let name = root.split("/").filter(Boolean).at(-1) ?? "project";
+  let verify = ["npm test"];
+  const manifestPath = join(root, "package.json");
+  if (existsSync(manifestPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(manifestPath, "utf8"));
+      name = pkg.name ?? name;
+      const runner = existsSync(join(root, "bun.lock")) ? "bun run" : "npm run";
+      verify = ["check", "test", "build"].filter((script) => pkg.scripts?.[script]).map((script) => `${runner} ${script}`);
+      if (verify.length === 0)
+        verify = [existsSync(join(root, "bun.lock")) ? "bun test" : "npm test"];
+    } catch {}
+  }
+  return {
+    schemaVersion: PROJECT_CONTEXT_VERSION,
+    name,
+    purpose: "Describe the product outcome here; implementation details belong in the truth sources below.",
+    truth: [
+      { area: "architecture", path: "docs/architecture.md", description: "Current system boundaries and decisions." },
+      { area: "progress", path: "docs/progress.md", description: "Evidence-backed delivery state and next work." }
+    ],
+    readFirst: [".forgezero/PROJECT.md"],
+    verify,
+    rules: [
+      "Inspect the current worktree before editing and preserve unrelated changes.",
+      "Update a truth source instead of copying architecture or progress into another document.",
+      "Never report a feature as complete without running its declared verification."
+    ],
+    nonAuthoritative: ["audit/"]
+  };
+}
+function renderProjectContext(manifest) {
+  const truth = manifest.truth.map((source) => `| ${source.area} | \`${source.path}\` | ${source.description} |`).join(`
+`);
+  return `${GENERATED}
+# ${manifest.name} \u2014 project context
+
+${manifest.purpose}
+
+## Read first
+
+${manifest.readFirst.map((path) => `- \`${path}\``).join(`
+`) || "- No additional entry points."}
+
+## Sources of truth
+
+| Area | Path | Authority |
+|---|---|---|
+${truth}
+
+If two files disagree, the file named in this table wins. Fix or regenerate the
+other file in the same change. Conversation memory, audit snapshots and generated
+output never override repository truth.
+
+## Project rules
+
+${manifest.rules.map((rule) => `- ${rule}`).join(`
+`) || "- No additional project rules."}
+
+## Verification
+
+${manifest.verify.map((command) => `- \`${command}\``).join(`
+`) || "- No verification command declared."}
+
+## Non-authoritative material
+
+${manifest.nonAuthoritative.map((path) => `- \`${path}\``).join(`
+`) || "- None declared."}
+
+Tools, skills and AI vendors may change. They are execution aids, not memory.
+Persist every accepted decision and status change in the source of truth that
+owns it, then run \`fz project check\` before handoff.
+`;
+}
+var adapter = (name) => `${GENERATED}
+# ${name} project instructions
+
+Read \`.forgezero/PROJECT.md\` completely before acting. It is generated from
+\`.forgezero/project.json\`, the vendor-neutral project context. Follow every
+source of truth and verification command it names.
+
+Do not treat this adapter, conversation memory, an audit report, generated
+output, a tool, or a skill as architectural authority. When work changes an
+accepted decision or delivery state, update the named Git source in the same
+change and run \`fz project check\`.
+`;
+function projectContextFiles(manifestInput) {
+  const manifest = parseProjectContext(manifestInput);
+  return [
+    { path: ".forgezero/PROJECT.md", content: renderProjectContext(manifest) },
+    { path: "AGENTS.md", content: adapter("AI agent") },
+    { path: "CLAUDE.md", content: adapter("Claude") },
+    { path: "GEMINI.md", content: adapter("Gemini") },
+    { path: ".github/copilot-instructions.md", content: adapter("GitHub Copilot") },
+    { path: ".cursor/rules/project-context.mdc", content: `${GENERATED}
+---
+description: Repository source-of-truth contract
+alwaysApply: true
+---
+
+${adapter("Cursor").replace(`${GENERATED}
+`, "")}` }
+  ];
+}
+var atomicWrite = (path, content) => {
+  mkdirSync(dirname(path), { recursive: true });
+  const next = `${path}.${process.pid}.next`;
+  writeFileSync(next, content, { mode: 420 });
+  renameSync(next, path);
+};
+function initializeProjectContext(rootInput, manifestInput = defaultProjectContext(rootInput), options = {}) {
+  const root = resolve(rootInput);
+  const manifest = parseProjectContext(manifestInput);
+  const manifestPath = join(root, ".forgezero", "project.json");
+  const files = projectContextFiles(manifest);
+  const collisions = [manifestPath, ...files.map((file) => join(root, file.path))].filter((path) => {
+    if (!existsSync(path))
+      return false;
+    if (path === manifestPath)
+      return true;
+    return !readFileSync(path, "utf8").startsWith(GENERATED);
+  });
+  if (collisions.length && !options.force) {
+    throw new ProjectContextError(`refusing to replace existing project context: ${collisions.join(", ")}`);
+  }
+  atomicWrite(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  for (const file of files)
+    atomicWrite(join(root, file.path), file.content);
+  return files;
+}
+function syncProjectContext(rootInput) {
+  const root = resolve(rootInput);
+  const manifestPath = join(root, ".forgezero", "project.json");
+  if (!existsSync(manifestPath))
+    throw new ProjectContextError("No .forgezero/project.json. Run `fz project init`.");
+  const manifest = parseProjectContext(JSON.parse(readFileSync(manifestPath, "utf8")));
+  const files = projectContextFiles(manifest);
+  for (const file of files) {
+    const path = join(root, file.path);
+    if (existsSync(path) && !readFileSync(path, "utf8").startsWith(GENERATED)) {
+      throw new ProjectContextError(`refusing to replace non-generated adapter: ${file.path}`);
+    }
+    atomicWrite(path, file.content);
+  }
+  return files;
+}
+function checkProjectContext(rootInput) {
+  const root = resolve(rootInput);
+  const manifestPath = join(root, ".forgezero", "project.json");
+  if (!existsSync(manifestPath))
+    return { ok: false, problems: ["missing .forgezero/project.json"] };
+  let manifest;
+  try {
+    manifest = parseProjectContext(JSON.parse(readFileSync(manifestPath, "utf8")));
+  } catch (cause) {
+    return { ok: false, problems: [cause instanceof Error ? cause.message : String(cause)] };
+  }
+  const problems = [];
+  for (const source of manifest.truth) {
+    if (!existsSync(join(root, source.path)))
+      problems.push(`missing truth source: ${source.path}`);
+  }
+  for (const path of manifest.readFirst) {
+    if (!existsSync(join(root, path)))
+      problems.push(`missing read-first file: ${path}`);
+  }
+  for (const file of projectContextFiles(manifest)) {
+    const path = join(root, file.path);
+    if (!existsSync(path))
+      problems.push(`missing generated adapter: ${file.path}`);
+    else if (readFileSync(path, "utf8") !== file.content)
+      problems.push(`drifted generated adapter: ${file.path}`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+export {
+  syncProjectContext,
+  renderProjectContext,
+  projectContextFiles,
+  parseProjectContext,
+  initializeProjectContext,
+  defaultProjectContext,
+  checkProjectContext,
+  ProjectContextError,
+  PROJECT_CONTEXT_VERSION
+};

package/dist/provision.d.ts

@@ -83,7 +83,7 @@ export interface UnitOptions {
     controlSocketPath?: string;
     repository?: string;
     branch?: string;
-    role?: string;
+    profile?: string;
     deployRoot?: string;
     publicApiUrl?: string;
     /** Non-secret phase values, named explicitly instead of inheriting the unit environment. */
@@ -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

@@ -361,6 +361,16 @@ import { readFileSync as readFileSync2 } from "node:fs";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+var OS_CATALOG = [
+  { id: "ubuntu", version: "26.04", architecture: "x64", status: "active" }
+];
+var SOFTWARE_CATALOG = [
+  { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+];
 var UBUNTU_2604_X64 = [
   {
     requirement: { id: "bun", version: "1.3.14" },
@@ -399,7 +409,7 @@ function observeSoftwareHost(osRelease = readFileSync2("/etc/os-release", "utf8"
     architecture
   };
 }
-function validateSoftwareRequirements(value) {
+function validateSoftwareRequirements(value, options = {}) {
   if (!Array.isArray(value) || value.length > 32)
     throw new Error("software requirements must be an array of at most 32 entries");
   const seen = new Set;
@@ -417,13 +427,18 @@ function validateSoftwareRequirements(value) {
     if (seen.has(requirement.id))
       throw new Error(`duplicate software requirement: ${requirement.id}`);
     seen.add(requirement.id);
+    const catalog = SOFTWARE_CATALOG.find((candidate) => candidate.id === requirement.id && candidate.version === requirement.version);
+    if (!catalog || catalog.status === "retired" || options.channel !== "development" && catalog.status !== "active") {
+      throw new Error(`software requirement is not available for ${options.channel ?? "production"}: ${requirement.id}@${requirement.version}`);
+    }
     return requirement;
   });
 }
 async function ensureSoftwareRequirements(requirementsInput, options) {
   const requirements = validateSoftwareRequirements(requirementsInput);
   const observation = options.observation ?? observeSoftwareHost();
-  if (observation.os.id !== "ubuntu" || observation.os.versionId !== "26.04" || observation.architecture !== "x64") {
+  const os = OS_CATALOG.find((candidate) => candidate.id === observation.os.id && candidate.version === observation.os.versionId && candidate.architecture === observation.architecture);
+  if (!os || os.status !== "active") {
     throw new Error(`unsupported software strategy: ${observation.os.id} ${observation.os.versionId} ${observation.architecture}`);
   }
   const results = [];
@@ -554,7 +569,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION2 = "0.1.28";
+var VERSION2 = "0.1.30";
 
 // src/provision.ts
 function atLeast(version, floor) {
@@ -603,6 +618,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 +708,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 +995,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}`,
@@ -954,7 +1008,7 @@ function agentUnit(options) {
     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.role ? `FZ_DEPLOY_ROLE=${options.role}` : 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_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}` : null,
@@ -1021,7 +1075,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 +1162,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 +1238,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 +1276,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 +1285,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 +1318,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 +1336,9 @@ export {
   agentUpdateHelperUnit,
   agentUnit,
   agentSocketUnit,
+  agentSocketProxyUnit,
   agentEnrolmentUnit,
+  agentBackendSocketPath,
   WARP_SERVICE_DROP_IN_PATH,
   WARP_CONFIG_UNIT_PATH,
   VAULT_GROUP,
@@ -1285,5 +1352,6 @@ export {
   DEPLOYMENT_RUNNER_SOCKET,
   DEPLOYMENT_GROUP,
   CAPABILITY_CHECKS,
-  AGENT_SOCKET_UNIT_PATH
+  AGENT_SOCKET_UNIT_PATH,
+  AGENT_SOCKET_PROXY_UNIT_PATH
 };

package/dist/software-helper.js

@@ -3,6 +3,16 @@ import { readFileSync } from "node:fs";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+var OS_CATALOG = [
+  { id: "ubuntu", version: "26.04", architecture: "x64", status: "active" }
+];
+var SOFTWARE_CATALOG = [
+  { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+];
 var UBUNTU_2604_X64 = [
   {
     requirement: { id: "bun", version: "1.3.14" },
@@ -41,7 +51,7 @@ function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8")
     architecture
   };
 }
-function validateSoftwareRequirements(value) {
+function validateSoftwareRequirements(value, options = {}) {
   if (!Array.isArray(value) || value.length > 32)
     throw new Error("software requirements must be an array of at most 32 entries");
   const seen = new Set;
@@ -59,13 +69,18 @@ function validateSoftwareRequirements(value) {
     if (seen.has(requirement.id))
       throw new Error(`duplicate software requirement: ${requirement.id}`);
     seen.add(requirement.id);
+    const catalog = SOFTWARE_CATALOG.find((candidate) => candidate.id === requirement.id && candidate.version === requirement.version);
+    if (!catalog || catalog.status === "retired" || options.channel !== "development" && catalog.status !== "active") {
+      throw new Error(`software requirement is not available for ${options.channel ?? "production"}: ${requirement.id}@${requirement.version}`);
+    }
     return requirement;
   });
 }
 async function ensureSoftwareRequirements(requirementsInput, options) {
   const requirements = validateSoftwareRequirements(requirementsInput);
   const observation = options.observation ?? observeSoftwareHost();
-  if (observation.os.id !== "ubuntu" || observation.os.versionId !== "26.04" || observation.architecture !== "x64") {
+  const os = OS_CATALOG.find((candidate) => candidate.id === observation.os.id && candidate.version === observation.os.versionId && candidate.architecture === observation.architecture);
+  if (!os || os.status !== "active") {
     throw new Error(`unsupported software strategy: ${observation.os.id} ${observation.os.versionId} ${observation.architecture}`);
   }
   const results = [];

package/dist/software.d.ts

@@ -1,8 +1,25 @@
+export type CatalogStatus = 'testing' | 'active' | 'retired';
+export type DeploymentChannel = 'development' | 'production';
+export type SoftwareId = 'bun' | 'nginx' | 'arangodb' | 'cloudflared' | 'ufw';
 /** Repository input is a catalogue coordinate, never a root command. */
 export interface SoftwareRequirement {
-    id: 'bun' | 'nginx' | 'arangodb' | 'cloudflared' | 'ufw';
+    id: SoftwareId;
     version: string;
 }
+export interface SoftwareCatalogEntry extends SoftwareRequirement {
+    status: CatalogStatus;
+    os: 'ubuntu';
+    osVersion: '26.04';
+    architecture: 'x64';
+    /** What promotes this coordinate beyond an unreviewed candidate. */
+    evidence: 'reviewed-strategy-and-tests';
+}
+export interface OsCatalogEntry {
+    id: 'ubuntu';
+    version: '26.04';
+    architecture: 'x64';
+    status: CatalogStatus;
+}
 export interface SoftwareObservation {
     os: {
         id: string;
@@ -15,8 +32,13 @@ export interface SoftwareCommandResult {
     output: string;
 }
 export type SoftwareExec = (command: string) => Promise<SoftwareCommandResult>;
+/** Public, command-free catalog. Root strategies remain private below. */
+export declare const OS_CATALOG: readonly OsCatalogEntry[];
+export declare const SOFTWARE_CATALOG: readonly SoftwareCatalogEntry[];
 export declare function observeSoftwareHost(osRelease?: string, architecture?: NodeJS.Architecture): SoftwareObservation;
-export declare function validateSoftwareRequirements(value: unknown): SoftwareRequirement[];
+export declare function validateSoftwareRequirements(value: unknown, options?: {
+    channel?: DeploymentChannel;
+}): SoftwareRequirement[];
 export declare function ensureSoftwareRequirements(requirementsInput: unknown, options: {
     observation?: SoftwareObservation;
     exec: SoftwareExec;