@forgezero/agent 0.1.28 → 0.1.30

package/dist/fz.js

@@ -4871,8 +4871,8 @@ async function spawnWith(command, env, report = () => {}) {
 
 // src/cli/index.ts
 init_dist();
-import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
-import { dirname } from "path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/agent-update.ts
@@ -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.28";
+var VERSION2 = "0.1.30";
 
 // 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}`,
@@ -5324,7 +5363,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,
@@ -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")
       }] : []
     ]
   };
@@ -9225,6 +9275,261 @@ async function resolveIdentity(selector, socketPath) {
   return chosen;
 }
 
+// src/project-context.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname, join as join2, 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 = join2(root, "package.json");
+  if (existsSync(manifestPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(manifestPath, "utf8"));
+      name = pkg.name ?? name;
+      const runner = existsSync(join2(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(join2(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 = join2(root, ".forgezero", "project.json");
+  const files = projectContextFiles(manifest);
+  const collisions = [manifestPath, ...files.map((file) => join2(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(join2(root, file.path), file.content);
+  return files;
+}
+function syncProjectContext(rootInput) {
+  const root = resolve(rootInput);
+  const manifestPath = join2(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 = join2(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 = join2(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(join2(root, source.path)))
+      problems.push(`missing truth source: ${source.path}`);
+  }
+  for (const path of manifest.readFirst) {
+    if (!existsSync(join2(root, path)))
+      problems.push(`missing read-first file: ${path}`);
+  }
+  for (const file of projectContextFiles(manifest)) {
+    const path = join2(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 };
+}
+
 // src/cli/index.ts
 var DEFAULT_MODE = THRESHOLD_MODES[0].id;
 var RECOMMENDED_MODE = (THRESHOLD_MODES.find((mode) => mode.recommended) ?? THRESHOLD_MODES[0]).id;
@@ -9240,7 +9545,9 @@ function parseOptions(argv) {
     mode: DEFAULT_MODE,
     user: process.env.FZ_USER ?? "operator",
     email: process.env.FZ_EMAIL ?? "operator@localhost",
-    preserveEnv: false
+    preserveEnv: false,
+    projectRoot: process.cwd(),
+    force: false
   };
   const positional = [];
   for (let index = 0;index < argv.length; index += 1) {
@@ -9259,6 +9566,14 @@ function parseOptions(argv) {
       options.enrol = true;
     else if (token === "--preserve-env")
       options.preserveEnv = true;
+    else if (token === "--root")
+      options.projectRoot = argv[++index] ?? options.projectRoot;
+    else if (token === "--name")
+      options.projectName = argv[++index];
+    else if (token === "--purpose")
+      options.projectPurpose = argv[++index];
+    else if (token === "--force")
+      options.force = true;
     else if (token === "--key")
       options.key = argv[++index];
     else if (token === "--mode")
@@ -9277,15 +9592,15 @@ function parseOptions(argv) {
   return { command: positional[0] ?? "help", args: positional.slice(1), options };
 }
 var out = {
-  line: (text = "") => process.stdout.write(`${text}
+  line: (text2 = "") => process.stdout.write(`${text2}
 `),
-  step: (text) => process.stdout.write(`  ${text}
+  step: (text2) => process.stdout.write(`  ${text2}
 `),
-  warn: (text) => process.stderr.write(`  ! ${text}
+  warn: (text2) => process.stderr.write(`  ! ${text2}
 `),
-  fail: (text) => process.stderr.write(`  \u2717 ${text}
+  fail: (text2) => process.stderr.write(`  \u2717 ${text2}
 `),
-  ok: (text) => process.stdout.write(`  \u2713 ${text}
+  ok: (text2) => process.stdout.write(`  \u2713 ${text2}
 `)
 };
 var sessionCookie = null;
@@ -9440,7 +9755,7 @@ async function cmdAgent(options, args) {
     controlSocketPath: process.env.FZ_CONTROL_SOCKET,
     repository: process.env.FZ_DEPLOY_REPO,
     branch: process.env.FZ_DEPLOY_BRANCH,
-    role: process.env.FZ_DEPLOY_ROLE,
+    profile: process.env.FZ_DEPLOY_PROFILE,
     deployRoot: process.env.FZ_DEPLOY_ROOT,
     publicApiUrl: process.env.FZ_PUBLIC_API_URL,
     deploymentEnvironment: parseAssignments(process.env.FZ_DEPLOY_ENV),
@@ -9490,17 +9805,17 @@ async function cmdAgent(options, args) {
     return 0;
   }
   try {
-    writeFileSync(plan.unitPath, plan.unit, { mode: 420 });
+    writeFileSync2(plan.unitPath, plan.unit, { mode: 420 });
     out.ok(`Wrote ${plan.unitPath}`);
     for (const auxiliary of plan.auxiliaryUnits) {
-      mkdirSync(dirname(auxiliary.path), { recursive: true, mode: 493 });
-      writeFileSync(auxiliary.path, auxiliary.unit, { mode: 420 });
+      mkdirSync2(dirname2(auxiliary.path), { recursive: true, mode: 493 });
+      writeFileSync2(auxiliary.path, auxiliary.unit, { mode: 420 });
       out.ok(`Wrote ${auxiliary.path}`);
     }
     if (options.enrol) {
-      if (existsSync(enrolTokenSourcePath)) {
+      if (existsSync2(enrolTokenSourcePath)) {
         const source = statSync(enrolTokenSourcePath);
-        const token = readFileSync(enrolTokenSourcePath, "utf8").trim();
+        const token = readFileSync2(enrolTokenSourcePath, "utf8").trim();
         if (!source.isFile() || (source.mode & 511) !== 384 || source.uid !== 0) {
           throw new Error("The preloaded enrolment token must be a root-owned 0600 file in /run.");
         }
@@ -9513,7 +9828,7 @@ async function cmdAgent(options, args) {
         if (await prompt.exited !== 0 || !/^fze_[A-Za-z0-9_-]{40,100}$/.test(token)) {
           throw new Error("A valid fze_ enrolment token was not provided.");
         }
-        writeFileSync(enrolTokenSourcePath, `${token}
+        writeFileSync2(enrolTokenSourcePath, `${token}
 `, { mode: 384, flag: "wx" });
       }
     }
@@ -9524,7 +9839,7 @@ async function cmdAgent(options, args) {
     out.line();
     out.line("  Add this machine-specific PUBLIC key as a read-only deploy key:");
     out.line();
-    out.line(`  ${readFileSync(gitPublicKeyPath, "utf8").trim()}`);
+    out.line(`  ${readFileSync2(gitPublicKeyPath, "utf8").trim()}`);
     out.line();
     return 0;
   } catch (cause) {
@@ -9641,6 +9956,43 @@ Is fz-agent running on this machine? \`fz agent install --apply\`.`);
     out.line(describeInjection(merged, Object.keys(secrets).length));
   return spawnWith(command, merged.env, (line) => out.line(line));
 }
+function cmdProject(options, args) {
+  const operation = args[0] ?? "check";
+  try {
+    if (operation === "init") {
+      const manifest = defaultProjectContext(options.projectRoot);
+      if (options.projectName)
+        manifest.name = options.projectName;
+      if (options.projectPurpose)
+        manifest.purpose = options.projectPurpose;
+      const files = initializeProjectContext(options.projectRoot, manifest, { force: options.force });
+      out.ok(`Project context initialized; ${files.length} generated adapters now share one Git source.`);
+      out.step("Edit .forgezero/project.json, create every named truth source, then run `fz project sync`.");
+      return 0;
+    }
+    if (operation === "sync") {
+      const files = syncProjectContext(options.projectRoot);
+      out.ok(`Synchronized ${files.length} AI adapters from .forgezero/project.json.`);
+      return 0;
+    }
+    if (operation === "check") {
+      const result = checkProjectContext(options.projectRoot);
+      if (options.json)
+        out.line(JSON.stringify(result, null, 2));
+      else if (result.ok)
+        out.ok("Project context and every AI adapter are in sync.");
+      else
+        for (const problem of result.problems)
+          out.fail(problem);
+      return result.ok ? 0 : 1;
+    }
+    out.fail("Usage: fz project init|sync|check [--root <path>] [--force]");
+    return 2;
+  } catch (cause) {
+    out.fail(cause instanceof Error ? cause.message : String(cause));
+    return 1;
+  }
+}
 function usage() {
   out.line(`
   fz ${VERSION2} \u2014 ForgeZero control surface
@@ -9662,6 +10014,9 @@ function usage() {
     fz agent install        Install the node agent as a systemd service, so
                             applications on this box read secrets through a
                             local socket instead of holding an API key
+    fz project init         Create vendor-neutral, Git-persisted AI context
+    fz project sync         Regenerate Claude/Codex/Gemini/Copilot/Cursor adapters
+    fz project check        Fail when truth sources or generated adapters drift
 
   CEREMONY OPTIONS
     --key <fp|index>        Which agent key to use for custody
@@ -9684,6 +10039,10 @@ function usage() {
     --apply                 Write the unit rather than printing it (root)
     --enrol                Bind this machine with a one-time token prompted
                            securely by systemd (tenant-owned compute)
+    --root <path>          Project root for project init/sync/check
+    --name <name>          Project name during init
+    --purpose <text>       Product outcome during init
+    --force                Init may replace existing AI instruction files
 
   CUSTODY FACTORS
     Every custodian share is sealed TWICE and either envelope alone opens it:
@@ -9712,6 +10071,9 @@ async function runCli() {
     case "agent":
       code = await cmdAgent(options, args);
       break;
+    case "project":
+      code = cmdProject(options, args);
+      break;
     case "genesis":
       code = await cmdGenesis(options);
       break;
@@ -9735,7 +10097,7 @@ async function runCli() {
       usage();
       code = 1;
   }
-  if (args.length > 0 && code === 0 && command !== "agent") {
+  if (args.length > 0 && code === 0 && command !== "agent" && command !== "project") {
     out.warn(`Ignored: ${args.join(" ")}`);
   }
   process.exit(code);

package/dist/index.d.ts

@@ -32,8 +32,8 @@ export type { AgentRelease, StagedAgentRelease, UpdateCommand, UpdateCommandResu
 export { activateAgentRelease, probeAgentSocket, requestAgentUpdate, startAgentUpdateHelper, AGENT_UPDATE_GROUP, AGENT_UPDATE_HELPER_UNIT_PATH, AGENT_UPDATE_RECEIPT } from './agent-update-helper';
 export type { AgentUpdateRequest, AgentUpdateResponse } from './agent-update-helper';
 export { DEFAULT_SOFTWARE_HELPER_SOCKET, requestSoftware, startSoftwareHelper, SOFTWARE_HELPER_GROUP, SOFTWARE_HELPER_UNIT_PATH } from './software-helper';
-export { ensureSoftwareRequirements, observeSoftwareHost, validateSoftwareRequirements } from './software';
-export type { SoftwareCommandResult, SoftwareExec, SoftwareObservation, SoftwareRequirement } from './software';
+export { ensureSoftwareRequirements, observeSoftwareHost, validateSoftwareRequirements, OS_CATALOG, SOFTWARE_CATALOG } from './software';
+export type { CatalogStatus, DeploymentChannel, OsCatalogEntry, SoftwareCatalogEntry, SoftwareCommandResult, SoftwareExec, SoftwareId, SoftwareObservation, SoftwareRequirement } from './software';
 export { heartbeatAgentOnce, observeAgentHost, startAgentHeartbeat } from './agent-heartbeat';
 export type { AgentHeartbeatOptions, AgentHeartbeatResponse, AgentObservation } from './agent-heartbeat';
 export { DEFAULT_DEPLOYMENT_RUNNER_SOCKET, requestDeploymentCommand, startDeploymentRunner } from './deployment-runner';

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) {

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) {