@intentius/chant 0.90.0 → 0.91.0

package/src/cli/mcp/workspace-tools.test.ts

@@ -85,7 +85,7 @@ describe("which servers have the workspace tools", () => {
       const { tools } = (await rpc(server(cwd), "tools/list")) as { tools: { name: string }[] };
       expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(names));
     }
-    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-records", "records-new", "records-amend", "records-review", "records-close"]);
+    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-records", "workspace-points", "records-new", "records-amend", "records-review", "records-close", "points-answer"]);
   });
 
   test("a server outside any workspace, or given none, does not", async () => {
@@ -115,6 +115,19 @@ describe("reads", () => {
     expect(recordsOf(only.structuredContent).map((r) => r.id)).toEqual(["fix-001"]);
   }, 120_000);
 
+  test("workspace-points returns the document chant workspace points --json prints, and points-answer the write's (ws-058)", async () => {
+    const s = server();
+    const res = await call(s, "workspace-points", { open: true });
+    expect(res.isError).toBeUndefined();
+    expect(res.structuredContent).toEqual(cli(["workspace", "points", "--open", "--json"]));
+    expect(res.structuredContent).toMatchObject({ open: true, sources: [], points: [], questions: [] });
+    // The generated workspace declares no answer kind, so there is nothing to answer.
+    const answered = await call(s, "points-answer", { id: "slice-tier-000000000000", answer: "small", by: ["alice"] });
+    expect(answered.structuredContent).toMatchObject({ verb: "answer", error: { code: "points-undeclared" } });
+    const bad = await call(s, "points-answer", { id: "slice-tier-000000000000", answer: "small", by: [] });
+    expect(bad.isError).toBe(true);
+  }, 120_000);
+
   test("an error document is returned as a document, and a flag-shaped value is refused before chant runs", async () => {
     const s = server();
     const missing = await call(s, "workspace-records", { kind: "nowhere/none.kind.mjs" });

package/src/cli/mcp/workspace-tools.ts

@@ -6,15 +6,17 @@
  * is a thin call into the code the CLI runs:
  *
  * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`,
- *   `workspace-records`) run `chant workspace <command> ... --json` with the
- *   chant this server runs as, in the server's directory, and return the
+ *   `workspace-records`, `workspace-points`) run `chant workspace <command>
+ *   ... --json` with the chant this server runs as, in the server's
+ *   directory, and return the
  *   document it printed, unchanged, with its reason codes (#2536). Running the
  *   command, rather than calling into it, keeps every rule it has, handing the
  *   read to the workspace root's pinned chant included (ws-021), and keeps
  *   anything a command prints away from the protocol on stdout.
  * - The writes (`records-new`, `records-amend`, `records-review`,
- *   `records-close`) call the functions `chant workspace records new|amend|
- *   review|close` call, and return the same JSON result. They keep every rule
+ *   `records-close`, `points-answer`) call the functions `chant workspace
+ *   records new|amend|review|close` and `points answer` call, and return the
+ *   same JSON result. They keep every rule
  *   the CLI keeps: the kind's schema, a closed record never changing, an
  *   approved one changing only as its approval rule allows, a dissent needing
  *   a note, and `sign` using this host's configured key or refusing with the
@@ -75,7 +77,7 @@ export const workspaceReadTools: ToolDefinition[] = [
   {
     name: "workspace-status",
     description:
-      "What each member has released to an environment, from the lifecycle ledgers: chant workspace status <env> --json. Returns that document unchanged (status.schema.json).",
+      "What each member has released to an environment, its gates, and the steward that runs it with each Op's last run, from the declaration and the lifecycle ledgers: chant workspace status <env> --json. Returns that document unchanged (status.schema.json).",
     inputSchema: {
       type: "object",
       properties: {
@@ -119,6 +121,19 @@ export const workspaceReadTools: ToolDefinition[] = [
       },
     },
   },
+  {
+    name: "workspace-points",
+    description:
+      "The workspace's decision points and the questions asked of them: chant workspace points --json (points.schema.json, ws-058). A question is open while it is escalated to people, or proposed by a model and not yet confirmed; each lists any model's answer with its confidence and threshold. Returns the document unchanged. chant calls no model to answer this.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        open: { type: "boolean", description: "Only the open questions (--open)." },
+        kind: { type: "string", description: "One answer kind file, in place of the declared ones (--kind)." },
+        at: atProp,
+      },
+    },
+  },
 ];
 
 export const workspaceWriteTools: ToolDefinition[] = [
@@ -191,6 +206,23 @@ export const workspaceWriteTools: ToolDefinition[] = [
       required: ["id"],
     },
   },
+  {
+    name: "points-answer",
+    description:
+      "Record people's answer to an open decision point question, or confirm a model's proposal: chant workspace points answer. Refused unless the point's quorum is met: distinct people, none holding the agent role, each holding one of the quorum's roles when it names any. An answered question never changes. " +
+      PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The question's id, as workspace-points lists it." },
+        answer: { type: ["string", "boolean"], description: "One of the question's candidates; for a noul, true or false." },
+        by: { type: "array", items: { type: "string" }, description: "Each person who answered (--by)." },
+        kind: { type: "string", description: "The answer kind file. Without it, the declared answer kinds." },
+        dryRun: dryRunProp,
+      },
+      required: ["id", "answer", "by"],
+    },
+  },
 ];
 
 /** A tool call that can't be made as given: the client gets it as an error result, and nothing runs. */
@@ -249,6 +281,10 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
       if (intent !== undefined) return ["workspace", "graph", "--intent", intent, ...kindArgs, ...atArgs, "--json"];
       return ["workspace", "graph", ...kindArgs, ...atArgs, "--json"];
     }
+    case "workspace-points": {
+      const kind = str(params, "kind");
+      return ["workspace", "points", ...(bool(params, "open") ? ["--open"] : []), ...(kind !== undefined ? ["--kind", kind] : []), ...atArgs, "--json"];
+    }
     case "workspace-records": {
       const kind = str(params, "kind");
       const since = str(params, "since");
@@ -389,6 +425,14 @@ export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceT
         cwd,
       });
     },
+    "points-answer": async (params) => {
+      const { answerPoint } = await import("../../workspace/decide");
+      const answer = params.answer;
+      if (typeof answer !== "string" && typeof answer !== "boolean") throw new ToolInputError("answer must be a string, or true or false");
+      const by = params.by;
+      if (!Array.isArray(by) || by.length === 0 || !by.every((b) => typeof b === "string" && b.trim() !== "")) throw new ToolInputError("by must list each person who answered");
+      return answerPoint({ cwd, id: str(params, "id", true)!, answer, by: by as string[], kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
+    },
     "records-close": async (params) => {
       const w = await write();
       const { closeRecord, RECORDS_CLOSE_SCHEMA_ID } = await import("../../workspace/records-close");

package/src/cli/registry.ts

@@ -287,6 +287,18 @@ export interface ParsedArgs {
   kind?: string;
   /** Every `--kind` given, in order: `chant workspace graph --intent` reads each (#2651). */
   kinds?: string[];
+  /** Every `--by` given, in order: `chant workspace points answer` counts each person toward the quorum (#2739). */
+  bys?: string[];
+  /** `chant workspace points --open` (#2739): only the questions still open. */
+  open?: boolean;
+  /** `chant workspace points ask <point> --inputs <file|->` (#2739): the inputs, as a JSON object. */
+  inputs?: string;
+  /** `chant workspace points ask <point> --response <file>` (#2739): a POST /v1/systemone response the caller got from a backend. */
+  response?: string;
+  /** `chant workspace points ask <point> --subject <id>` (#2739): what the question is about. */
+  subject?: string;
+  /** `chant workspace points answer <id> --answer <value>` (#2739): the people's answer. */
+  answer?: string;
   /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
   composites?: boolean;
   /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. */
@@ -369,6 +381,8 @@ export interface ParsedArgs {
   component?: string;
   /** `chant components release record --digest <sha256:...>` (#568) — artifact digest to record, joining this release to the build archive/ledger. Also `chant components export --digest <manifestDigest>` (#929) — a build archive manifest digest to export directly, bypassing env/component resolution. */
   digest?: string;
+  /** `chant components release record --release-plan <file>` (ws-055, #2733) — path to a release plan JSON file, persisted content-addressed to `_plans/<digest>.json` on chant/lifecycle and read back through the read contract (`chant workspace status --json`). The plan's own `digest` field supplies `--digest` when it is omitted, and must match it when both are given. Distinct from `--plan` (#2300, below), the Op gate-approval plan digest. */
+  releasePlanFile?: string;
   /** Every `--digest` value, in order (#2602). `chant components promote --digest <component>=<sha256:...>` is repeatable, one per component; the other commands read the single {@link digest}. */
   digests?: string[];
   /** `chant components release record --git-sha <sha>` (#568) — git commit the deploy was built from. */
@@ -413,6 +427,23 @@ export interface ParsedArgs {
   interval?: string;
   /** `chant operator --lease-ttl <duration>` (#1485) — how long an acquired lease is valid before it's reclaimable by another operator. Default: 5m. */
   leaseTtl?: string;
+  /**
+   * `chant operator --steward [<name>]` (#2731) — run a declared steward's
+   * local form: its scheduled Ops on their crons, under the steward's own
+   * lease. `""` when the flag is given without a name, which picks the
+   * project's only steward.
+   */
+  steward?: string;
+  /** `chant workspace work claim|renew|release <id> --holder <name>` (#2732): who holds, or releases, the work lease. */
+  holder?: string;
+  /** `chant run <op> --work <id>` (#2748): the work item an Op with a work lease runs under. */
+  work?: string;
+  /** `chant workspace work claim|renew <id> --ttl <seconds|duration>` (#2732): how long the lease lasts unless renewed. */
+  ttl?: string;
+  /** `chant workspace work renew|release <id> --token <token>` (#2732): the fencing token the caller holds. */
+  token?: string;
+  /** `chant workspace work release <id> --outcome <text>` (#2732): how the work ended, such as done or not_done. */
+  outcome?: string;
   /** `chant operator --once` (#1485) — run a single round and exit, instead of looping until Ctrl-C. Also the offline test/cron-invoker story. */
   once?: boolean;
   /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text prose recorded on the gate-resolution fact. The PR link belongs in `--url` since #2028; this is for everything that isn't the link. */

package/src/components/verbs/vuln-scan.test.ts

@@ -5,7 +5,8 @@
  * `scan-vulnerabilities` capability over an injected scanner.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, test, expect } from "vitest";
 import {
@@ -15,8 +16,13 @@ import {
   createToolVulnScanner,
   createScanVulnerabilitiesCapability,
   autoDetectVulnScanner,
+  sbomPackages,
+  compareVersions,
+  scanWithDatabase,
+  createDatabaseVulnScanner,
   type VulnFinding,
   type VulnScanner,
+  type AdvisoryDatabase,
 } from "./vuln-scan";
 import { ToolNotAvailableError } from "./process-runner";
 import type { SbomDocument } from "./sbom-generator";
@@ -178,6 +184,123 @@ describe("exploitability parsing (#1463)", () => {
   });
 });
 
+// ── offline advisory database (ws-056, INTENTIUS/chant#2735) ─────────────────
+// Ported from chud's supply-chain.mjs tests: an SBOM's purl-derived packages
+// matched against a local, offline advisory database — no scanner binary, no
+// network.
+
+const SPDX_SBOM: SbomDocument = {
+  format: "spdx",
+  mediaType: "application/spdx+json",
+  bytes: JSON.stringify({
+    packages: [
+      { name: "lodash", externalRefs: [{ referenceCategory: "PACKAGE-MANAGER", referenceType: "purl", referenceLocator: "pkg:npm/lodash@4.17.20" }] },
+      { name: "left-pad", externalRefs: [{ referenceCategory: "PACKAGE-MANAGER", referenceType: "purl", referenceLocator: "pkg:npm/left-pad@1.3.0" }] },
+      { name: "no-purl" },
+    ],
+  }),
+  generator: "lockfile",
+};
+
+const CYCLONEDX_SBOM: SbomDocument = {
+  format: "cyclonedx",
+  mediaType: "application/vnd.cyclonedx+json",
+  bytes: JSON.stringify({
+    components: [{ name: "lodash", purl: "pkg:npm/lodash@4.17.20" }, { name: "left-pad", purl: "pkg:npm/left-pad@1.3.0" }],
+  }),
+  generator: "lockfile",
+};
+
+const DB: AdvisoryDatabase = {
+  advisories: [
+    { id: "CVE-2024-0001", package: "lodash", severity: "critical", introduced: "4.0.0", fixed: "4.17.21" },
+    { id: "CVE-2024-0002", package: "left-pad", severity: "low" },
+    { id: "CVE-2024-0003", package: "lodash", ecosystem: "pypi", severity: "high" },
+  ],
+};
+
+describe("sbomPackages", () => {
+  test("reads purls from an SPDX document's externalRefs, skipping entries with none", () => {
+    const packages = sbomPackages(SPDX_SBOM);
+    expect(packages).toEqual([
+      { ecosystem: "npm", name: "lodash", version: "4.17.20" },
+      { ecosystem: "npm", name: "left-pad", version: "1.3.0" },
+    ]);
+  });
+
+  test("reads purls from a CycloneDX document's components", () => {
+    expect(sbomPackages(CYCLONEDX_SBOM)).toEqual([
+      { ecosystem: "npm", name: "lodash", version: "4.17.20" },
+      { ecosystem: "npm", name: "left-pad", version: "1.3.0" },
+    ]);
+  });
+
+  test("deduplicates identical ecosystem/name/version", () => {
+    const doc = { bytes: JSON.stringify({ components: [{ purl: "pkg:npm/x@1.0.0" }, { purl: "pkg:npm/x@1.0.0" }] }) };
+    expect(sbomPackages(doc)).toHaveLength(1);
+  });
+});
+
+describe("compareVersions", () => {
+  test("compares numerically, not lexically (1.9.0 < 1.10.0)", () => {
+    expect(compareVersions("1.9.0", "1.10.0")).toBe(-1);
+    expect(compareVersions("1.10.0", "1.9.0")).toBe(1);
+    expect(compareVersions("1.2.3", "1.2.3")).toBe(0);
+  });
+
+  test("a pre-release sorts before its release", () => {
+    expect(compareVersions("1.2.0-rc.1", "1.2.0")).toBe(-1);
+    expect(compareVersions("1.2.0", "1.2.0-rc.1")).toBe(1);
+  });
+});
+
+describe("scanWithDatabase", () => {
+  test("matches an SBOM's packages against the database by ecosystem + name, introduced <= version < fixed", () => {
+    const findings = scanWithDatabase(SPDX_SBOM, DB);
+    expect(findings).toHaveLength(2);
+    const lodash = findings.find((f) => f.cveId === "CVE-2024-0001");
+    expect(lodash).toEqual({ cveId: "CVE-2024-0001", severity: "critical", package: "lodash", installedVersion: "4.17.20", fixedVersion: "4.17.21", fixable: true });
+    const leftPad = findings.find((f) => f.cveId === "CVE-2024-0002");
+    expect(leftPad).toMatchObject({ package: "left-pad", fixable: false });
+    expect(leftPad!.fixedVersion).toBeUndefined();
+  });
+
+  test("a version at or after `fixed` is not affected", () => {
+    const doc = { bytes: JSON.stringify({ components: [{ purl: "pkg:npm/lodash@4.17.21" }] }) };
+    expect(scanWithDatabase(doc, DB)).toHaveLength(0);
+  });
+
+  test("an ecosystem mismatch does not match (pypi advisory, npm package)", () => {
+    const findings = scanWithDatabase(SPDX_SBOM, DB);
+    expect(findings.some((f) => f.cveId === "CVE-2024-0003")).toBe(false);
+  });
+
+  test("accepts a bare advisories array as well as { advisories: [...] }", () => {
+    expect(scanWithDatabase(SPDX_SBOM, DB.advisories)).toHaveLength(2);
+  });
+});
+
+describe("createDatabaseVulnScanner", () => {
+  test("scans by reading the database file at scan time", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-vulndb-"));
+    const dbFile = join(dir, "advisories.json");
+    writeFileSync(dbFile, JSON.stringify(DB));
+    const scanner = createDatabaseVulnScanner(dbFile);
+    const findings = await scanner.scan({ sbom: SPDX_SBOM });
+    expect(findings).toHaveLength(2);
+  });
+
+  test("composes with scan-vulnerabilities like any other VulnScanner", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-vulndb-"));
+    const dbFile = join(dir, "advisories.json");
+    writeFileSync(dbFile, JSON.stringify(DB));
+    const cap = createScanVulnerabilitiesCapability(createDatabaseVulnScanner(dbFile));
+    const out = await cap.run(ctx, { sbom: SPDX_SBOM, digest: "sha256:abc" });
+    expect(out.findings).toHaveLength(2);
+    expect(out.digest).toBe("sha256:abc");
+  });
+});
+
 describe("createToolVulnScanner (grype, via MockProcessRunner)", () => {
   test("scans the SBOM with `grype sbom:<file>` and parses the result", async () => {
     const mock = createMockProcessRunner({ tools: { grype: true }, responses: { "grype sbom:": GRYPE_JSON } });

package/src/components/verbs/vuln-scan.ts

@@ -13,9 +13,17 @@
  * inline fake `VulnScanner` (an object literal with a canned `scan()`, see
  * ./vuln-gate.test.ts) and never invoke a real scanner, network, or vuln DB.
  * The scanner's vuln DB currency is the tool's job, not chant's.
+ *
+ * `createDatabaseVulnScanner` (ws-056, INTENTIUS/chant#2735) is the one
+ * hermetic exception: a `VulnScanner` matched against a local, offline
+ * advisory-database file instead of a real scanner binary — no `grype`/
+ * `trivy` required, deterministic, at the cost of covering only the
+ * advisories the database names. Ported from chud's `supply-chain.mjs`
+ * (`scanWithDatabase`/`sbomPackages`/`compareVersions`), which built its own
+ * copy of this because `scan-vulnerabilities` had no offline backend.
  */
 
-import { writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
@@ -174,6 +182,139 @@ export function parseTrivyOutput(stdout: string): VulnFinding[] {
   return out;
 }
 
+// ── offline advisory database ────────────────────────────────────────────────
+
+/** One package an SBOM names, by purl: the ecosystem, its name and its installed version. */
+export interface SbomPackage {
+  ecosystem: string;
+  name: string;
+  version: string;
+}
+
+/**
+ * The packages an SPDX or CycloneDX document lists, by purl (SPDX's
+ * `externalRefs` with `referenceType: "purl"`, CycloneDX's `components[].purl`),
+ * deduplicated by ecosystem/name/version. Parses `doc.bytes` (a string, as
+ * every `SbomDocument` carries it) rather than requiring a pre-parsed object,
+ * so a caller can pass a `scan-vulnerabilities` input's `sbom` straight
+ * through.
+ */
+export function sbomPackages(doc: Pick<SbomDocument, "bytes">): SbomPackage[] {
+  const parsed = JSON.parse(doc.bytes) as {
+    packages?: Array<{ externalRefs?: Array<{ referenceType?: string; referenceLocator?: string }> }>;
+    components?: Array<{ purl?: string }>;
+  };
+  const purls = [
+    ...(parsed.packages ?? []).flatMap((p) =>
+      (p.externalRefs ?? []).filter((r) => r.referenceType === "purl").map((r) => r.referenceLocator ?? ""),
+    ),
+    ...(parsed.components ?? []).map((c) => c.purl).filter((p): p is string => Boolean(p)),
+  ];
+  const seen = new Map<string, SbomPackage>();
+  for (const purl of purls) {
+    const m = /^pkg:([^/]+)\/(.+)@([^?#]+)/.exec(purl);
+    if (!m) continue;
+    const pkg: SbomPackage = { ecosystem: m[1], name: decodeURIComponent(m[2]), version: decodeURIComponent(m[3]) };
+    seen.set(`${pkg.ecosystem}:${pkg.name}@${pkg.version}`, pkg);
+  }
+  return [...seen.values()];
+}
+
+/**
+ * Compare two dotted version strings numerically, a pre-release sorting
+ * before its release (`1.2.0-rc.1` < `1.2.0`). Not full semver (no build
+ * metadata, no ordering between differing pre-release labels beyond "a
+ * pre-release exists") — just enough to place an installed version between
+ * an advisory's `introduced` and `fixed`.
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const parse = (v: string) => {
+    const [core, pre] = String(v).replace(/^v/, "").split("-", 2);
+    return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < Math.max(x.nums.length, y.nums.length); i++) {
+    const d = (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+    if (d) return Math.sign(d) as -1 | 1;
+  }
+  if (x.pre && !y.pre) return -1;
+  if (!x.pre && y.pre) return 1;
+  if (x.pre === y.pre) return 0;
+  return x.pre! < y.pre! ? -1 : 1;
+}
+
+/** One advisory in a local, offline advisory database (`AdvisoryDatabase.advisories`). */
+export interface Advisory {
+  /** Advisory id, e.g. `"CVE-2024-12345"` or `"GHSA-…"`. */
+  id: string;
+  /** Ecosystem the advisory applies to (npm, pypi, …). Default: `"npm"`. */
+  ecosystem?: string;
+  /** Affected package name, matched against the SBOM's purl-derived package name. */
+  package: string;
+  severity?: string;
+  /** First affected version. Default: `"0"` (affects every version up to `fixed`). */
+  introduced?: string;
+  /** First version that fixes it. Omitted for a vulnerability with no fix yet. */
+  fixed?: string;
+  summary?: string;
+}
+
+/** A local, offline advisory database: `{ "advisories": [...] }` (or a bare array, for convenience). */
+export interface AdvisoryDatabase {
+  advisories: Advisory[];
+}
+
+/**
+ * Match an SBOM's packages against a local, offline advisory database —
+ * no scanner binary, no network, deterministic. A package is affected when
+ * `introduced <= installedVersion < fixed` (or unconditionally affected when
+ * the advisory names no `fixed`). Findings are `VulnFinding`-shaped, so they
+ * feed `vuln-gate` exactly like `grype`/`trivy` output does; every
+ * exploitability field (`epss`, `inKev`, …) an offline database can't supply
+ * is left `undefined`, never defaulted to a false negative.
+ */
+export function scanWithDatabase(doc: Pick<SbomDocument, "bytes">, db: AdvisoryDatabase | Advisory[]): VulnFinding[] {
+  const advisories = Array.isArray(db) ? db : (db.advisories ?? []);
+  const findings: VulnFinding[] = [];
+  for (const pkg of sbomPackages(doc)) {
+    for (const a of advisories) {
+      if ((a.ecosystem ?? "npm") !== pkg.ecosystem || a.package !== pkg.name) continue;
+      if (compareVersions(pkg.version, a.introduced ?? "0") < 0) continue;
+      if (a.fixed && compareVersions(pkg.version, a.fixed) >= 0) continue;
+      findings.push({
+        cveId: a.id,
+        severity: normalizeSeverity(a.severity),
+        package: pkg.name,
+        installedVersion: pkg.version,
+        ...(a.fixed ? { fixedVersion: a.fixed } : {}),
+        fixable: Boolean(a.fixed),
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * A `VulnScanner` backed by a local, offline advisory database file (JSON:
+ * `{ "advisories": [...] }`, see `AdvisoryDatabase`) instead of a real
+ * scanner binary — the hermetic fallback `autoDetectVulnScanner`'s doc
+ * comment says a scan doesn't have ("there is no hermetic fallback, a scan
+ * needs a real vuln DB"): deterministic, offline, no `grype`/`trivy`
+ * install required, at the cost of covering only the advisories the
+ * database names. Reads the file once per call (a database pinned in the
+ * repo changes rarely; callers that scan repeatedly should cache the parsed
+ * `AdvisoryDatabase` and call `scanWithDatabase` directly instead).
+ */
+export function createDatabaseVulnScanner(dbFile: string): VulnScanner {
+  return {
+    async scan(input) {
+      const db = JSON.parse(readFileSync(dbFile, "utf8")) as AdvisoryDatabase | Advisory[];
+      return scanWithDatabase(input.sbom, db);
+    },
+  };
+}
+
 /**
  * A real `VulnScanner` that writes the SBOM to a temp file and scans it with
  * `grype` (default) or `trivy`, through the injectable `ProcessRunner`.

package/src/lifecycle/git.ts

@@ -1100,34 +1100,70 @@ export async function readBlobBySha(sha: string, opts?: { cwd?: string }): Promi
  * Push one arbitrary ref (e.g. a lease ref) to the remote, guarded the same
  * way {@link pushLifecycle} guards the ledger branch: `--force-with-lease`
  * keyed to the remote SHA last observed locally, so a concurrent push from a
- * second machine is rejected rather than silently clobbered. Plain `--force`
- * underneath that lease — a lease ref's value is a bare blob SHA, not a
- * commit descending from the previous one, so there is no "fast-forward" to
- * preserve, only the CAS the lease guard already provides.
+ * second machine is rejected rather than silently clobbered. The lease alone
+ * lets a push replace a value that is not an ancestor — a lease ref's value is
+ * a bare blob SHA, not a commit descending from the previous one — as long as
+ * the remote still holds the expected value. No `--force` beside it: git lets
+ * `--force` override `--force-with-lease`, which made every lease push
+ * unconditional before #2732.
  *
  * Returns `false` (never throws) when no remote is configured — a
  * remote-less project's lease is local-only by construction (see
  * `./lease.ts`'s module doc), or when the push itself is rejected (the
- * caller re-reads and retries; see `acquireLease`).
+ * caller re-reads and retries; see `acquireLease`). {@link pushRefStatus}
+ * tells those two apart.
  */
-export async function pushRef(ref: string, opts?: { cwd?: string }): Promise<boolean> {
+export async function pushRef(ref: string, opts?: { cwd?: string; expect?: string | null }): Promise<boolean> {
+  return (await pushRefStatus(ref, opts)) === "pushed";
+}
+
+/** What {@link pushRefStatus} did: the remote took the ref, there is no remote, or the remote refused it. */
+export type PushRefStatus = "pushed" | "no-remote" | "rejected";
+
+/**
+ * {@link pushRef}, saying why a push did not land (#2732).
+ *
+ * `opts.expect` is the value the caller last saw the ref at on the remote
+ * (`null`: absent there), and becomes the `--force-with-lease` expectation.
+ * Without it the expectation is `refs/remotes/<remote>/<ref>`, which nothing
+ * fetches a lease ref into, so it reads as "absent" and only a first push
+ * lands. A lease passes the value of its own remote-tracking ref instead
+ * (`./lease.ts`'s `readLease`).
+ *
+ * A ref that no longer exists locally is pushed as a deletion, under the same
+ * expectation, so a released lease is released on the remote too. Deleting a
+ * ref the caller expects to be absent already is a no-op that reports
+ * `pushed`.
+ */
+export async function pushRefStatus(ref: string, opts?: { cwd?: string; expect?: string | null }): Promise<PushRefStatus> {
   const rt = getRuntime();
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
-  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return "no-remote";
   const remote = remoteResult.stdout.trim().split("\n")[0];
 
-  const remoteRef = `refs/remotes/${remote}/${ref.replace(/^refs\//, "")}`;
-  const expectedResult = await rt.spawn(["git", "rev-parse", "--verify", remoteRef], { cwd: opts?.cwd });
-  const expected = expectedResult.exitCode === 0 ? expectedResult.stdout.trim() : null;
+  let expected: string | null;
+  if (opts?.expect !== undefined) {
+    expected = opts.expect;
+  } else {
+    const remoteRef = `refs/remotes/${remote}/${ref.replace(/^refs\//, "")}`;
+    const expectedResult = await rt.spawn(["git", "rev-parse", "--verify", remoteRef], { cwd: opts?.cwd });
+    expected = expectedResult.exitCode === 0 ? expectedResult.stdout.trim() : null;
+  }
   const lease = `${ref}:${expected ?? ""}`;
 
+  const local = await readRefSha(ref, opts);
+  if (local === null && expected === null) return "pushed";
+  const refspec = local === null ? `:${ref}` : `${ref}:${ref}`;
   const pushResult = await rt.spawn(
-    ["git", "push", "--force", `--force-with-lease=${lease}`, remote, `${ref}:${ref}`],
+    ["git", "push", `--force-with-lease=${lease}`, remote, refspec],
     { cwd: opts?.cwd },
   );
-  return pushResult.exitCode === 0;
+  return pushResult.exitCode === 0 ? "pushed" : "rejected";
 }
 
+/** What {@link fetchRefIntoStatus} found: the ref fetched, no remote, the remote answered without the ref, or the fetch failed. */
+export type FetchRefStatus = "fetched" | "no-remote" | "missing" | "failed";
+
 /**
  * Fetch one arbitrary remote ref into a local ref of a possibly *different*
  * name (#1959 finding 3). `+` forces the update even when it isn't a
@@ -1145,12 +1181,26 @@ export async function fetchRefInto(
   localRef: string,
   opts?: { cwd?: string },
 ): Promise<boolean> {
+  return (await fetchRefIntoStatus(remoteRef, localRef, opts)) === "fetched";
+}
+
+/**
+ * {@link fetchRefInto}, saying why nothing was fetched (#2732). `missing`
+ * means the remote answered and does not carry the ref, which for a lease is
+ * the news that it was released there.
+ */
+export async function fetchRefIntoStatus(
+  remoteRef: string,
+  localRef: string,
+  opts?: { cwd?: string },
+): Promise<FetchRefStatus> {
   const rt = getRuntime();
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
-  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return "no-remote";
   const remote = remoteResult.stdout.trim().split("\n")[0];
-  const fetchResult = await rt.spawn(["git", "fetch", remote, `+${remoteRef}:${localRef}`], { cwd: opts?.cwd });
-  return fetchResult.exitCode === 0;
+  const fetchResult = await rt.spawn(["git", "fetch", remote, `+${remoteRef}:${localRef}`], { cwd: opts?.cwd, env: C_LOCALE_ENV });
+  if (fetchResult.exitCode === 0) return "fetched";
+  return NO_SUCH_REMOTE_REF_RE.test(fetchResult.stderr ?? "") ? "missing" : "failed";
 }
 
 /**

package/src/lifecycle/lease.test.ts

@@ -285,6 +285,28 @@ describe("lifecycle/lease", () => {
       }
     });
 
+    // #2732: pushRef passed `--force` beside `--force-with-lease`, and git
+    // lets `--force` win, so every lease push was unconditional. It now pushes
+    // under the lease alone, expecting the value last fetched, so a renewal
+    // lands and a release deletes the ref on the remote.
+    test("a renewal and a release reach the remote, under the lease the last fetch saw (#2732)", async () => {
+      const { clonePath, remotePath, cleanup } = await setupClonePair();
+      try {
+        const ref = leaseRef("fountain-converge");
+        const first = await acquireLease("fountain-converge", "operator-a", { cwd: clonePath, ttlMs: 60_000 });
+        expect(first.acquired).toBe(true);
+        const renewed = await acquireLease("fountain-converge", "operator-a", { cwd: clonePath, ttlMs: 120_000 });
+        expect(renewed.lease?.token).toBe(first.lease?.token);
+        const local = git(["rev-parse", ref], clonePath).stdout.trim();
+        expect(git(["rev-parse", ref], remotePath).stdout.trim()).toBe(local);
+
+        expect(await releaseLease("fountain-converge", "operator-a", renewed.lease!.token, { cwd: clonePath })).toBe(true);
+        expect(git(["rev-parse", "--verify", ref], remotePath).exitCode).not.toBe(0);
+      } finally {
+        await cleanup();
+      }
+    });
+
     // ── #1959 finding 3 ──────────────────────────────────────────────────
     //
     // `readLease` used to fetch the remote lease ref directly into the same