@forgezero/agent 0.1.30 → 0.1.32

package/dist/fz.js

@@ -4871,7 +4871,7 @@ async function spawnWith(command, env, report = () => {}) {
 
 // src/cli/index.ts
 init_dist();
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, statSync, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 
@@ -4884,14 +4884,26 @@ var MAX_AGENT_TARBALL_BYTES = 32 * 1024 * 1024;
 var AGENT_UPDATE_GROUP = "forgezero-update";
 var AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-helper.service";
 var MAX_REQUEST_BYTES = 8 * 1024;
+var UPDATE_RETRY_BASE_MS = 5 * 60000;
+var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION2 = "0.1.30";
+var VERSION2 = "0.1.32";
 
 // src/software.ts
 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" },
@@ -4919,6 +4931,31 @@ var UBUNTU_2604_X64 = [
     install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
   }
 ];
+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;
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      throw new Error("software requirement must be an object");
+    const row = item;
+    if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
+      throw new Error("software requirement contains an unknown field");
+    }
+    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+      throw new Error("software requirement coordinate is invalid");
+    }
+    const requirement = { id: row.id, version: row.version };
+    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 !== "active") {
+      throw new Error(`software requirement is not active: ${requirement.id}@${requirement.version}`);
+    }
+    return requirement;
+  });
+}
 
 // src/software-helper.ts
 var DEFAULT_SOFTWARE_HELPER_SOCKET = "/run/forgezero-software/helper.sock";
@@ -9530,6 +9567,262 @@ function checkProjectContext(rootInput) {
   return { ok: problems.length === 0, problems };
 }
 
+// src/deploy-file.ts
+import { createHash as createHash2 } from "crypto";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { basename, join as join3 } from "path";
+
+// src/definition.ts
+var PIPELINE_VERSION = 2;
+var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
+
+class DefinitionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DefinitionError";
+  }
+}
+var record = (value, where) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new DefinitionError(`${where} must be an object.`);
+  }
+  return value;
+};
+var text2 = (value, where) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new DefinitionError(`${where} must be a non-empty string.`);
+  }
+  return value;
+};
+var exactKeys = (value, allowed, where) => {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0)
+    throw new DefinitionError(`${where} contains unknown field(s): ${unknown.join(", ")}.`);
+};
+var NAME2 = /^[a-z][a-z0-9-]{0,62}$/;
+var RESERVED_STEP_ENV = new Set([
+  "PATH",
+  "HOME",
+  "SHELL",
+  "PWD",
+  "BUN_INSTALL",
+  "NODE_OPTIONS",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "GIT_SSH",
+  "GIT_SSH_COMMAND"
+]);
+function parseDeployDefinition(value, options = {}) {
+  const root = record(value, "pipeline");
+  exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
+  if (root.$schema !== undefined && root.$schema !== DEPLOY_SCHEMA_URL) {
+    throw new DefinitionError(`pipeline.$schema must be ${DEPLOY_SCHEMA_URL}.`);
+  }
+  if (root.version !== PIPELINE_VERSION) {
+    throw new DefinitionError(`pipeline.version must be ${PIPELINE_VERSION}.`);
+  }
+  if (root.requireAttestation !== undefined && typeof root.requireAttestation !== "boolean") {
+    throw new DefinitionError("pipeline.requireAttestation must be a boolean.");
+  }
+  const rawProfiles = record(root.profiles, "pipeline.profiles");
+  const profileEntries = Object.entries(rawProfiles);
+  if (profileEntries.length === 0 || profileEntries.length > 32) {
+    throw new DefinitionError("pipeline.profiles must contain from 1 to 32 named profiles.");
+  }
+  if (!Array.isArray(root.steps) || root.steps.length === 0) {
+    throw new DefinitionError("pipeline.steps must contain at least one step.");
+  }
+  const profiles = {};
+  for (const [name2, raw] of profileEntries) {
+    if (!NAME2.test(name2))
+      throw new DefinitionError(`pipeline profile name is invalid: ${name2}.`);
+    const profile = record(raw, `profiles.${name2}`);
+    exactKeys(profile, ["software"], `profiles.${name2}`);
+    if (!Array.isArray(profile.software)) {
+      throw new DefinitionError(`profiles.${name2}.software must be an array.`);
+    }
+    profiles[name2] = { software: validateSoftwareRequirements(profile.software, options) };
+  }
+  const phases = new Set(["build", "release", "migrate", "health"]);
+  const steps = root.steps.map((raw, index) => {
+    const step = record(raw, `steps[${index}]`);
+    exactKeys(step, ["name", "run", "phase", "scope", "profiles", "secrets", "always", "timeoutMs", "when"], `steps[${index}]`);
+    const phase = text2(step.phase, `steps[${index}].phase`);
+    if (!phases.has(phase))
+      throw new DefinitionError(`steps[${index}].phase is not supported.`);
+    if (step.scope !== "target" && step.scope !== "release") {
+      throw new DefinitionError(`steps[${index}].scope must be target or release.`);
+    }
+    if (step.always !== undefined && typeof step.always !== "boolean") {
+      throw new DefinitionError(`steps[${index}].always must be a boolean.`);
+    }
+    let selectedProfiles;
+    if (step.profiles !== undefined) {
+      if (!Array.isArray(step.profiles) || step.profiles.length === 0 || step.profiles.some((name2) => typeof name2 !== "string" || !Object.hasOwn(profiles, name2))) {
+        throw new DefinitionError(`steps[${index}].profiles must name existing profiles.`);
+      }
+      selectedProfiles = [...step.profiles];
+      if (new Set(selectedProfiles).size !== selectedProfiles.length) {
+        throw new DefinitionError(`steps[${index}].profiles must not contain duplicates.`);
+      }
+    }
+    if (step.secrets !== undefined && (!Array.isArray(step.secrets) || step.secrets.some((name2) => typeof name2 !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name2)))) {
+      throw new DefinitionError(`steps[${index}].secrets must contain names only.`);
+    }
+    if (Array.isArray(step.secrets) && new Set(step.secrets).size !== step.secrets.length) {
+      throw new DefinitionError(`steps[${index}].secrets must not contain duplicates.`);
+    }
+    if (Array.isArray(step.secrets) && step.secrets.some((name2) => RESERVED_STEP_ENV.has(String(name2)))) {
+      throw new DefinitionError(`steps[${index}].secrets may not replace process-control environment variables.`);
+    }
+    const timeoutMs = step.timeoutMs === undefined ? undefined : Number(step.timeoutMs);
+    if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 86400000)) {
+      throw new DefinitionError(`steps[${index}].timeoutMs must be an integer from 1 to 86400000.`);
+    }
+    let when;
+    if (step.when !== undefined) {
+      const conditions = record(step.when, `steps[${index}].when`);
+      when = {};
+      for (const [name2, expected] of Object.entries(conditions)) {
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name2) || typeof expected !== "string" || expected.length === 0) {
+          throw new DefinitionError(`steps[${index}].when must map environment names to non-empty strings.`);
+        }
+        when[name2] = expected;
+      }
+      if (Object.keys(when).length === 0)
+        throw new DefinitionError(`steps[${index}].when must not be empty.`);
+    }
+    return {
+      name: text2(step.name, `steps[${index}].name`),
+      run: text2(step.run, `steps[${index}].run`),
+      phase,
+      scope: step.scope,
+      profiles: selectedProfiles,
+      secrets: step.secrets,
+      always: step.always === true,
+      timeoutMs,
+      when
+    };
+  });
+  if (new Set(steps.map((step) => step.name)).size !== steps.length) {
+    throw new DefinitionError("pipeline.steps must have unique names.");
+  }
+  const name = text2(root.name, "pipeline.name");
+  if (name.length > 120)
+    throw new DefinitionError("pipeline.name must be at most 120 characters.");
+  return {
+    version: PIPELINE_VERSION,
+    name,
+    requireAttestation: root.requireAttestation === true,
+    profiles,
+    steps
+  };
+}
+
+// src/deploy-file.ts
+var DEPLOY_FILE = ".fz/deploy.json";
+var DEPLOY_TODO_PREFIX = "ForgeZero pipeline TODO:";
+var stable = (value) => {
+  if (Array.isArray(value))
+    return `[${value.map(stable).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => `${JSON.stringify(key)}:${stable(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+};
+function deployDefinitionDigest(definition) {
+  return `sha256:${createHash2("sha256").update(stable(definition)).digest("hex")}`;
+}
+var safeName = (value) => {
+  const normalized = value.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63);
+  return /^[a-z]/.test(normalized) ? normalized : `app-${normalized || "service"}`.slice(0, 63);
+};
+function packageHints(root) {
+  const packagePath = join3(root, "package.json");
+  if (!existsSync2(packagePath))
+    return { bun: existsSync2(join3(root, "bun.lock")) };
+  try {
+    const manifest = JSON.parse(readFileSync2(packagePath, "utf8"));
+    return {
+      name: typeof manifest.name === "string" ? manifest.name : undefined,
+      build: typeof manifest.scripts?.build === "string" ? "bun run build" : undefined,
+      bun: existsSync2(join3(root, "bun.lock")) || existsSync2(join3(root, "bun.lockb"))
+    };
+  } catch {
+    return { bun: existsSync2(join3(root, "bun.lock")) };
+  }
+}
+var blocker = (instruction) => `printf '%s\\n' '${DEPLOY_TODO_PREFIX} ${instruction}' >&2; exit 78`;
+function defaultDeployFile(root, options = {}) {
+  const hints = packageHints(root);
+  const software = options.software ?? (hints.bun ? SOFTWARE_CATALOG.filter((entry) => entry.id === "bun" && entry.status === "active").map(({ id: id2, version }) => ({ id: id2, version })) : []);
+  validateSoftwareRequirements(software, { channel: options.channel });
+  const profile = options.profile ?? "app";
+  const build = hints.build ?? blocker("replace the build step with the project build command");
+  return {
+    $schema: DEPLOY_SCHEMA_URL,
+    version: 2,
+    name: safeName(options.name ?? hints.name ?? basename(root)),
+    ...options.requireAttestation ? { requireAttestation: true } : {},
+    profiles: { [profile]: { software } },
+    steps: [
+      { name: "build", phase: "build", scope: "target", run: build, timeoutMs: 600000 },
+      {
+        name: "promote release",
+        phase: "release",
+        scope: "target",
+        run: blocker("replace the release step with an atomic promotion command"),
+        timeoutMs: 120000
+      },
+      {
+        name: "health check",
+        phase: "health",
+        scope: "target",
+        run: blocker("replace the health step with a bounded local health check"),
+        timeoutMs: 30000
+      }
+    ]
+  };
+}
+function inspectDeployFile(root, options = {}) {
+  const path = join3(root, DEPLOY_FILE);
+  if (!existsSync2(path))
+    throw new Error(`${DEPLOY_FILE} does not exist; run \`fz deploy init\`.`);
+  const raw = JSON.parse(readFileSync2(path, "utf8"));
+  const definition = parseDeployDefinition(raw, options);
+  const problems = definition.steps.filter((step) => step.run.includes(DEPLOY_TODO_PREFIX)).map((step) => `${step.name} still contains the safe initialization blocker`);
+  const profiles = Object.keys(definition.profiles).sort();
+  return {
+    path,
+    definition,
+    summary: {
+      path,
+      digest: deployDefinitionDigest(definition),
+      version: definition.version,
+      name: definition.name,
+      profiles,
+      software: Object.fromEntries(profiles.map((profile) => [
+        profile,
+        definition.profiles[profile].software
+      ])),
+      ready: problems.length === 0,
+      problems
+    }
+  };
+}
+function initializeDeployFile(root, options = {}) {
+  const path = join3(root, DEPLOY_FILE);
+  if (existsSync2(path) && !options.force) {
+    throw new Error(`${DEPLOY_FILE} already exists; use --force only when replacing it deliberately.`);
+  }
+  const raw = defaultDeployFile(root, options);
+  parseDeployDefinition(raw, { channel: options.channel });
+  mkdirSync2(join3(root, ".fz"), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(raw, null, 2)}
+`, { mode: 420 });
+  return inspectDeployFile(root, { channel: options.channel });
+}
+
 // src/cli/index.ts
 var DEFAULT_MODE = THRESHOLD_MODES[0].id;
 var RECOMMENDED_MODE = (THRESHOLD_MODES.find((mode) => mode.recommended) ?? THRESHOLD_MODES[0]).id;
@@ -9547,6 +9840,10 @@ function parseOptions(argv) {
     email: process.env.FZ_EMAIL ?? "operator@localhost",
     preserveEnv: false,
     projectRoot: process.cwd(),
+    deployProfile: "app",
+    deploySoftware: [],
+    deployChannel: "production",
+    requireAttestation: false,
     force: false
   };
   const positional = [];
@@ -9572,6 +9869,18 @@ function parseOptions(argv) {
       options.projectName = argv[++index];
     else if (token === "--purpose")
       options.projectPurpose = argv[++index];
+    else if (token === "--profile")
+      options.deployProfile = argv[++index] ?? options.deployProfile;
+    else if (token === "--software")
+      options.deploySoftware.push(argv[++index] ?? "");
+    else if (token === "--channel") {
+      const channel = argv[++index];
+      if (channel === "development" || channel === "production")
+        options.deployChannel = channel;
+      else
+        options.optionError = "--channel must be production or development.";
+    } else if (token === "--attestation")
+      options.requireAttestation = true;
     else if (token === "--force")
       options.force = true;
     else if (token === "--key")
@@ -9592,15 +9901,15 @@ function parseOptions(argv) {
   return { command: positional[0] ?? "help", args: positional.slice(1), options };
 }
 var out = {
-  line: (text2 = "") => process.stdout.write(`${text2}
+  line: (text3 = "") => process.stdout.write(`${text3}
 `),
-  step: (text2) => process.stdout.write(`  ${text2}
+  step: (text3) => process.stdout.write(`  ${text3}
 `),
-  warn: (text2) => process.stderr.write(`  ! ${text2}
+  warn: (text3) => process.stderr.write(`  ! ${text3}
 `),
-  fail: (text2) => process.stderr.write(`  \u2717 ${text2}
+  fail: (text3) => process.stderr.write(`  \u2717 ${text3}
 `),
-  ok: (text2) => process.stdout.write(`  \u2713 ${text2}
+  ok: (text3) => process.stdout.write(`  \u2713 ${text3}
 `)
 };
 var sessionCookie = null;
@@ -9805,17 +10114,17 @@ async function cmdAgent(options, args) {
     return 0;
   }
   try {
-    writeFileSync2(plan.unitPath, plan.unit, { mode: 420 });
+    writeFileSync3(plan.unitPath, plan.unit, { mode: 420 });
     out.ok(`Wrote ${plan.unitPath}`);
     for (const auxiliary of plan.auxiliaryUnits) {
-      mkdirSync2(dirname2(auxiliary.path), { recursive: true, mode: 493 });
-      writeFileSync2(auxiliary.path, auxiliary.unit, { mode: 420 });
+      mkdirSync3(dirname2(auxiliary.path), { recursive: true, mode: 493 });
+      writeFileSync3(auxiliary.path, auxiliary.unit, { mode: 420 });
       out.ok(`Wrote ${auxiliary.path}`);
     }
     if (options.enrol) {
-      if (existsSync2(enrolTokenSourcePath)) {
+      if (existsSync3(enrolTokenSourcePath)) {
         const source = statSync(enrolTokenSourcePath);
-        const token = readFileSync2(enrolTokenSourcePath, "utf8").trim();
+        const token = readFileSync3(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.");
         }
@@ -9828,7 +10137,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.");
         }
-        writeFileSync2(enrolTokenSourcePath, `${token}
+        writeFileSync3(enrolTokenSourcePath, `${token}
 `, { mode: 384, flag: "wx" });
       }
     }
@@ -9839,7 +10148,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(`  ${readFileSync2(gitPublicKeyPath, "utf8").trim()}`);
+    out.line(`  ${readFileSync3(gitPublicKeyPath, "utf8").trim()}`);
     out.line();
     return 0;
   } catch (cause) {
@@ -9993,6 +10302,86 @@ function cmdProject(options, args) {
     return 1;
   }
 }
+function softwareCoordinates(values) {
+  if (values.length === 0)
+    return;
+  return values.map((coordinate) => {
+    const separator = coordinate.lastIndexOf("@");
+    if (separator < 1 || separator === coordinate.length - 1) {
+      throw new Error(`Software must be <key>@<version>, received: ${coordinate || "<empty>"}.`);
+    }
+    return {
+      id: coordinate.slice(0, separator),
+      version: coordinate.slice(separator + 1)
+    };
+  });
+}
+function cmdDeploy(options, args) {
+  const operation = args[0] ?? "check";
+  try {
+    if (options.optionError)
+      throw new Error(options.optionError);
+    if (operation === "init") {
+      const created = initializeDeployFile(options.projectRoot, {
+        name: options.projectName,
+        profile: options.deployProfile,
+        software: softwareCoordinates(options.deploySoftware),
+        requireAttestation: options.requireAttestation,
+        channel: options.deployChannel,
+        force: options.force
+      });
+      if (options.json)
+        out.line(JSON.stringify(created.summary, null, 2));
+      else {
+        out.ok(`Initialized .fz/deploy.json (${created.summary.digest}).`);
+        out.warn("Release and health use safe blockers until you replace them with project-specific commands.");
+        out.step("Run `fz deploy check`, commit the file, then push; the verified Git commit is the live sync.");
+      }
+      return 0;
+    }
+    if (operation === "check" || operation === "sync") {
+      const inspected = inspectDeployFile(options.projectRoot, { channel: options.deployChannel });
+      if (options.json)
+        out.line(JSON.stringify(inspected.summary, null, 2));
+      else {
+        out.step(`${inspected.summary.name} \xB7 v${inspected.summary.version} \xB7 ${inspected.summary.digest}`);
+        out.step(`profiles: ${inspected.summary.profiles.join(", ")}`);
+        for (const problem of inspected.summary.problems)
+          out.fail(problem);
+        if (inspected.summary.ready) {
+          out.ok("Deploy definition is typed, catalog-valid and ready to commit.");
+          if (operation === "sync") {
+            out.step("Commit and push this file. ForgeZero deploys the exact webhook commit; no second live file exists.");
+          }
+        }
+      }
+      return inspected.summary.ready ? 0 : 1;
+    }
+    if (operation === "catalog") {
+      const software = SOFTWARE_CATALOG.filter((entry) => entry.status === "active" || options.deployChannel === "development" && entry.status === "testing");
+      const payload = {
+        channel: options.deployChannel,
+        note: "Only active coordinates are selectable in deploy definitions.",
+        os: OS_CATALOG,
+        software
+      };
+      if (options.json)
+        out.line(JSON.stringify(payload, null, 2));
+      else {
+        out.line(`${options.deployChannel} software catalog (only active coordinates are selectable):`);
+        for (const entry of software) {
+          out.step(`${entry.id}@${entry.version} \xB7 ${entry.os} ${entry.osVersion} ${entry.architecture} \xB7 ${entry.status}`);
+        }
+      }
+      return 0;
+    }
+    out.fail("Usage: fz deploy init|check|sync|catalog [--root <path>] [--channel production|development]");
+    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
@@ -10017,6 +10406,10 @@ function usage() {
     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
+    fz deploy init          Create a typed, fail-safe .fz/deploy.json
+    fz deploy check         Validate commands, profiles and software coordinates
+    fz deploy sync          Prove readiness and print the Git synchronization rule
+    fz deploy catalog       List selectable tested OS/software coordinates
 
   CEREMONY OPTIONS
     --key <fp|index>        Which agent key to use for custody
@@ -10039,10 +10432,14 @@ 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
+    --root <path>           Project root for project/deploy commands
+    --name <name>           Project or deploy name during init
+    --purpose <text>        Product outcome during project init
+    --profile <name>        Initial deploy profile (default app)
+    --software <key@ver>    Initial tested software coordinate; repeatable
+    --channel <name>        Catalog view: production or development (shows testing)
+    --attestation           Require hardware attestation for every deploy step
+    --force                 Init may replace an existing generated target
 
   CUSTODY FACTORS
     Every custodian share is sealed TWICE and either envelope alone opens it:
@@ -10074,6 +10471,9 @@ async function runCli() {
     case "project":
       code = cmdProject(options, args);
       break;
+    case "deploy":
+      code = cmdDeploy(options, args);
+      break;
     case "genesis":
       code = await cmdGenesis(options);
       break;
@@ -10097,7 +10497,7 @@ async function runCli() {
       usage();
       code = 1;
   }
-  if (args.length > 0 && code === 0 && command !== "agent" && command !== "project") {
+  if (args.length > 0 && code === 0 && command !== "agent" && command !== "project" && command !== "deploy") {
     out.warn(`Ignored: ${args.join(" ")}`);
   }
   process.exit(code);

package/dist/index.d.ts

@@ -29,8 +29,8 @@ export type { LifecycleCommandResult, LifecycleExec, LifecycleProfile } from './
 export { materializeWarpMdm, renderWarpMdm } from './warp-config';
 export { compareVersions, restoreAgentRelease, selectAgentRelease, stageAgentRelease, validateAgentRelease, DEFAULT_AGENT_RELEASE_ROOT, DEFAULT_AGENT_UPDATE_SOCKET, MAX_AGENT_TARBALL_BYTES } from './agent-update';
 export type { AgentRelease, StagedAgentRelease, UpdateCommand, UpdateCommandResult } from './agent-update';
-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 { activateAgentRelease, probeAgentSocket, readAgentUpdateReceipt, recoverInterruptedAgentUpdate, requestAgentUpdate, startAgentUpdateHelper, AGENT_UPDATE_GROUP, AGENT_UPDATE_HELPER_UNIT_PATH, AGENT_UPDATE_JOURNAL, AGENT_UPDATE_RECEIPT } from './agent-update-helper';
+export type { AgentUpdateOutcome, AgentUpdateReceipt, 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, OS_CATALOG, SOFTWARE_CATALOG } from './software';
 export type { CatalogStatus, DeploymentChannel, OsCatalogEntry, SoftwareCatalogEntry, SoftwareCommandResult, SoftwareExec, SoftwareId, SoftwareObservation, SoftwareRequirement } from './software';