@nanobpm/nano-workforce 0.205.2 → 0.206.1

package/.github/workflows/release.yml

@@ -197,8 +197,11 @@ jobs:
       # token, still OIDC + provenance via the job's id-token. This step is a NO-OP
       # when the release step succeeded or when the version is already on npm, so it
       # can never double-publish. If OIDC stays down through every retry, fail loudly:
-      # a human must `npm publish` the pushed tag locally (npm login with 2FA, then
-      # `git checkout vX.Y.Z && npm ci && npm publish --provenance --access public`).
+      # a human must `npm publish` the pushed tag locally — restoring the build identity first,
+      # because a fresh tag checkout has no build-info.json and plain `npm publish` skips the
+      # prepare hook (npm login with 2FA, then `git checkout vX.Y.Z && npm ci &&
+      # node --experimental-strip-types scripts/write-build-info.ts X.Y.Z --sha "$(git rev-parse
+      # vX.Y.Z^)" && npm publish --provenance --access public`; see the ::error:: message below).
       - name: Retry OIDC publish if the release publish failed
         if: steps.release.outcome == 'failure'
         env:
@@ -213,6 +216,18 @@ jobs:
             exit 0
           fi
           echo "semantic-release prepared + tagged ${PKG}@${VERSION} but the OIDC publish failed; retrying."
+          # Reuse the build-info.json that semantic-release's prepare step already wrote (prepareCmd
+          # in .releaserc.json) — do NOT regenerate it here. By the time this retry runs,
+          # @semantic-release/git has already created the release commit, so HEAD is that
+          # metadata-only `chore(release)` commit, NOT the source HEAD the release was cut from.
+          # Re-running write-build-info.ts would call `git rev-parse HEAD` and overwrite the recorded
+          # source SHA with the release commit's SHA (and replace builtAt), making the documented
+          # identity depend on whether OIDC publishing failed. The prepared file is already present
+          # in this checkout with the correct source HEAD; this step re-packs via plain `npm publish`
+          # (which runs OUTSIDE semantic-release, so the prepare hook does not re-run), so the baked
+          # file is packed as-is. Validate it is present and well-formed (fail loudly if a future
+          # change ever drops it) rather than regenerate it from the changed HEAD (issue #925).
+          node --experimental-strip-types scripts/write-build-info.ts --check
           published=false
           for attempt in 1 2 3; do
             echo "OIDC publish attempt ${attempt}/3 for ${PKG}@${VERSION}"
@@ -224,7 +239,7 @@ jobs:
             sleep $((attempt * 30))
           done
           if [ "$published" != true ]; then
-            echo "::error::OIDC publish of ${PKG}@${VERSION} still failing after retries. The git tag v${VERSION} is pushed but npm has no tarball. Publish it locally: 'git fetch --tags && git checkout v${VERSION} && npm ci && npm publish --provenance --access public' (npm login with 2FA first)."
+            echo "::error::OIDC publish of ${PKG}@${VERSION} still failing after retries. The git tag v${VERSION} is pushed but npm has no tarball. Publish it locally (npm login with 2FA first): 'git fetch --tags && git checkout v${VERSION} && npm ci && node --experimental-strip-types scripts/write-build-info.ts ${VERSION} --sha \"\$(git rev-parse v${VERSION}^)\" && node --experimental-strip-types scripts/write-build-info.ts --check && npm publish --provenance --access public'. The write-build-info step is REQUIRED: a fresh tag checkout has no build-info.json (it is an uncommitted build artifact) and plain npm publish does not run the semantic-release prepare hook, so without it the package ships with gitSha: null. Passing --sha \"\$(git rev-parse v${VERSION}^)\" records the SOURCE HEAD (the tag's parent), not the metadata-only release commit the tag points at."
             exit 1
           fi
           # semantic-release aborts before @semantic-release/github when the npm

package/.releaserc.json

@@ -40,6 +40,13 @@
     "@semantic-release/changelog",
     "@semantic-release/npm",
     "@semantic-release/github",
+    [
+      "@semantic-release/exec",
+      {
+        "//": "Bake the build identity into the package (issue #925). prepareCmd runs in semantic-release's prepare step — AFTER @semantic-release/npm bumps package.json to ${nextRelease.version} and BEFORE it packs/publishes the tarball — so the published package ships build-info.json and an npm-installed instance (no .git, no env override) can still report its gitSha. The recorded gitSha is the SOURCE HEAD the release is cut from; the tag commit is created afterwards by @semantic-release/git (see scripts/write-build-info.ts). There is deliberately NO verifyConditionsCmd: semantic-release runs verifyConditions BEFORE it computes nextRelease, so ${nextRelease.version} interpolates empty there and the command would fail with EVERIFYCONDITIONS, blocking every release. The workflow's OIDC-retry step re-runs plain `npm publish` (which re-packs) in the same checkout — where prepare already wrote build-info.json — and validates + reuses that prepared file (it does NOT regenerate it: by then HEAD is the release commit, so re-running the writer would overwrite the source SHA with the release commit's SHA; see release.yml), so the retry never publishes a tarball with no or wrong build-info.json.",
+        "prepareCmd": "node --experimental-strip-types scripts/write-build-info.ts ${nextRelease.version}"
+      }
+    ],
     [
       "@semantic-release/git",
       {

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.206.1](https://github.com/nanobpm/nano-workforce/compare/v0.206.0...v0.206.1) (2026-11-08)
+
+### Bug Fixes
+
+* **merge:** fail the review backstop closed and retire review waits on merged PRs ([#928](https://github.com/nanobpm/nano-workforce/issues/928)) ([973c161](https://github.com/nanobpm/nano-workforce/commit/973c161d8b279db21915601647c5e8c43f3cac2f)), closes [nano-bpm#1467](https://github.com/nanobpm/nano-bpm/issues/1467) [#927](https://github.com/nanobpm/nano-workforce/issues/927)
+
+## [0.206.0](https://github.com/nanobpm/nano-workforce/compare/v0.205.2...v0.206.0) (2026-11-08)
+
+### Features
+
+* **version:** bake the git SHA into release packages and report identity on /status ([#926](https://github.com/nanobpm/nano-workforce/issues/926)) ([e5eedca](https://github.com/nanobpm/nano-workforce/commit/e5eedca0ee28db1f54167b4bb962ce4c06776e9f)), closes [#925](https://github.com/nanobpm/nano-workforce/issues/925) [#925](https://github.com/nanobpm/nano-workforce/issues/925) [#925](https://github.com/nanobpm/nano-workforce/issues/925) [#925](https://github.com/nanobpm/nano-workforce/issues/925)
+
 ## [0.205.2](https://github.com/nanobpm/nano-workforce/compare/v0.205.1...v0.205.2) (2026-11-08)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -301,7 +301,7 @@ export const ENV_CONTRACTS = {
     name: "NANO_WORKFORCE_GIT_SHA",
     owner: "app/version.ts",
     semantics:
-      "Explicit git SHA override for version reporting on deploys shipped without a .git directory; version derivation reads .git when unset.",
+      "Explicit git SHA override for version reporting on deploys shipped without a .git directory; version derivation reads .git when unset, then falls back to the release-baked build-info.json (issue #925).",
   },
   NANO_AUTO_RETRO: {
     category: "env",

package/app/pollReviewsTerminal.test.ts

@@ -0,0 +1,175 @@
+// Regression for issue #927 §3 (nano-bpm#1467): after the PR merged, the convergence loop kept
+// re-requesting Copilot reviews on the MERGED PR for six rounds and finally escalated a review
+// timeout. `pollReviews` must check the PR's live state before re-soliciting: a merged/closed PR
+// retires the parked convergence instance and closes the row out — no reviewer-request POST.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import { pollReviews } from "./service.ts";
+
+const REPO = "owner/repo";
+const NUMBER = 9;
+
+function memTable(rows: any[], key: string, lookups: unknown[] = []) {
+  return {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    all: () => Promise.resolve([...rows]),
+    find: (q: any) => Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any) => {
+      lookups.push(q);
+      return Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null);
+    },
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    delete: () => Promise.resolve(),
+  };
+}
+
+type Opts = { reviewsFail?: boolean; reviews?: unknown[]; cancelFails?: boolean; searchState?: string | null };
+
+async function run(prState: { merged: boolean; state: string }, opts: Opts = {}) {
+  const row: any = {
+    pr_key: `${REPO}#${NUMBER}`,
+    repo: REPO,
+    number: NUMBER,
+    status: "waiting_review",
+    last_review_id: 0,
+    waiting_since: "2026-11-08T15:08:58Z",
+    last_nudge_at: "2000-01-01T00:00:00Z",
+    process_key: "589000",
+    updated_at: "t0",
+  };
+  const planLookups: unknown[] = [];
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], key: "pr_key" },
+    merges: { rows: [], key: "id" },
+    plan_tasks: { rows: [], key: "id" },
+  };
+  const data = {
+    table: withTrackingViews((name: string, key: string) => {
+      stores[name] ??= { rows: [], key };
+      return memTable(stores[name].rows, stores[name].key, name === "plan_tasks" ? planLookups : []);
+    }),
+  } as any;
+  const cancelled: string[] = [];
+  const published: string[] = [];
+  const engine = {
+    publishMessage: (m: { name: string }) => {
+      published.push(m.name);
+      return Promise.resolve();
+    },
+    cancelInstance: (a: { processInstanceKey: string }) => {
+      if (opts.cancelFails) return Promise.reject(new Error("transient engine error"));
+      cancelled.push(a.processInstanceKey);
+      return Promise.resolve();
+    },
+    searchProcessInstances: () =>
+      Promise.resolve(
+        opts.searchState === null ? [] : [{ processInstanceKey: "589000", state: opts.searchState ?? "ACTIVE" }],
+      ),
+  } as any;
+  const posts: string[] = [];
+  const prevFetch = globalThis.fetch;
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "test-token";
+  globalThis.fetch = ((url: string | URL | Request, init?: RequestInit) => {
+    const u = String(url);
+    const method = (init?.method ?? "GET").toUpperCase();
+    const json = (b: unknown, status = 200) => Promise.resolve(new Response(JSON.stringify(b), { status }));
+    if (method !== "GET") posts.push(`${method} ${u}`);
+    if (u.includes(`/pulls/${NUMBER}/requested_reviewers`)) return method === "GET" ? json({ users: [] }) : json({}, 201);
+    if (u.includes(`/pulls/${NUMBER}/reviews`) && opts.reviewsFail) return json({ message: "bad gateway" }, 502);
+    if (u.includes(`/pulls/${NUMBER}/reviews`)) return json(opts.reviews ?? []); // default: review requested, none arrived
+    if (u.includes("/git/ref")) return json({ object: { sha: "e597b399" } });
+    if (u.endsWith(`/pulls/${NUMBER}`)) return json({ ...prState, mergeable_state: "clean", head: { sha: "e597b399" } });
+    return json({}, 404);
+  }) as typeof fetch;
+  try {
+    await pollReviews(data, engine, "test-token");
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+    else delete process.env["GITHUB_TOKEN"];
+  }
+  return { row, posts, cancelled, published, stores, planLookups };
+}
+
+test("pollReviews #927: a PR MERGED while awaiting review retires the loop — no review re-request", async () => {
+  const { row, posts, cancelled, published } = await run({ merged: true, state: "closed" });
+  assertEquals(posts.length, 0, "no reviewer-request POST on a merged PR");
+  assertEquals(cancelled, ["589000"], "the parked convergence instance is retired");
+  assertEquals(published.length, 0);
+  assertEquals(row.status, "merged");
+  assertEquals(typeof row.merged_at, "string");
+});
+
+test("pollReviews #927: a PR CLOSED unmerged while awaiting review is abandoned — no review re-request", async () => {
+  const { row, posts, cancelled, stores } = await run({ merged: false, state: "closed" });
+  assertEquals(posts.length, 0);
+  assertEquals(cancelled, ["589000"]);
+  assertEquals((stores.merges.rows as any[]).some((m) => m.method === "pr-closed"), true);
+  assertEquals(row.status === "waiting_review", false);
+});
+
+test("pollReviews #927: an OPEN PR awaiting review is still re-solicited (control)", async () => {
+  const { row, posts, cancelled } = await run({ merged: false, state: "open" });
+  assertEquals(cancelled.length, 0);
+  assertEquals(row.status, "waiting_review");
+  assertEquals(posts.length, 1, "the review nudge still fires for a live PR");
+});
+
+const HEAD_CURRENT_REVIEW = [
+  { id: 77, state: "COMMENTED", submitted_at: "2026-11-08T16:00:00Z", commit_id: "e597b399", user: { login: "copilot-pull-request-reviewer[bot]" } },
+];
+
+for (const [label, prState] of [
+  ["MERGED", { merged: true, state: "closed" }],
+  ["CLOSED", { merged: false, state: "closed" }],
+] as const) {
+  test(`pollReviews #927: a HEAD-CURRENT review on a ${label} PR retires the loop — never resumes a round`, async () => {
+    const { row, posts, cancelled, published } = await run(prState, { reviews: HEAD_CURRENT_REVIEW });
+    assertEquals(published.length, 0, "no readiness-ready published for a terminal PR");
+    assertEquals(posts.length, 0);
+    assertEquals(cancelled, ["589000"]);
+    assertEquals(row.status === "waiting_review" || row.status === "converging", false);
+  });
+}
+
+test("pollReviews #927: a failed cancel of a still-LIVE instance leaves the row pollable", async () => {
+  const { row, posts, published } = await run({ merged: true, state: "closed" }, { cancelFails: true, searchState: "ACTIVE" });
+  assertEquals(row.status, "waiting_review", "not finalized while the instance (and its timer) lives");
+  assertEquals(posts.length, 0, "no re-solicit this pass");
+  assertEquals(published.length, 0);
+});
+
+for (const searchState of ["COMPLETED", null] as const) {
+  test(`pollReviews #927: a failed cancel of an already-${searchState ?? "gone"} instance still finalizes`, async () => {
+    const { row } = await run({ merged: true, state: "closed" }, { cancelFails: true, searchState });
+    assertEquals(row.status, "merged");
+  });
+}
+
+test("pollReviews #927: a PR merged externally while awaiting review runs the retro hook", async () => {
+  // maybeStartRetro resolves the PR's plan via `plan_tasks`; the lookup proves the hook ran.
+  const { planLookups } = await run({ merged: true, state: "closed" });
+  assertEquals(planLookups, [{ pr_key: `${REPO}#${NUMBER}` }]);
+});
+
+test("pollReviews #927: a MERGED PR whose review fetch FAILS is still retired (terminal check precedes fetch)", async () => {
+  const { row, posts, cancelled, published } = await run({ merged: true, state: "closed" }, { reviewsFail: true });
+  assertEquals(cancelled, ["589000"]);
+  assertEquals(published.length, 0);
+  assertEquals(posts.length, 0);
+  assertEquals(row.status, "merged");
+});

package/app/service.ts

@@ -100,6 +100,7 @@ import { ENGINE_TERMINAL_STATES } from "./reconcile.ts";
 // (submitPr/startMerge) and re-exported below so the long-standing `import { repoEnvelopeVars } from
 // "./service.ts"` call sites (and its tests) keep resolving.
 import { repoEnvelopeVars } from "./repoEnvelope.ts";
+import { maybeStartRetro } from "./retro.ts";
 import { clampNudgeMinutes, isoDurationToMs, isReviewStale, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
@@ -1283,6 +1284,13 @@ export async function pollReviews(data: DataLayer, engine: EngineClient, token:
     const { repo, number, pr_key: prKey } = pr;
     const lastId = pr.last_review_id ?? 0;
     try {
+      // #927: a PR that already landed/closed must never resume or re-solicit a review — whatever
+      // the review freshness (no review, stale review, OR a head-current one landing after the
+      // merge). Check terminal state FIRST — before even fetching reviews, so a failing
+      // reviews endpoint (e.g. 502) can't strand a merged PR in `waiting_review` with a live timer — so no branch below can route a merged PR back into a
+      // review round. `null` → handled-but-not-finalized (cancel failed): skip this pass, stay pollable.
+      const retired = await retireTerminalReviewWait(data, engine, pr, token);
+      if (retired !== false) continue;
       const reviews = await fetchPrReviews(repo, number, token);
       if (reviews === null) return; // no usable transport (no gh, no token) → idle
       const fresh = reviews
@@ -1342,6 +1350,60 @@ export async function pollReviews(data: DataLayer, engine: EngineClient, token:
   }
 }
 
+/** Review-wait out-of-band terminal check (issue #927). nano-bpm#1467 landed while its convergence
+ * loop was parked at `wait-review`; the poller then kept re-requesting Copilot reviews on the MERGED
+ * PR for six rounds and finally escalated a review timeout no human could act on. Before any
+ * re-solicitation, read the PR's live state: if it is terminal (merged or closed) the review wait is
+ * moot, so RETIRE the parked convergence instance (`process_key`) and close the row out — `merged`
+ * (with `merged_at`) for a landed PR, the canonical `abandonClosedPr` for a closed-unmerged one.
+ * Conservative: an unreadable/open state returns `false` and the caller re-solicits as before.
+ * Exported for tests. */
+export async function retireTerminalReviewWait(
+  data: DataLayer,
+  engine: EngineClient,
+  pr: PullRequest,
+  token: string,
+): Promise<boolean | null> {
+  const st = await fetchPrState(pr.repo, pr.number, token).catch(() => null);
+  const liveness = classifyPrLiveness(st);
+  if (liveness !== "merged" && liveness !== "closed") return false;
+  if (pr.process_key != null) {
+    const key = String(pr.process_key);
+    try {
+      await engine.cancelInstance({ processInstanceKey: key });
+    } catch (err) {
+      // Only finalize the row once the instance is confirmed gone/terminal: a transiently-failed
+      // cancel would otherwise drop the row from `waiting_review` scans while the live instance's
+      // review-timeout timer still escalates a human. Unconfirmed → stay pollable, retry next pass.
+      let confirmedTerminal = false;
+      try {
+        const match = (await engine.searchProcessInstances({ processInstanceKeys: [key] })).find(
+          (s) => String(s.processInstanceKey) === key,
+        );
+        confirmedTerminal = !match || ENGINE_TERMINAL_STATES.has(String(match.state ?? "").trim().toUpperCase());
+      } catch {
+        confirmedTerminal = false;
+      }
+      if (!confirmedTerminal) {
+        console.error(`[poller] ${pr.pr_key}: retire review-wait instance ${key} failed, retrying next pass: ${err}`);
+        return null;
+      }
+    }
+  }
+  if (liveness === "merged") {
+    const ts = now();
+    await prs(data).update(pr.pr_key, { status: "merged", merged_at: ts, updated_at: ts });
+    // Reuse the merged-completion side effect `pr.mark-merged`/`pr.finalize` run: an externally
+    // merged PR may be its plan's last to settle, so its automatic retrospective must still start.
+    // `maybeStartRetro` is best-effort and never throws.
+    await maybeStartRetro(data, engine, pr.pr_key);
+  } else {
+    await abandonClosedPr(data, pr.pr_key, "PR was closed on GitHub while awaiting review — retiring the convergence loop");
+  }
+  console.log(`[poller] ${liveness} while waiting for review -> retired loop ${pr.pr_key}`);
+  return true;
+}
+
 /** Ensure a Copilot review is in flight for a PR still waiting, throttled to one attempt per
  * REVIEW_NUDGE_MS window. Skips when Copilot is already a pending reviewer (a review is coming);
  * otherwise re-requests one and records the nudge. This is the primary liveness mechanism — the

package/app/version.test.ts

@@ -0,0 +1,204 @@
+// Tests for app/version.ts identity resolution (issue #925).
+//
+// The module probes the working tree ONCE at import time (STATIC), so each scenario imports a
+// cache-busted copy (`?scenario=…`) to re-run the probe under a controlled environment:
+//   - env override (NANO_WORKFORCE_GIT_SHA) always wins;
+//   - a live .git checkout beats the baked build-info.json;
+//   - with neither env nor .git, the release-baked build-info.json is the fallback (the npm-install
+//     case — the whole point of #925);
+//   - gitTag/builtAt are exposed from build-info.json when known, null on a plain checkout.
+//
+// The "no .git" scenarios copy the app's identity inputs (package.json + build-info.json) into a
+// temp dir WITHOUT a .git directory and load a thin re-export fixture from there — the fixture's
+// own location is what `version.ts` derives REPO_ROOT from, so loading it via the temp path
+// reproduces an npm-installed layout faithfully.
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { buildVersionInfo } from "./version.ts";
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+// A build-info.json the release pipeline would have baked (scripts/write-build-info.ts shape).
+const BAKED = {
+  version: "9.9.9",
+  gitSha: "0123456789abcdef0123456789abcdef01234567",
+  gitTag: "v9.9.9",
+  builtAt: "2026-01-02T03:04:05.000Z",
+};
+
+/** Materialise an npm-install-like layout (package.json + build-info.json, NO .git) in a temp dir. */
+function npmInstallLayout(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-version-"));
+  writeFileSync(
+    join(dir, "package.json"),
+    // "type": "module" so the copied version.ts loads as ESM without a MODULE_TYPELESS_PACKAGE_JSON warning.
+    JSON.stringify({ name: "@nanobpm/nano-workforce", version: BAKED.version, type: "module" }),
+  );
+  writeFileSync(join(dir, "build-info.json"), JSON.stringify(BAKED));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+/**
+ * Import version.ts AS IF it lived under `dir` (a copy whose REPO_ROOT resolves to `dir`).
+ * version.ts derives REPO_ROOT as dirname(dirname(import.meta.url)) — it lives in `app/` — so the
+ * copy must sit at the SAME depth (`<dir>/app/version-copy.ts`) for the derivation to land on `dir`.
+ */
+async function importFrom(dir: string) {
+  const { mkdirSync, readFileSync } = await import("node:fs");
+  const src = readFileSync(new URL("./version.ts", import.meta.url), "utf8");
+  mkdirSync(join(dir, "app"), { recursive: true });
+  const dest = join(dir, "app", `version-copy-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`);
+  writeFileSync(dest, src);
+  return (await import(dest)) as typeof import("./version.ts");
+}
+
+async function withEnv<T>(key: string, value: string | undefined, fn: () => Promise<T>): Promise<T> {
+  const prev = process.env[key];
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+  try {
+    return await fn();
+  } finally {
+    if (prev === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+}
+
+test("a live .git checkout resolves gitSha from HEAD (the dev-clone case)", () => {
+  // This test itself runs from a real checkout, so the plain import sees .git.
+  const info = buildVersionInfo();
+  assert(info.gitSha == null || SHA_RE.test(info.gitSha), `gitSha is null or 40-hex, got ${info.gitSha}`);
+});
+
+test("a live .git checkout WINS over a competing baked build-info.json (checkout > baked)", async () => {
+  // Precedence guard (issue #925): env > .git checkout > build-info.json. Lay out BOTH a live
+  // (detached) .git whose HEAD SHA differs from the baked one AND a build-info.json, with no env
+  // override, and assert HEAD wins. Without a competing baked file this could not catch the baked
+  // fallback incorrectly taking precedence over the checkout.
+  const dir = mkdtempSync(join(tmpdir(), "nwf-version-precedence-"));
+  try {
+    const checkoutSha = "cccccccccccccccccccccccccccccccccccccccc";
+    writeFileSync(
+      join(dir, "package.json"),
+      JSON.stringify({ name: "@nanobpm/nano-workforce", version: BAKED.version, type: "module" }),
+    );
+    // A live checkout: .git is a directory whose HEAD is a detached commit SHA distinct from the baked one.
+    mkdirSync(join(dir, ".git"), { recursive: true });
+    writeFileSync(join(dir, ".git", "HEAD"), `${checkoutSha}\n`);
+    // A competing baked file whose gitSha must LOSE to the checkout above.
+    writeFileSync(join(dir, "build-info.json"), JSON.stringify(BAKED));
+    await withEnv("NANO_WORKFORCE_GIT_SHA", undefined, async () => {
+      const mod = await importFrom(dir);
+      const info = mod.buildVersionInfo();
+      assertEquals(info.gitSha, checkoutSha, "the live .git checkout beats the baked build-info.json");
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("env override NANO_WORKFORCE_GIT_SHA wins over .git and build-info.json", async () => {
+  const envSha = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+  await withEnv("NANO_WORKFORCE_GIT_SHA", envSha, async () => {
+    const mod = (await import(`./version.ts?env-wins=${Date.now()}`)) as typeof import("./version.ts");
+    assertEquals(mod.buildVersionInfo().gitSha, envSha);
+  });
+});
+
+test("env override wins even in an npm-install layout (env > build-info.json)", async () => {
+  const { dir, cleanup } = npmInstallLayout();
+  try {
+    const envSha = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+    await withEnv("NANO_WORKFORCE_GIT_SHA", envSha, async () => {
+      const mod = await importFrom(dir);
+      assertEquals(mod.buildVersionInfo().gitSha, envSha, "env beats the baked build-info.json");
+    });
+  } finally {
+    cleanup();
+  }
+});
+
+test("with no env and no .git, gitSha falls back to the baked build-info.json (the npm-install case)", async () => {
+  const { dir, cleanup } = npmInstallLayout();
+  try {
+    await withEnv("NANO_WORKFORCE_GIT_SHA", undefined, async () => {
+      const mod = await importFrom(dir);
+      const info = mod.buildVersionInfo();
+      assertEquals(info.gitSha, BAKED.gitSha, "build-info.json is the fallback source of gitSha");
+      assertEquals(info.gitTag, BAKED.gitTag, "gitTag is exposed from build-info.json");
+      assertEquals(info.builtAt, BAKED.builtAt, "builtAt is exposed from build-info.json");
+      assertEquals(info.gitBranch, null, "no .git → no branch");
+      assertEquals(info.version, BAKED.version, "version still comes from package.json");
+    });
+  } finally {
+    cleanup();
+  }
+});
+
+test("a malformed build-info.json (non-string gitSha) is ignored, not fatal", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-version-bad-"));
+  try {
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "@nanobpm/nano-workforce", version: "1.0.0", type: "module" }));
+    writeFileSync(join(dir, "build-info.json"), JSON.stringify({ version: "1.0.0", gitSha: 42 }));
+    await withEnv("NANO_WORKFORCE_GIT_SHA", undefined, async () => {
+      const mod = await importFrom(dir);
+      const info = mod.buildVersionInfo();
+      assertEquals(info.gitSha, null);
+      assertEquals(info.gitTag, null);
+      assertEquals(info.builtAt, null);
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a build-info.json whose gitSha is a non-blank but non-40-hex string is rejected (fail closed)", async () => {
+  // Regression for the malformed-baked-SHA finding: a payload like `gitSha: "not-a-sha"` must NOT
+  // be reported as the commit — the getter fails closed and reports null rather than surfacing an
+  // invalid commit on the identity endpoints.
+  const dir = mkdtempSync(join(tmpdir(), "nwf-version-badsha-"));
+  try {
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "@nanobpm/nano-workforce", version: "1.0.0", type: "module" }));
+    writeFileSync(
+      join(dir, "build-info.json"),
+      JSON.stringify({ version: "1.0.0", gitSha: "not-a-sha", gitTag: "v1.0.0", builtAt: "2026-01-02T03:04:05.000Z" }),
+    );
+    await withEnv("NANO_WORKFORCE_GIT_SHA", undefined, async () => {
+      const mod = await importFrom(dir);
+      const info = mod.buildVersionInfo();
+      assertEquals(info.gitSha, null, "a malformed baked SHA is ignored, not reported");
+      assertEquals(info.gitTag, null, "the whole baked payload is dropped when its gitSha is invalid");
+      assertEquals(info.builtAt, null);
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("gitTag/builtAt are always present in the payload (null on a plain checkout)", () => {
+  // The committed repo carries no build-info.json, so a dev checkout reports the release-only
+  // fields as null; the assertion keys off the SAME getter the endpoint uses, so it documents the
+  // contract either way.
+  const info = buildVersionInfo();
+  assert("gitTag" in info && "builtAt" in info, "the fields are always present in the payload");
+});
+
+test("a build-info.json with a valid SHA but an unparseable builtAt is rejected (shared validator)", async () => {
+  // Regression: the reader once validated only gitSha, so `builtAt: "not-a-date"` reached /version
+  // even though the writer's buildInfoProblems() rejects it. Reader + writer now share one validator.
+  const dir = mkdtempSync(join(tmpdir(), "nwf-version-baddate-"));
+  try {
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "@nanobpm/nano-workforce", version: "1.0.0", type: "module" }));
+    writeFileSync(join(dir, "build-info.json"), JSON.stringify({ ...BAKED, builtAt: "not-a-date" }));
+    await withEnv("NANO_WORKFORCE_GIT_SHA", undefined, async () => {
+      const mod = await importFrom(dir);
+      const info = mod.buildVersionInfo();
+      assertEquals(info.gitSha, null, "the whole baked payload is dropped when builtAt is invalid");
+      assertEquals(info.builtAt, null);
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});