@nanobpm/nano-workforce 0.205.1 → 0.206.0

package/app/roundProgress.test.ts

@@ -24,8 +24,11 @@ test("routeProgress: an addressed round whose head advanced continues", () => {
 
 test("routeProgress: an explicit non-addressed round always continues (no push is expected)", () => {
   // These are the statuses gw-status routes AWAY from the addressed/default arm — a legit no-push
-  // round. They always continue regardless of the head.
-  for (const status of ["waiting", "converged", "needs_input", "blocked"]) {
+  // round. They always continue regardless of the head. `review-stale` (#923 §4) joins them: the
+  // round re-entered via the converge gate's stale/missing-review path, so no reviewer verdict was
+  // obtained and no push was claimed — it must continue to the review wait, never escalate as
+  // no-progress.
+  for (const status of ["waiting", "converged", "needs_input", "blocked", "review-stale"]) {
     assertEquals(
       routeProgress(status, "sha-1", "sha-1"),
       "continue",
@@ -280,6 +283,64 @@ test("progress-check: a non-addressed round records the baseline and consumes th
   );
 });
 
+test("progress-check: a review-stale re-entry parks with waiting_since at the gate's reviewWaitCutoff, not the park time", async () => {
+  // Issue #923 review ("previously missed"): the converge-gate decides stale/missing from ITS review
+  // read, but the loop parks several tasks later — and the old park stamped `waiting_since` at the
+  // (later) park time. A head-current review landing in that read→park window was then REJECTED by
+  // `pollReviews` (`submitted_at >= waiting_since`), so the loop re-solicited and could time out
+  // despite a valid verdict already sitting unconsumed on the PR. The gate emits `reviewWaitCutoff`
+  // (its read time); the park must stamp `waiting_since` at THAT cutoff so the in-window review
+  // satisfies the wait.
+  const CUTOFF = "2026-11-08T01:00:00.000Z"; // the gate's review-read time (earlier than "now")
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => ({ work: true, consumedKey: "9" }),
+  );
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler(
+    {
+      processInstanceKey: "pik",
+      variables: {
+        prKey: "o/r#1",
+        status: "waiting",
+        repo: "o/r",
+        prNumber: 1,
+        reviewWaitCutoff: CUTOFF,
+      },
+    } as any,
+    app as any,
+  );
+  assertEquals(out, { progressed: true, huskRetries: 0 });
+  assertEquals(updates.length, 1, "one atomic park write");
+  assertEquals(updates[0]!.patch.status, "waiting_review", "the round parks for review");
+  assertEquals(
+    updates[0]!.patch.waiting_since,
+    CUTOFF,
+    "waiting_since is stamped at the gate's review-read cutoff, so a review landing in the read→park window satisfies the wait",
+  );
+});
+
+test("progress-check: a normal round (no reviewWaitCutoff) still stamps waiting_since at the park time", async () => {
+  // The cutoff is only emitted on a review-stale re-entry. A normal round carries no
+  // `reviewWaitCutoff`, so the park falls back to "now" — the pre-fix behaviour every existing test
+  // relies on.
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => ({ work: true, consumedKey: "9" }),
+  );
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  await handler(
+    { processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "waiting", repo: "o/r", prNumber: 1 } } as any,
+    app as any,
+  );
+  assertEquals(updates[0]!.patch.status, "waiting_review");
+  const stamped = updates[0]!.patch.waiting_since;
+  assertEquals(typeof stamped, "string", "a park time is stamped");
+  // Not the (absent) cutoff — a fresh "now" timestamp, i.e. close to the wall clock.
+  const driftMs = Math.abs(Date.now() - Date.parse(stamped as string));
+  assertEquals(driftMs < 60_000, true, "waiting_since falls back to the park time when no cutoff is carried");
+});
+
 test("progress-check: a blank/unknown status is treated as addressed — reads the head and can report no progress", async () => {
   let called = false;
   const handler = await makeUnderTest(async () => {

package/app/roundProgress.ts

@@ -39,6 +39,12 @@ const NON_ADDRESSED_STATUSES: ReadonlySet<string> = new Set([
   "converged",
   "needs_input",
   "blocked",
+  // `review-stale` (issue #923 §4): the round re-entered persist-round via the converge gate's
+  // stale/missing-review path (f_convergeStale) — no head-current reviewer verdict was ever
+  // obtained, so the round claims no push and must always continue to the review wait (the poller
+  // re-solicits a fresh review of the current head). Treating it as `addressed` would fabricate a
+  // no-progress escalation on a round that never claimed progress.
+  "review-stale",
 ]);
 
 /** True when a round's status is `addressed` for no-progress purposes — i.e. NOT one of 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 });
+  }
+});

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.1",
+  "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/resources/processes/convergence-loop.bpmn

@@ -42,6 +42,7 @@
           <nano:extend name="round" type="integer" optional="true" />
           <nano:extend name="huskRetries" type="integer" optional="true" />
           <nano:extend name="roundEntryHead" type="string" optional="true" />
+          <nano:extend name="reviewWaitCutoff" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="PrCaptureHeadIn" name="Capture round-entry head — input">
           <nano:extend name="prKey" type="string" />
@@ -68,6 +69,7 @@
           <nano:extend name="convergeBlockReason" type="string" optional="true" />
           <nano:extend name="convergeAckOnly" type="boolean" optional="true" />
           <nano:extend name="reviewStale" type="boolean" optional="true" />
+          <nano:extend name="reviewWaitCutoff" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="EscalationIn" name="Record escalation — input">
           <nano:extend name="prKey" type="string" />
@@ -307,6 +309,9 @@
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrPersistRoundIn" />
         </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:input source="=if reviewStale = true then &#34;review-stale&#34; else status" target="status" />
+        </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_advSkip</bpmn:incoming>
       <bpmn:incoming>f_advClean</bpmn:incoming>

package/resources/processes/merge-loop.bpmn

@@ -282,7 +282,7 @@
         </zeebe:properties>
         <zeebe:ioMapping>
           <zeebe:input source="=status" target="agentVerdict" />
-          <zeebe:input source="=&#34;This PR cannot be merged and needs a human decision. &#34; + (if mergeState = &#34;conflict&#34; then &#34;The automated rebase agent could not resolve the merge conflicts on this branch. Resolve them manually (or reply with guidance), then reply to retry.&#34; else if mergeStatus = &#34;retry&#34; then &#34;The merge kept losing a race with concurrent updates to the base branch and exhausted its automatic retry budget (&#34; + string(mergeRetryMax) + &#34; retries). This is a repeated transient race, not a conflict, failing check, or permissions block. Reply to retry, or investigate why the base branch keeps moving.&#34; else if mergeState = &#34;ready&#34; then &#34;The merge attempt did not land (merge result: &#34; + mergeStatus + &#34;). Investigate why GitHub refused the merge, then reply to retry.&#34; else if status = &#34;blocked&#34; then &#34;The automated CI-fix agent could not make the required checks green. Fix the failing checks on the branch (or reply with guidance), then reply to retry.&#34; else &#34;The automated CI-fix agent exceeded its time budget (SLA) before the required checks went green. Check its progress or intervene, then reply to retry.&#34;)" target="question" />
+          <zeebe:input source="=&#34;This PR cannot be merged and needs a human decision. &#34; + (if mergeState = &#34;conflict&#34; then &#34;The automated rebase agent could not resolve the merge conflicts on this branch. Resolve them manually (or reply with guidance), then reply to retry.&#34; else if mergeStatus = &#34;retry&#34; then &#34;The merge kept losing a race with concurrent updates to the base branch and exhausted its automatic retry budget (&#34; + string(mergeRetryMax) + &#34; retries). This is a repeated transient race, not a conflict, failing check, or permissions block. Reply to retry, or investigate why the base branch keeps moving.&#34; else if mergeState = &#34;ready&#34; and mergeStatus = &#34;blocked&#34; and question != null then question else if mergeState = &#34;ready&#34; then &#34;The merge attempt did not land (merge result: &#34; + mergeStatus + &#34;). Investigate why GitHub refused the merge, then reply to retry.&#34; else if status = &#34;blocked&#34; then &#34;The automated CI-fix agent could not make the required checks green. Fix the failing checks on the branch (or reply with guidance), then reply to retry.&#34; else &#34;The automated CI-fix agent exceeded its time budget (SLA) before the required checks went green. Check its progress or intervene, then reply to retry.&#34;)" target="question" />
           <zeebe:input source="=&#34;blocked&#34;" target="status" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>