@nanobpm/nano-workforce 0.205.2 → 0.206.0

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,9 @@
+## [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/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 });
+  }
+});

package/app/version.ts

@@ -5,8 +5,10 @@
 // inspecting the working tree at runtime. This module gathers that identity — the app's package
 // version, the resolved `@nanobpm/urban` version, the git commit (read from `.git`, handling both
 // an ordinary `.git` directory and the `gitdir:` file pointer used by worktrees/submodules, with
-// an env override for detached deploys), plus the Node runtime, pid and start time — so an operator
-// debugging a stuck instance can confirm the process is on the code they think it is.
+// an env override for detached deploys AND a `build-info.json` fallback baked into the release
+// package — an npm install has neither `.git` nor the env var, issue #925), plus the Node runtime,
+// pid and start time — so an operator debugging a stuck instance can confirm the process is on the
+// code they think it is.
 //
 // Every probe is best-effort: a missing file or unavailable `.git` yields `null` for that field
 // rather than throwing, so `/app/api/version` never fails just because one source is absent.
@@ -98,17 +100,68 @@ function urbanVersion(): string | null {
   return typeof pkg?.version === "string" ? pkg.version : null;
 }
 
+/**
+ * The build identity baked into the release package (`build-info.json` at the package root) by
+ * `scripts/write-build-info.ts` during semantic-release's `prepare` step (issue #925). An npm
+ * install ships this file but no `.git`, so it is the ONLY source of `gitSha` there. Its `gitSha`
+ * is the SOURCE HEAD the release was cut from (the tag commit does not exist yet at prepare time);
+ * its `gitTag` names the tag placed on the release commit, whose tree matches that source HEAD
+ * except for the version-bump metadata. Returns null on a dev checkout, which has no such file.
+ */
+export const SHA_RE = /^[0-9a-f]{40}$/;
+
+/** Validate a parsed build-info payload; returns a list of problems (empty = valid). The single
+ * validator shared by the writer (scripts/write-build-info.ts) and the reader below. */
+export function buildInfoProblems(info: unknown): string[] {
+  const problems: string[] = [];
+  if (typeof info !== "object" || info == null) return ["build-info.json is not a JSON object"];
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape (parsed JSON)
+  const bi = info as Record<string, unknown>;
+  if (typeof bi.version !== "string" || !bi.version.trim()) problems.push("version must be a non-blank string");
+  if (typeof bi.gitSha !== "string" || !SHA_RE.test(bi.gitSha)) problems.push("gitSha must be a 40-hex string");
+  if (typeof bi.gitTag !== "string" || !bi.gitTag.trim()) problems.push("gitTag must be a non-blank string");
+  if (typeof bi.builtAt !== "string" || Number.isNaN(Date.parse(bi.builtAt)))
+    problems.push("builtAt must be an ISO-8601 timestamp");
+  return problems;
+}
+
+
+function buildInfo(): { version: string; gitSha: string; gitTag: string; builtAt: string } | null {
+  const raw = readJson(join(REPO_ROOT, "build-info.json"));
+  if (raw == null) return null;
+  // Fail closed on ANY malformed field (bad SHA, unparseable builtAt, blank tag/version): a corrupt
+  // or tampered build-info.json is ignored wholesale rather than partially surfaced. Uses the SAME
+  // validator the writer's --check uses, so reader and writer can never drift.
+  if (buildInfoProblems(raw).length > 0) return null;
+  return {
+    version: String(raw.version),
+    gitSha: String(raw.gitSha),
+    gitTag: String(raw.gitTag),
+    builtAt: String(raw.builtAt),
+  };
+}
+
 /**
  * The git commit the working tree is on, read straight from `.git` so it reflects the ACTUAL
  * checked-out code — not a value baked at some earlier build. Resolves a symbolic `HEAD`
  * (`ref: refs/heads/…`) via the loose ref file (checking both the per-worktree and common dirs),
- * falling back to `packed-refs`. An explicit `NANO_WORKFORCE_GIT_SHA` env var wins (for deploys
- * that ship without a `.git` directory).
+ * falling back to `packed-refs`. Resolution order (issue #925): an explicit
+ * `NANO_WORKFORCE_GIT_SHA` env var wins (for deploys that ship without a `.git` directory), then
+ * the live `.git` checkout, then the release-baked `build-info.json` (the only source available to
+ * an npm-installed instance).
  */
 function gitSha(): string | null {
   const env = envVar("NANO_WORKFORCE_GIT_SHA");
   if (env) return env;
 
+  const fromCheckout = gitShaFromCheckout();
+  if (fromCheckout != null) return fromCheckout;
+
+  return buildInfo()?.gitSha ?? null;
+}
+
+/** The commit SHA read from the live `.git` checkout, or null when there is none (npm install). */
+function gitShaFromCheckout(): string | null {
   const dirs = resolveGitDirs();
   if (dirs == null) return null;
   const head = readText(join(dirs.gitDir, "HEAD"));
@@ -160,6 +213,10 @@ export interface VersionInfo {
   urbanVersion: string | null;
   gitSha: string | null;
   gitBranch: string | null;
+  /** The release tag (e.g. "v0.206.0") from the baked `build-info.json`; null on a dev checkout. */
+  gitTag: string | null;
+  /** ISO-8601 time the release package was built (from `build-info.json`); null on a dev checkout. */
+  builtAt: string | null;
   runtime: string;
   pid: number | null;
   startedAt: string;
@@ -172,12 +229,15 @@ export interface VersionInfo {
  */
 const STATIC: Omit<VersionInfo, "uptimeSeconds"> = (() => {
   const pkg = appPackage();
+  const build = buildInfo();
   return Object.freeze({
     name: appName(pkg),
     version: appVersion(pkg),
     urbanVersion: urbanVersion(),
     gitSha: gitSha(),
     gitBranch: gitBranch(),
+    gitTag: build?.gitTag || null,
+    builtAt: build?.builtAt || null,
     runtime: runtime(),
     pid: typeof process.pid === "number" ? process.pid : null,
     startedAt: STARTED_AT.toISOString(),

package/build-info.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.206.0",
+  "gitSha": "e5eedca0ee28db1f54167b4bb962ce4c06776e9f",
+  "gitTag": "v0.206.0",
+  "builtAt": "2026-11-08T12:12:11.017Z"
+}

package/docs/agent-guide.md

@@ -26,6 +26,11 @@ curl -sS __BASE__/version | jq   # tool: getVersion: app/urban version, git sha,
 curl -sS __BASE__/status  | jq   # tool: listActivePrs: every PR in flight
 ```
 
+`/status` also carries the running app's build identity as a top-level `version` object
+(`{ version, gitSha }`, the same source as `/version` — env override, then the live `.git`
+checkout, then the release-baked `build-info.json` an npm install ships), so the endpoint
+everyone polls answers "is the fix live?" in one call.
+
 Each `/status` entry carries `prKey` (`owner/repo#123`), `status`, `round`, `processKey`
 (the **engine process-instance key**, the bridge to §5), `openEscalation`,
 `activeWorker`/`leaseUntil` (an agent holds the round, or the job is just queued), and

package/openapi.yaml

@@ -195,6 +195,7 @@ components:
         - count
         - prs
         - deliveries
+        - version
       properties:
         count:
           type: integer
@@ -209,6 +210,26 @@ components:
             first (issue #889 §1 — the opt-in is shown for each PR AND each delivery).
           items:
             $ref: "#/components/schemas/ActiveDelivery"
+        version:
+          type: object
+          additionalProperties: false
+          required:
+            - version
+            - gitSha
+          description: >-
+            The running app's build identity (issue #925), derived from the same app/version.ts
+            getter as GET /version — so the endpoint everyone polls answers "is the fix live?" in
+            one call. gitSha resolves from NANO_WORKFORCE_GIT_SHA, then the .git checkout, then the
+            release-baked build-info.json (the only source an npm install has).
+          properties:
+            version:
+              type: string
+              nullable: true
+              description: The app's package version.
+            gitSha:
+              type: string
+              nullable: true
+              description: The commit the instance runs; null only when no source (env, .git, build-info.json) knows it.
     ActiveDelivery:
       type: object
       description: A delivery-graph run currently in flight, as reported by the status endpoint.
@@ -1561,6 +1582,8 @@ components:
         - urbanVersion
         - gitSha
         - gitBranch
+        - gitTag
+        - builtAt
         - runtime
         - pid
         - startedAt
@@ -1577,9 +1600,24 @@ components:
         gitSha:
           type: string
           nullable: true
+          description: >-
+            The commit the instance runs. Resolution order (issue #925): NANO_WORKFORCE_GIT_SHA env,
+            then the live .git checkout, then the release-baked build-info.json (the only source an
+            npm install has — this is the source HEAD the release was cut from).
         gitBranch:
           type: string
           nullable: true
+        gitTag:
+          type: string
+          nullable: true
+          description: >-
+            The release tag (e.g. "v0.206.0") naming the release commit, from the baked
+            build-info.json; null on a dev checkout. The tag commit's tree matches gitSha's tree
+            except for the version-bump metadata.
+        builtAt:
+          type: string
+          nullable: true
+          description: ISO-8601 time the release package was built (from build-info.json); null on a dev checkout.
         runtime:
           type: string
         pid:

package/operations/getVersion.test.ts

@@ -34,6 +34,9 @@ test("returns 200 with the app identity", async () => {
   assert("urbanVersion" in r.body);
   assert("gitSha" in r.body);
   assert("gitBranch" in r.body);
+  // Release-baked identity fields (issue #925): always present, null on a dev checkout.
+  assert("gitTag" in r.body);
+  assert("builtAt" in r.body);
   assert(typeof r.body.runtime === "string" && r.body.runtime.length > 0);
   assert(typeof r.body.startedAt === "string");
   assert(typeof r.body.uptimeSeconds === "number");

package/operations/listActivePrs.test.ts

@@ -66,6 +66,21 @@ test("returns 200 with a count + projected active PRs", async () => {
   assertEquals(r.body.prs[0].processKey, "9");
 });
 
+test("carries the running app's identity as a top-level version object (issue #925)", async () => {
+  // `/status` is the endpoint everyone polls, so it must answer "is the fix live?" on its own:
+  // version.version + version.gitSha, derived from the SAME app/version.ts getter /version uses.
+  const app = memApp([]);
+  const res = (await handler(input(), app)) as any;
+  assertEquals(res.status, 200);
+  assert("version" in res.body, "the status payload carries a top-level version object");
+  assert("version" in res.body.version, "version.version is present (string|null)");
+  assert("gitSha" in res.body.version, "version.gitSha is present (string|null)");
+  const { buildVersionInfo } = await import("../app/version.ts");
+  const identity = buildVersionInfo();
+  assertEquals(res.body.version.version, identity.version, "derived from the app/version.ts getter, not re-read");
+  assertEquals(res.body.version.gitSha, identity.gitSha, "derived from the app/version.ts getter, not re-read");
+});
+
 test("surfaces the structured openEscalation from the user_tasks read model (both loops)", async () => {
   // Issue #666: openEscalation is derived from the ONE `user_tasks` read model (the same surface
   // `listEscalations` and the Convergence page consume), so `/status` carries the completable

package/operations/listActivePrs.ts

@@ -8,7 +8,7 @@
 // callers must present it via the x-hook-secret header. Unset → open (unchanged default).
 
 import { activeDeliveries, activePrs } from "../app/service.ts";
-import { envVar } from "../app/version.ts";
+import { buildVersionInfo, envVar } from "../app/version.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 // The optional shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via
@@ -21,5 +21,8 @@ export default defineOperation("listActivePrs", async ({ req }, app) => {
     return { status: 401, body: { error: "unauthorized" } };
   }
   const [prs, deliveries] = await Promise.all([activePrs(app.data, app.engine), activeDeliveries(app.data)]);
-  return { status: 200, body: { count: prs.length, prs, deliveries } };
+  // The running app's identity, derived from the SAME app/version.ts getter /version uses (never
+  // re-read), so the endpoint everyone polls answers "is the fix live?" in one call (issue #925).
+  const { version, gitSha } = buildVersionInfo();
+  return { status: 200, body: { count: prs.length, prs, deliveries, version: { version, gitSha } } };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.205.2",
+  "version": "0.206.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -74,6 +74,7 @@
     "@nanobpm/urban-testkit": "^1.6.0",
     "@nanobpm/workflow": "^0.15.0",
     "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^11.0.0",
     "@semantic-release/npm": "^13.1.5",
     "@types/node": "^24.0.0",

package/scripts/write-build-info.test.ts

@@ -0,0 +1,87 @@
+// Tests for scripts/write-build-info.ts — the release-time bake of `build-info.json` (issue #925).
+//
+// The acceptance criterion is end-to-end: an `npm pack` of a tree whose build-info.json was written
+// by this script CONTAINS the file, with a 40-hex gitSha — i.e. the published tarball carries the
+// identity an npm-installed instance falls back to. Plus unit coverage of the payload the script
+// composes (source-HEAD sha, `v<version>` tag, ISO builtAt) and its validation.
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { buildInfoProblems, composeBuildInfo } from "./write-build-info.ts";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const BUILD_INFO = join(REPO_ROOT, "build-info.json");
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+test("composeBuildInfo records the checkout HEAD (40-hex), the v<version> tag, and an ISO builtAt", () => {
+  const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: REPO_ROOT, encoding: "utf8" }).trim();
+  const info = composeBuildInfo("1.2.3", new Date("2026-01-02T03:04:05.000Z"));
+  assertEquals(info.gitSha, head);
+  assert(SHA_RE.test(info.gitSha));
+  assertEquals(info.gitTag, "v1.2.3");
+  assertEquals(info.builtAt, "2026-01-02T03:04:05.000Z");
+  assertEquals(buildInfoProblems(info), []);
+});
+
+test("composeBuildInfo honours an explicit source SHA instead of the checkout HEAD", () => {
+  // The manual OIDC-recovery path checks out the release TAG, whose HEAD is the metadata-only
+  // release commit — so it passes the source HEAD explicitly. The explicit SHA must win over
+  // `git rev-parse HEAD` and must be validated against the 40-hex contract.
+  const sourceHead = "b".repeat(40);
+  const info = composeBuildInfo("2.0.0", new Date("2026-01-02T03:04:05.000Z"), sourceHead);
+  assertEquals(info.gitSha, sourceHead);
+  assertEquals(info.gitTag, "v2.0.0");
+  assertEquals(buildInfoProblems(info), []);
+});
+
+test("composeBuildInfo rejects a malformed explicit source SHA (fail closed)", () => {
+  assertThrows(() => composeBuildInfo("2.0.0", new Date(), "not-a-sha"), Error, "non-SHA");
+  assertThrows(() => composeBuildInfo("2.0.0", new Date(), "abc123"), Error, "non-SHA");
+});
+
+test("buildInfoProblems rejects malformed payloads", () => {
+  assert(buildInfoProblems(null).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "not-a-sha", gitTag: "v1.0.0", builtAt: "2026-01-02T03:04:05.000Z" }).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "a".repeat(40), gitTag: "", builtAt: "2026-01-02T03:04:05.000Z" }).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "a".repeat(40), gitTag: "v1.0.0", builtAt: "not-a-date" }).length > 0);
+});
+
+test("an npm pack of the package contains build-info.json with a 40-hex SHA", () => {
+  // Write the file exactly as the release pipeline does (prepare step), pack, inspect, then clean
+  // up — build-info.json is a build artifact and MUST NOT be committed (a stale committed copy
+  // would mislabel every later dev checkout), so the test restores the prior state in `finally`.
+  const prior = (() => {
+    try {
+      return readFileSync(BUILD_INFO, "utf8");
+    } catch {
+      return null;
+    }
+  })();
+  const packDir = mkdtempSync(join(tmpdir(), "nwf-pack-"));
+  try {
+    execFileSync("node", ["--experimental-strip-types", "scripts/write-build-info.ts", "0.0.0-packtest"], {
+      cwd: REPO_ROOT,
+      stdio: "pipe",
+    });
+    const out = execFileSync("npm", ["pack", "--pack-destination", packDir], { cwd: REPO_ROOT, encoding: "utf8" });
+    const tarball = join(packDir, out.trim().split("\n").pop() ?? "");
+    const listing = execFileSync("tar", ["-tzf", tarball], { encoding: "utf8" });
+    assert(
+      listing.split("\n").some((f) => f === "package/build-info.json" || f === "build-info.json"),
+      `the tarball must contain build-info.json; got:\n${listing.split("\n").slice(0, 5).join("\n")}…`,
+    );
+    const raw = execFileSync("tar", ["-xzOf", tarball, "package/build-info.json"], { encoding: "utf8" });
+    const packed: unknown = JSON.parse(raw);
+    assertEquals(buildInfoProblems(packed), [], `packed build-info.json must be well-formed: ${raw}`);
+    const gitSha = (packed as { gitSha: string }).gitSha;
+    assert(SHA_RE.test(gitSha), `packed gitSha must be 40-hex, got ${gitSha}`);
+  } finally {
+    if (prior == null) rmSync(BUILD_INFO, { force: true });
+    else writeFileSync(BUILD_INFO, prior);
+    rmSync(packDir, { recursive: true, force: true });
+  }
+});

package/scripts/write-build-info.ts

@@ -0,0 +1,126 @@
+// write-build-info — bake the release's build identity into `build-info.json` at the package root
+// (issue #925).
+//
+// WHY: an npm-installed instance has no `.git` directory and no `NANO_WORKFORCE_GIT_SHA` env var,
+// so `app/version.ts` reported `gitSha: null` on exactly the deploys an operator most needs to
+// identify ("is the fix live on merlin?"). The release pipeline writes this file during
+// semantic-release's `prepare` step — AFTER @semantic-release/npm bumps `package.json` to the
+// release version and BEFORE it packs/publishes the tarball — so every published package carries
+// its own identity and `app/version.ts` can fall back to it (env → .git → build-info.json).
+//
+// WHAT IT RECORDS (and why): `gitSha` is the SOURCE HEAD the release was cut from
+// (`git rev-parse HEAD` in the release checkout), NOT the `chore(release): X.Y.Z` commit
+// @semantic-release/git creates afterwards — that commit does not exist yet at prepare time, so it
+// cannot be recorded here. The release TAG `vX.Y.Z` is later placed on that release commit, whose
+// tree is identical to the source HEAD's tree except for the version-bump metadata (CHANGELOG.md,
+// package.json, package-lock.json). `gitTag` carries the tag name so an operator can resolve the
+// exact release commit (`git rev-list -1 <tag>`) when they need it; `gitSha` answers the
+// day-to-day question "which source code is running".
+//
+// USAGE:
+//   node --experimental-strip-types scripts/write-build-info.ts <version> [--sha <40-hex>]   # release pipeline
+//   node --experimental-strip-types scripts/write-build-info.ts --check                      # test: validate on disk
+//
+// `<version>` alone records the current checkout HEAD — correct at semantic-release `prepare` time.
+// The manual OIDC-recovery path runs from a fresh checkout of the release TAG, whose HEAD is the
+// metadata-only `chore(release)` commit, NOT the source HEAD; it passes `--sha "$(git rev-parse
+// v<version>^")"` so the recorded gitSha still names the source code (see release.yml's recovery
+// instructions).
+//
+// `--check` validates the committed/generated `build-info.json` (present, well-formed, 40-hex
+// gitSha) — used by the pack test to assert the release artifact contract without cutting a
+// release.
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const BUILD_INFO_PATH = join(REPO_ROOT, "build-info.json");
+
+export interface BuildInfo {
+  version: string;
+  gitSha: string;
+  gitTag: string;
+  builtAt: string;
+}
+
+// The ONE payload validator is shared with the reader (app/version.ts) so writer and reader can
+// never disagree on what a valid build-info.json is.
+export { buildInfoProblems } from "../app/version.ts";
+
+import { buildInfoProblems, SHA_RE } from "../app/version.ts";
+
+/**
+ * Compose the build-info payload for a release of `version`. `gitSha` is the SOURCE HEAD the
+ * release was cut from. By default it is read from the current checkout HEAD (`git rev-parse HEAD`)
+ * — correct at semantic-release `prepare` time, when HEAD is still the source commit. Callers that
+ * run LATER (the manual OIDC-recovery path, which checks out the release TAG) must pass `sha`
+ * explicitly as the source HEAD (`git rev-parse v<version>^`): by then HEAD is the metadata-only
+ * `chore(release)` commit, and recording it would mislabel the package with a commit whose only
+ * change is the version bump. An explicit `sha` is validated against the 40-hex contract.
+ */
+export function composeBuildInfo(version: string, now: Date = new Date(), sha?: string): BuildInfo {
+  const gitSha = (
+    sha ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd: REPO_ROOT, encoding: "utf8" })
+  ).trim();
+  if (!SHA_RE.test(gitSha)) throw new Error(`git rev-parse HEAD returned a non-SHA: ${JSON.stringify(gitSha)}`);
+  return {
+    version,
+    gitSha,
+    // The tag semantic-release will place on the release commit for this version.
+    gitTag: `v${version}`,
+    builtAt: now.toISOString(),
+  };
+}
+
+function main(argv: string[]): void {
+  const arg = argv[2];
+  if (arg === "--check") {
+    // Lazy import so the write path never needs fs/readFileSync beyond writeFileSync.
+    import("node:fs").then(({ readFileSync }) => {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(BUILD_INFO_PATH, "utf8"));
+      } catch (err) {
+        // biome-ignore lint/plugin: narrowing a caught unknown to Error for its message
+        console.error(`build-info.json is missing or invalid JSON: ${(err as Error).message}`);
+        process.exit(1);
+      }
+      const problems = buildInfoProblems(parsed);
+      if (problems.length > 0) {
+        console.error(`build-info.json failed validation:\n - ${problems.join("\n - ")}`);
+        process.exit(1);
+      }
+      console.log(`build-info.json OK: ${JSON.stringify(parsed)}`);
+    });
+    return;
+  }
+  const version = arg?.trim();
+  if (!version) {
+    console.error("usage: write-build-info.ts <version> [--sha <40-hex>] | --check");
+    process.exit(1);
+  }
+  // Optional explicit source SHA (see composeBuildInfo). The manual OIDC-recovery path checks out
+  // the release TAG, whose HEAD is the release commit — so it passes the source HEAD
+  // (`git rev-parse v<version>^`) explicitly to keep gitSha pointing at the source code.
+  let sha: string | undefined;
+  const shaIdx = argv.indexOf("--sha");
+  if (shaIdx !== -1) {
+    sha = argv[shaIdx + 1]?.trim();
+    if (!sha || !SHA_RE.test(sha)) {
+      console.error(`--sha must be a 40-hex commit SHA, got ${JSON.stringify(argv[shaIdx + 1])}`);
+      process.exit(1);
+    }
+  }
+  const info = composeBuildInfo(version, new Date(), sha);
+  writeFileSync(BUILD_INFO_PATH, `${JSON.stringify(info, null, 2)}\n`);
+  console.log(`wrote build-info.json: version=${info.version} gitSha=${info.gitSha} gitTag=${info.gitTag}`);
+}
+
+// Run the CLI only when executed directly — importing this module (e.g. from the test) must not
+// parse argv or write files.
+const invokedAs = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (invokedAs === import.meta.url) {
+  main(process.argv);
+}