@nanobpm/nano-workforce 0.114.0 → 0.115.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.115.0](https://github.com/nanobpm/nano-workforce/compare/v0.114.1...v0.115.0) (2026-08-20)
+
+
+### Features
+
+* **engine:** startup preflight + canonical engine address resolution ([#391](https://github.com/nanobpm/nano-workforce/issues/391)) ([#404](https://github.com/nanobpm/nano-workforce/issues/404)) ([16fcb71](https://github.com/nanobpm/nano-workforce/commit/16fcb711f190341f03fd84914fa66c1ee704b78c)), closes [Magikcraft/nano-bpm#940](https://github.com/Magikcraft/nano-bpm/issues/940)
+
+## [0.114.1](https://github.com/nanobpm/nano-workforce/compare/v0.114.0...v0.114.1) (2026-08-20)
+
+
+### Bug Fixes
+
+* **convergence-loop:** give the scope-integrity gate a human-override door ([#395](https://github.com/nanobpm/nano-workforce/issues/395)) ([#401](https://github.com/nanobpm/nano-workforce/issues/401)) ([23f8354](https://github.com/nanobpm/nano-workforce/commit/23f83541c57b3474b36a92baa1d88bdd6535df9b))
+
 # [0.114.0](https://github.com/nanobpm/nano-workforce/compare/v0.113.0...v0.114.0) (2026-08-20)
 
 

package/README.md

@@ -252,7 +252,7 @@ active epic already targets the same custom base. See
 |---|---|---|
 | `PR_REVIEW_PORT` | `3000` | app HTTP port |
 | `NANO_APP_DB_URL` | `file:./app.db` | sqlite datasource |
-| `NANOBPMN_BASE_URL` | `http://localhost:8080` | engine base URL (or set `CAMUNDA_REST_ADDRESS` to the `/v2` REST address directly) |
+| `NANOBPMN_BASE_URL` | `http://localhost:8080` | engine base URL (or set `CAMUNDA_REST_ADDRESS` to the `/v2` REST address directly). See [Engine address & the startup preflight](#engine-address--the-startup-preflight) |
 | `GITHUB_TOKEN` | — | token for the review poller / merge (or use the host `gh` CLI) |
 | `NANO_PR_GITHUB_TRANSPORT` | `auto` | how the poller reads GitHub: `gh` (host CLI), `token` (`GITHUB_TOKEN` over HTTP), or `auto` |
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
@@ -267,6 +267,49 @@ active epic already targets the same custom base. See
 | `NANO_WORKFORCE_BASE_URL` | `http://localhost:3000` | externally-reachable base URL for the capability hooks (`/app/api/hooks/*`). Must resolve from **wherever the agent runs** — set it to the app's LAN address (or console-proxy URL) for a remote fleet. See [Fleet networking](#fleet-networking-remote-workers) |
 | `NANO_AGENTIC_SECRET` | — | enables **secure mode** for the agentic visibility channel (`/agentic`): every peer must present the **same** `NANO_AGENTIC_SECRET` value (set the identical env var on the server and every worker box — Tab A → Slot A). Unset = on-by-default **LOCAL mode** — the well-known token is honoured from **any origin** (open on the trusted LAN, matching the engine's posture); exposure is governed by the server bind address, not a shared secret. Also accepts `NANO_PR_WEBHOOK_SECRET` |
 
+### Engine address & the startup preflight
+
+The app talks to one engine over the Camunda 8 REST API. The REST address is
+resolved with a fixed precedence — set **one** of:
+
+1. **`CAMUNDA_REST_ADDRESS`** — used verbatim (it already points at the `/v2`
+   REST address, e.g. `http://engine.example:8080/v2`). **Wins** if set.
+2. **`NANOBPMN_BASE_URL`** — the engine *base*; the app appends `/v2`
+   (e.g. `http://localhost:7000` → `http://localhost:7000/v2`).
+3. Neither set → the base defaults to **`http://localhost:8080`**.
+
+At boot the app **echoes the resolved address and which input it came from**,
+then probes `/v2/topology` and announces **which engine answered** — so a
+misconfigured address is obvious immediately instead of surfacing later as a
+cryptic mid-run engine error:
+
+```
+Engine address: http://localhost:8080/v2 (from default (http://localhost:8080))
+Engine: Nano engine (nanobpmn v0.114.1) — Falcon streaming at /falcon at http://localhost:8080/v2.
+```
+
+The preflight is **informational, never a gate** — Nano Workforce runs against a
+stock **Camunda 8** cluster too, so a non-Nano engine is announced
+(`Engine: Camunda 8 (gateway v8.x) — REST only …`), not rejected. If nothing
+answers, it logs a `warn` (`could not reach … features will fail to start until
+the engine is reachable`) and boot continues. On a **secured** cluster the probe
+sends `CAMUNDA_TOKEN` as a bearer credential; a `401/403` is reported as an auth
+hint (check `CAMUNDA_TOKEN`), not as an unreachable engine.
+
+> **Watch the port when launched from a console.** A console-launched app can
+> default `NANOBPMN_BASE_URL` to `http://localhost:8080`. If **another Camunda 8**
+> is already on `:8080`, the app will talk to *that* engine (it works — C8 is
+> supported), which may not be the engine you intended. Check the startup
+> `Engine:` line; to target a Nano engine on a different port, set
+> `NANOBPMN_BASE_URL` (or `CAMUNDA_REST_ADDRESS`) explicitly.
+>
+> When the app *can't* work against the reached engine you'll see a job/instance
+> decode error at first feature start — `MalformedFrameError` / `MalformedJobError`
+> (Falcon) or the Camunda REST client's own `4xx` (older versions surfaced
+> `engine response missing processInstanceKey/key`). The startup `Engine:` line
+> tells you which engine you actually reached, before any such error.
+
+
 ### Fleet networking (remote workers)
 
 `nano-workforce` can drive a **distributed worker fleet** — `senior:*` agents running on other LAN

package/app/agentic/vocab/demand-report.ts

@@ -20,6 +20,7 @@ import {
 import type { RegisteredWorker } from "@nanobpm/agentic/vocab";
 import type { Logger } from "@nanobpm/urban";
 import type { RegistryReport as WireRegistryReport } from "../../../nano-generated/api-io.d.ts";
+import { resolveEngineAddress } from "../../enginePreflight.ts";
 import { envVar } from "../../version.ts";
 import { currentPresenceRegistry } from "../families/presence.family.ts";
 import { CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
@@ -40,17 +41,14 @@ export interface RegistryReport extends DemandSupplyReport {
 }
 
 /**
- * Derive the engine's C8 v2 REST base the demand reader targets — the same precedence/derivation
- * `main.ts` uses: an explicit `CAMUNDA_REST_ADDRESS` wins, else it is derived from `NANOBPMN_BASE_URL`
- * (+ `/v2`), defaulting to `http://localhost:8080/v2`. Read through the declared env schema (ADR 0004).
- * (This reader additionally strips trailing slashes off an explicit `CAMUNDA_REST_ADDRESS`, which
- * `main.ts` does not, so the derived base is well-formed regardless of a trailing `/`.)
+ * Derive the engine's C8 v2 REST base the demand reader targets. Delegates to
+ * the canonical {@link resolveEngineAddress} (the single source of truth shared
+ * with `main.ts`) so the precedence — explicit `CAMUNDA_REST_ADDRESS` wins, else
+ * `NANOBPMN_BASE_URL` (+ `/v2`), defaulting to `http://localhost:8080/v2` — lives
+ * in one place and cannot drift between call sites.
  */
 export function engineRestAddress(): string {
-  const explicit = envVar("CAMUNDA_REST_ADDRESS")?.replace(/\/+$/, "");
-  if (explicit) return explicit;
-  const base = (envVar("NANOBPMN_BASE_URL") ?? "http://localhost:8080").replace(/\/+$/, "");
-  return `${base}/v2`;
+  return resolveEngineAddress().restAddress;
 }
 
 /** The live supply rows (`{ instance, capability }`) from the H1 presence registry, or none when unmounted. */

package/app/convergeGate.test.ts

@@ -218,11 +218,14 @@ async function makeUnderTest(deps: {
   readThreads: (repo: string, n: number) => Promise<ReviewThread[] | null>;
   readReviewBody: (repo: string, n: number) => Promise<string | null>;
   readPrBody?: (repo: string, n: number) => Promise<string | null>;
+  readHeadSha?: (repo: string, n: number) => Promise<string | null>;
 }) {
   const { makeHandler } = await import("../workers/converge-gate/worker.ts");
   // Default the scope-guard PR-body read to a verified-empty description so the comment-gate tests
-  // below exercise only the review-comment dimension; scope-guard tests pass an explicit body.
-  return makeHandler({ readPrBody: async () => "", ...deps });
+  // below exercise only the review-comment dimension; scope-guard tests pass an explicit body. The
+  // HEAD read defaults to null (unreadable) so a scope block stays blocked unless a test opts into
+  // the #395 override door with an explicit HEAD — see workers/converge-gate/worker.test.ts.
+  return makeHandler({ readPrBody: async () => "", readHeadSha: async () => null, ...deps });
 }
 
 test("converge-gate: a clean PR is allowed to converge", async () => {

package/app/enginePreflight.test.ts

@@ -0,0 +1,122 @@
+// Tests for engine address resolution + the startup preflight (nano-workforce#391).
+//
+// The resolver and the identity description are pure (an injectable env reader /
+// a plain topology body), and the preflight takes an injectable `fetch`, so none
+// of this needs a live engine or `process.env` mutation.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  announceEngine,
+  describeEngine,
+  type EngineAddress,
+  resolveEngineAddress,
+  type TopologyProbe,
+} from "./enginePreflight.ts";
+
+const reader = (vars: Record<string, string>) => (name: string): string | null => vars[name] ?? null;
+
+test("resolveEngineAddress honours an explicit CAMUNDA_REST_ADDRESS and strips trailing slashes", () => {
+  const addr = resolveEngineAddress(reader({ CAMUNDA_REST_ADDRESS: "http://engine.example:8080/v2///" }));
+  assertEquals(addr, { restAddress: "http://engine.example:8080/v2", source: "CAMUNDA_REST_ADDRESS" });
+});
+
+test("resolveEngineAddress derives /v2 from NANOBPMN_BASE_URL when no explicit address", () => {
+  const addr = resolveEngineAddress(reader({ NANOBPMN_BASE_URL: "http://engine.example:7000//" }));
+  assertEquals(addr, { restAddress: "http://engine.example:7000/v2", source: "NANOBPMN_BASE_URL" });
+});
+
+test("resolveEngineAddress defaults to localhost:8080 and labels the source as the default", () => {
+  const addr = resolveEngineAddress(reader({}));
+  assertEquals(addr, { restAddress: "http://localhost:8080/v2", source: "default (http://localhost:8080)" });
+});
+
+test("describeEngine reports a Nano engine from the `nano` marker", () => {
+  const line = describeEngine({ nano: { engine: "nanobpmn", version: "0.114.1", falconPath: "/falcon" } });
+  assert(line.includes("Nano engine (nanobpmn v0.114.1)"), "names the nano engine + version");
+  assert(line.includes("/falcon"), "mentions the Falcon path");
+});
+
+test("describeEngine reports Camunda 8 (never rejects) when the `nano` marker is absent", () => {
+  const line = describeEngine({ gatewayVersion: "8.6.0" });
+  assert(line.startsWith("Camunda 8"), "identifies Camunda 8");
+  assert(line.includes("8.6.0"), "surfaces the gateway version");
+  assert(line.includes("REST only"), "notes Falcon is unavailable");
+});
+
+test("describeEngine tolerates an empty / missing body", () => {
+  assert(describeEngine(null).startsWith("Camunda 8"), "null body degrades to Camunda 8");
+  assert(describeEngine({}).startsWith("Camunda 8"), "empty body degrades to Camunda 8");
+});
+
+// --- announceEngine (injected fetch; never throws) ---
+
+const ADDR: EngineAddress = { restAddress: "http://localhost:8080/v2", source: "default (http://localhost:8080)" };
+
+function capture() {
+  const info: string[] = [];
+  const warn: string[] = [];
+  return { log: { info: (m: string) => info.push(m), warn: (m: string) => warn.push(m) }, info, warn };
+}
+
+const okResponse = (body: TopologyProbe) =>
+  ({ ok: true, status: 200, json: () => Promise.resolve(body) }) as unknown as Response;
+
+test("announceEngine logs the resolved address + a Nano identity line", async () => {
+  const { log, info, warn } = capture();
+  let probed = "";
+  await announceEngine(ADDR, log, {
+    fetchImpl: ((url: string) => {
+      probed = url;
+      return Promise.resolve(okResponse({ nano: { engine: "nanobpmn", version: "1.2.3", falconPath: "/falcon" } }));
+    }) as unknown as typeof fetch,
+  });
+  assertEquals(probed, "http://localhost:8080/v2/topology");
+  assert(info.some((l) => l.includes("Engine address: http://localhost:8080/v2 (from default")), "echoes address+source");
+  assert(info.some((l) => l.includes("Nano engine (nanobpmn v1.2.3)")), "announces the Nano engine");
+  assertEquals(warn, []);
+});
+
+test("announceEngine announces Camunda 8 without rejecting", async () => {
+  const { log, info, warn } = capture();
+  await announceEngine(ADDR, log, {
+    fetchImpl: (() => Promise.resolve(okResponse({ gatewayVersion: "8.6.0" }))) as unknown as typeof fetch,
+  });
+  assert(info.some((l) => l.includes("Camunda 8")), "announces Camunda 8");
+  assertEquals(warn, []);
+});
+
+test("announceEngine sends CAMUNDA_TOKEN as a bearer credential on the probe", async () => {
+  const { log } = capture();
+  let sentAuth: string | undefined;
+  await announceEngine(ADDR, log, {
+    token: "secret-token",
+    fetchImpl: ((_url: string, init: { headers: Record<string, string> }) => {
+      sentAuth = init.headers.authorization;
+      return Promise.resolve(okResponse({ nano: { engine: "nanobpmn" } }));
+    }) as unknown as typeof fetch,
+  });
+  assertEquals(sentAuth, "Bearer secret-token");
+});
+
+test("announceEngine treats 401/403 as an auth hint, not an unreachable warning", async () => {
+  const { log, warn } = capture();
+  const res = { ok: false, status: 401, json: () => Promise.reject(new Error("unused")) } as unknown as Response;
+  await announceEngine(ADDR, log, { fetchImpl: (() => Promise.resolve(res)) as unknown as typeof fetch });
+  assert(warn.some((l) => l.includes("HTTP 401") && l.includes("CAMUNDA_TOKEN")), "points at the token, not unreachability");
+  assert(!warn.some((l) => l.includes("could not reach")), "does not claim the engine is unreachable");
+});
+
+test("announceEngine warns (does not throw) on a non-200 response", async () => {
+  const { log, warn } = capture();
+  const res = { ok: false, status: 503, json: () => Promise.reject(new Error("unused")) } as unknown as Response;
+  await announceEngine(ADDR, log, { fetchImpl: (() => Promise.resolve(res)) as unknown as typeof fetch });
+  assert(warn.some((l) => l.includes("HTTP 503")), "warns with the status code");
+});
+
+test("announceEngine warns (does not throw) when the engine is unreachable", async () => {
+  const { log, warn } = capture();
+  await announceEngine(ADDR, log, {
+    fetchImpl: (() => Promise.reject(new Error("ECONNREFUSED"))) as unknown as typeof fetch,
+  });
+  assert(warn.some((l) => l.includes("could not reach") && l.includes("ECONNREFUSED")), "warns with the reason");
+});

package/app/enginePreflight.ts

@@ -0,0 +1,134 @@
+// Engine address resolution + a lightweight, non-rejecting startup preflight
+// (nano-workforce#391).
+//
+// Two jobs, one source of truth:
+//   1. `resolveEngineAddress` is the CANONICAL resolver for the engine REST
+//      address. Both the engine client (`main.ts`) and the demand reader
+//      (`app/agentic/vocab/demand-report.ts`) derive from it, so the precedence
+//      lives in exactly one place instead of drifting across call sites.
+//   2. `announceEngine` probes `/v2/topology` at boot and reports which engine
+//      answered. It is DELIBERATELY informational: Nano Workforce is a
+//      first-class Camunda 8 client, so a non-Nano engine is announced, never
+//      rejected. It never throws — a boot preflight must not gate startup.
+//
+// Why: without this, pointing the app at the wrong address (classically another
+// service already on :8080) surfaces only later as a cryptic mid-run engine
+// error. Echoing the resolved address + which engine answered makes the
+// misconfiguration obvious at boot.
+
+import { envVar } from "./version.ts";
+
+/** The resolved engine REST address plus a human label for where it came from. */
+export interface EngineAddress {
+  /** The `/v2` REST base the engine client and demand reader talk to. */
+  restAddress: string;
+  /** Which input produced `restAddress`, for a legible startup line. */
+  source: string;
+}
+
+/**
+ * Canonical engine REST address resolution — the single source of truth.
+ *
+ * Precedence: an explicit `CAMUNDA_REST_ADDRESS` (already the `/v2` REST
+ * address) wins; otherwise the address is derived from `NANOBPMN_BASE_URL`
+ * (+ `/v2`), defaulting the base to `http://localhost:8080`. Trailing slashes
+ * are stripped from both inputs.
+ *
+ * `read` is injectable so the resolution is testable without mutating
+ * `process.env`; it defaults to the app's `envVar` (ADR 0004) accessor.
+ */
+export function resolveEngineAddress(
+  read: (name: string) => string | null = envVar,
+): EngineAddress {
+  const explicit = read("CAMUNDA_REST_ADDRESS")?.replace(/\/+$/, "");
+  if (explicit) return { restAddress: explicit, source: "CAMUNDA_REST_ADDRESS" };
+  const base = read("NANOBPMN_BASE_URL");
+  const normalized = (base ?? "http://localhost:8080").replace(/\/+$/, "");
+  return {
+    restAddress: `${normalized}/v2`,
+    source: base ? "NANOBPMN_BASE_URL" : "default (http://localhost:8080)",
+  };
+}
+
+/**
+ * The subset of a `/v2/topology` body we read. A nanobpmn gateway advertises a
+ * `nano` object (its own extension) so a single call distinguishes it from a
+ * stock Camunda 8 gateway, which returns the same shape without it.
+ */
+export interface TopologyProbe {
+  nano?: { engine?: string; version?: string; falconPath?: string } | null;
+  gatewayVersion?: string;
+}
+
+/**
+ * A human-readable identity line for whatever answered `/v2/topology`. Never
+ * rejects: a Camunda 8 gateway (no `nano` marker) is a supported target, so it
+ * is described, not refused.
+ */
+export function describeEngine(body: TopologyProbe | null | undefined): string {
+  const nano = body?.nano;
+  if (nano?.engine) {
+    const version = nano.version ? ` v${nano.version}` : "";
+    const falcon = nano.falconPath ?? "/falcon";
+    return `Nano engine (${nano.engine}${version}) — Falcon streaming at ${falcon}`;
+  }
+  const gateway = body?.gatewayVersion ? ` (gateway v${body.gatewayVersion})` : "";
+  return `Camunda 8${gateway} — REST only (Nano Falcon streaming unavailable)`;
+}
+
+/** The logging surface `announceEngine` needs (structurally a `Logger`). */
+export interface PreflightLog {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+
+/**
+ * Log the resolved engine address (and its source), then probe `/v2/topology`
+ * and announce which engine answered. Informational only — it swallows every
+ * failure into a `warn` and never throws, so a slow or absent engine cannot
+ * block boot. A missing engine is a `warn` (features will fail to start until
+ * it is reachable), not a fatal error.
+ *
+ * `opts.token` (the same `CAMUNDA_TOKEN` the engine client uses) is sent as a
+ * bearer credential so a secured cluster does not answer the probe with a
+ * misleading 401/403 while the real client is correctly configured.
+ */
+export async function announceEngine(
+  addr: EngineAddress,
+  log: PreflightLog,
+  opts: { token?: string; fetchImpl?: typeof fetch } = {},
+): Promise<void> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  log.info(`Engine address: ${addr.restAddress} (from ${addr.source})`);
+  const url = `${addr.restAddress.replace(/\/+$/, "")}/topology`;
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (opts.token) headers.authorization = `Bearer ${opts.token}`;
+  try {
+    const res = await fetchImpl(url, { headers, signal: AbortSignal.timeout(3000) });
+    if (!res.ok) {
+      if (res.status === 401 || res.status === 403) {
+        // The engine is reachable but rejected the probe's credentials — the
+        // real client may still work (it authenticates independently), so this
+        // is an auth hint, not an "unreachable" warning.
+        log.warn(
+          `Engine preflight: ${url} returned HTTP ${res.status} (authentication). ` +
+            `If the engine requires a token, set CAMUNDA_TOKEN — the engine client uses it independently.`,
+        );
+        return;
+      }
+      log.warn(
+        `Engine preflight: ${url} returned HTTP ${res.status}. ` +
+          `Check CAMUNDA_REST_ADDRESS / NANOBPMN_BASE_URL — features will fail to start until the engine is reachable.`,
+      );
+      return;
+    }
+    const body: TopologyProbe = await res.json();
+    log.info(`Engine: ${describeEngine(body)} at ${addr.restAddress}.`);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    log.warn(
+      `Engine preflight: could not reach ${url} (${reason}). ` +
+        `Check CAMUNDA_REST_ADDRESS / NANOBPMN_BASE_URL — features will fail to start until the engine is reachable.`,
+    );
+  }
+}

package/app/persist-escalation.test.ts

@@ -212,3 +212,36 @@ test("a control-flow arm with a blank question opens nothing so gw-escalated re-
   assertEquals(inserts.escalations.length, 0, "no dead escalation is fabricated");
   assertEquals(updates.pull_requests?.length ?? 0, 0, "the PR is never flipped to escalated");
 });
+
+// The scope-integrity arm (persist-escalation-blockedcomments) binds the escalation to the reviewed
+// commit (issue #395): it stamps `head_sha` and marks `scope_block` so the converge-gate can honour
+// a same-HEAD human answer as an override instead of re-deriving the block and re-escalating forever.
+test("persist-escalation binds a scope-integrity escalation to the reviewed HEAD (head_sha + scope_block)", async () => {
+  const { app, inserts } = fakeApp();
+  const job = {
+    variables: {
+      prKey: "o/r#5",
+      round: 2,
+      status: "blocked",
+      question: "Scope integrity blocked: ...",
+      recordRound: false,
+      headSha: "HEAD1",
+      scopeBlock: true,
+    },
+  };
+  await handler(job as any, app as any);
+  assertEquals(inserts.escalations.length, 1);
+  assertEquals((inserts.escalations[0] as any).head_sha, "HEAD1", "the escalation carries the reviewed commit");
+  assertEquals((inserts.escalations[0] as any).scope_block, 1, "flagged as a scope-integrity block");
+});
+
+// Every other escalation arm (agent verdict, no-progress, max-rounds, stalled) omits the scope
+// binding: head_sha stays absent and scope_block defaults to 0, so the override door opens ONLY for
+// the block a human can actually answer.
+test("persist-escalation: a non-scope escalation records no HEAD binding and scope_block 0", async () => {
+  const { app, inserts } = fakeApp();
+  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "max rounds" } };
+  await handler(job as any, app as any);
+  assertEquals((inserts.escalations[0] as any).head_sha, undefined, "no reviewed HEAD to bind");
+  assertEquals((inserts.escalations[0] as any).scope_block, 0, "not a scope-integrity block");
+});

package/app/scopeGuard.test.ts

@@ -14,6 +14,7 @@ import {
   findClosingKeywordRefs,
   hasDeferralMarker,
   hasFollowupIssueRef,
+  isScopeOverridden,
 } from "./scopeGuard.ts";
 
 // ── The canonical router ────────────────────────────────────────────────────
@@ -145,3 +146,40 @@ test("hasFollowupIssueRef: only an explicit tracking marker + issue ref counts",
     "Follow-up marker with a full issue URL",
   );
 });
+
+// ── The human-override door (#395) ──────────────────────────────────────────
+// The scope-integrity gate re-derives `scopeBlocked` from the PR body every round, so answering
+// its escalation used to re-block identically (an infinite loop). An answer bound to the SAME
+// reviewed HEAD is now honoured as an explicit override; a different HEAD (a new push) is not.
+
+test("isScopeOverridden: an answer bound to the same HEAD overrides the block", () => {
+  assert(
+    isScopeOverridden("abc123", { escalationId: 7, headSha: "abc123", answer: "Full delivery — keep Closes." }),
+    "same-HEAD answered escalation is an override",
+  );
+});
+
+test("isScopeOverridden: an answer for a DIFFERENT HEAD does not override (a new push re-opens)", () => {
+  assert(
+    !isScopeOverridden("newHEAD", { escalationId: 7, headSha: "oldHEAD", answer: "Full delivery." }),
+    "an override never carries across a new push",
+  );
+});
+
+test("isScopeOverridden: no recorded answer is never an override", () => {
+  assertEquals(isScopeOverridden("abc123", null), false);
+  assertEquals(isScopeOverridden("abc123", undefined), false);
+});
+
+test("isScopeOverridden: a missing/blank HEAD on either side fails closed (no override)", () => {
+  assertEquals(isScopeOverridden(null, { headSha: "abc123", answer: "x" }), false, "unreadable current HEAD");
+  assertEquals(isScopeOverridden("", { headSha: "abc123", answer: "x" }), false, "blank current HEAD");
+  assertEquals(isScopeOverridden("abc123", { headSha: null, answer: "x" }), false, "unrecorded escalation HEAD");
+  assertEquals(isScopeOverridden("abc123", { headSha: "  ", answer: "x" }), false, "blank escalation HEAD");
+});
+
+test("isScopeOverridden: the answer text is not parsed for intent — presence at the HEAD is the signal", () => {
+  // On an unchanged HEAD, the operator completing the escalation IS the explicit approval: had they
+  // wanted a real split, the servicing agent would have pushed a fix, moving the HEAD.
+  assert(isScopeOverridden("abc123", { headSha: "abc123", answer: null }), "a null answer at the HEAD still overrides");
+});

package/app/scopeGuard.ts

@@ -129,3 +129,37 @@ export function evaluateScopeGuard(input: ScopeGuardInput): ScopeGuardResult {
     scopeBlockReason: `Scope integrity blocked: ${reasons.join("; ")}.`,
   };
 }
+
+// A recorded human answer to a scope-integrity escalation, bound to the PR HEAD it was raised
+// against (issue #395). This is the override door the deterministic scope gate lacked: without it,
+// the gate re-derives `scopeBlocked` from the PR body every round and re-escalates the identical
+// question, so a legitimate human override ("this fully delivers the issue — keep the closing
+// keyword") is unresolvable through the escalation the loop itself opens (infinite loop).
+export interface ScopeEscalationAnswer {
+  /** The escalation row id, for the audit trail. */
+  escalationId?: number;
+  /** The PR HEAD sha this scope escalation was raised against (`escalations.head_sha`). */
+  headSha: string | null | undefined;
+  /** The operator's recorded answer/rationale (`escalations.answer`), surfaced in the audit. */
+  answer: string | null | undefined;
+}
+
+/** Decide whether a recorded human answer overrides the scope-integrity block for the commit
+ * currently under review. The override is honoured ONLY when the human answered a scope-integrity
+ * escalation that was raised against the SAME HEAD sha now being checked — binding the override to
+ * the reviewed commit so a later push (a different HEAD) re-opens the gate instead of silently
+ * carrying the override forward. Pure and total: a missing/blank current HEAD or a missing/blank
+ * recorded HEAD never matches, so an unverifiable HEAD fails closed (no override) rather than
+ * waving the gate through. The answer TEXT is not parsed for intent: on an unchanged HEAD the human
+ * completing the escalation IS the explicit approval (had they wanted a real fix, the servicing
+ * agent would have pushed a new commit, moving the HEAD and side-stepping this override). */
+export function isScopeOverridden(
+  currentHeadSha: string | null | undefined,
+  answered: ScopeEscalationAnswer | null | undefined,
+): boolean {
+  if (!answered) return false;
+  const current = typeof currentHeadSha === "string" ? currentHeadSha.trim() : "";
+  const recorded = typeof answered.headSha === "string" ? answered.headSha.trim() : "";
+  if (current === "" || recorded === "") return false;
+  return current === recorded;
+}

package/db/migrations/056_escalation_head_override.sql

@@ -0,0 +1,23 @@
+-- Bind a scope-integrity escalation to the reviewed commit so a human answer can override it
+-- (issue #395). The review-convergence scope-integrity gate (`workers/converge-gate`) raises a
+-- human question ("this partial delivery closes a broader-scoped parent") but then re-derives the
+-- block from scratch off the PR body every round, ignoring the recorded `answer` — so answering
+-- the escalation re-enters the loop, the gate re-blocks identically, and the operator is trapped in
+-- an infinite escalation with no human-override door. The only escape was mangling the PR body into
+-- a non-closing ref, i.e. changing the PR to what the machine wants rather than answering it.
+--
+-- The fix gives the gate a real override door: an escalation now records the PR HEAD sha it was
+-- raised against (`head_sha`) and whether it was a scope-integrity block (`scope_block`). When the
+-- gate would re-block on scope, it consults the answered escalation for THIS PR at the SAME HEAD:
+-- a human answer bound to the reviewed commit is honoured as an explicit override (audited), and
+-- the gate is satisfied. Binding to the HEAD sha is deliberate — a later push (a new HEAD)
+-- legitimately re-opens the gate rather than silently carrying the override forward, and if the
+-- human instead asked for a real split the agent pushes a fix (new HEAD) so the stale override
+-- never applies. This categorically kills the infinite-escalation loop on an unchanged HEAD.
+--
+-- Both columns are nullable/defaulted (expand phase, additive). Only the scope-integrity arm
+-- (`persist-escalation-blockedcomments`) populates them; every other escalation arm leaves them
+-- NULL/0 and is unaffected. Numbered after the current highest prefix (055); the runner wraps each
+-- file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE escalations ADD COLUMN head_sha TEXT;
+ALTER TABLE escalations ADD COLUMN scope_block INTEGER NOT NULL DEFAULT 0;

package/main.ts

@@ -20,6 +20,7 @@
 import { Server } from "node:http";
 import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urban";
 import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
+import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
 
@@ -29,12 +30,18 @@ const GITHUB_TOKEN = process.env.GITHUB_TOKEN ?? "";
 
 const host = selectHost();
 
-// One engine client, shared by the runtime (surfaces/actions/workers) and the poller. Honour
-// the app's documented NANOBPMN_BASE_URL as well as the runtime's CAMUNDA_REST_ADDRESS.
-const restAddress = process.env.CAMUNDA_REST_ADDRESS ??
-  `${(process.env.NANOBPMN_BASE_URL ?? "http://localhost:8080").replace(/\/+$/, "")}/v2`;
+// One engine client, shared by the runtime (surfaces/actions/workers) and the poller. The address
+// resolution (CAMUNDA_REST_ADDRESS wins, else NANOBPMN_BASE_URL + /v2, else localhost:8080) is the
+// canonical `resolveEngineAddress`, shared with the demand reader. A non-rejecting startup preflight
+// then echoes the resolved address and announces which engine answered (nano-workforce#391) so a
+// misconfigured address is obvious at boot rather than as a cryptic mid-run engine error.
+const engineAddress = resolveEngineAddress();
+await announceEngine(engineAddress, {
+  info: (msg) => host.log("info", msg),
+  warn: (msg) => host.log("warn", msg),
+}, { token: process.env.CAMUNDA_TOKEN });
 const engine = await createNanoSdkEngineClient({
-  restAddress,
+  restAddress: engineAddress.restAddress,
   token: process.env.CAMUNDA_TOKEN,
   transport: process.env.CAMUNDA_TRANSPORT ?? "auto",
   log: host.log,
@@ -96,7 +103,7 @@ let shuttingDown = false;
 let pollTimer: ReturnType<typeof setTimeout> | null = null;
 async function pollLoop(): Promise<void> {
   try {
-    if (app.data) await pollOnce(app.data, engine, GITHUB_TOKEN, { restAddress, token: process.env.CAMUNDA_TOKEN });
+    if (app.data) await pollOnce(app.data, engine, GITHUB_TOKEN, { restAddress: engineAddress.restAddress, token: process.env.CAMUNDA_TOKEN });
   } catch (err) {
     console.error("poll error:", err);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.114.0",
+  "version": "0.115.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",

package/resources/processes/convergence-loop.bpmn

@@ -50,6 +50,8 @@
         <nano:shape id="PrConvergeGateOut" name="Converge gate — result">
           <nano:extend name="convergeBlocked" type="boolean" />
           <nano:extend name="convergeBlockReason" type="string" optional="true" />
+          <nano:extend name="headSha" type="string" optional="true" />
+          <nano:extend name="scopeBlocked" type="boolean" optional="true" />
         </nano:shape>
         <nano:shape id="EscalationIn" name="Record escalation — input">
           <nano:extend name="prKey" type="string" />
@@ -62,6 +64,8 @@
           <nano:extend name="prNumber" type="integer" optional="true" />
           <nano:extend name="prUrl" type="string" optional="true" />
           <nano:extend name="abandonUrl" type="string" optional="true" />
+          <nano:extend name="headSha" type="string" optional="true" />
+          <nano:extend name="scopeBlock" type="boolean" optional="true" />
         </nano:shape>
         <nano:shape id="EscalationOut" name="Record escalation — result">
           <nano:extend name="escalationId" type="integer" optional="true" />
@@ -299,6 +303,8 @@
           <zeebe:input source="=&#34;blocked&#34;" target="status" />
           <zeebe:input source="=false" target="recordRound" />
           <zeebe:input source="=convergeBlockReason" target="question" />
+          <zeebe:input source="=headSha" target="headSha" />
+          <zeebe:input source="=scopeBlocked" target="scopeBlock" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_convergeBlocked</bpmn:incoming>

package/workers/converge-gate/worker.test.ts

@@ -0,0 +1,116 @@
+// pr.converge-gate — the human-override door for the scope-integrity block (issue #395).
+//
+// The scope-integrity gate re-derives `scopeBlocked` from the PR body every converged round. Before
+// this fix, answering its escalation re-entered the loop, the gate re-blocked identically, and the
+// operator was trapped in an infinite escalation (a fresh escalationId each cycle) — the only escape
+// was mangling the PR body into a non-closing ref. These tests pin the override door: an escalation
+// answer bound to the SAME reviewed HEAD satisfies the gate (audited), a different HEAD (a new push)
+// re-opens it, and an unreadable HEAD keeps the block (fail closed).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { makeHandler } from "./worker.ts";
+
+// A PR body that trips the scope-integrity guard: it defers scope (`## Scope`) yet closes a
+// broader-scoped parent (`Closes #631`) and links no filed follow-up.
+const SCOPE_BLOCKING_BODY =
+  "Delivers the first half.\n\n## Scope\nThe embedded tools remain the deferred refinement.\n\nCloses #631";
+
+// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory app double, mirrors persist-escalation.test
+function fakeApp(escalations: Record<string, unknown>[]): any {
+  const stores: Record<string, Record<string, unknown>[]> = { escalations };
+  return {
+    stores,
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+        };
+      },
+    },
+    log: noopLog(),
+  };
+}
+
+function deps(overrides: {
+  headSha?: string | null;
+  prBody?: string;
+  headThrows?: boolean;
+}) {
+  const headSha = "headSha" in overrides ? (overrides.headSha ?? null) : "HEAD1";
+  return {
+    readThreads: () => Promise.resolve([]),
+    readReviewBody: () => Promise.resolve(""),
+    readPrBody: () => Promise.resolve(overrides.prBody ?? SCOPE_BLOCKING_BODY),
+    readHeadSha: () => (overrides.headThrows ? Promise.reject(new Error("gh down")) : Promise.resolve(headSha)),
+  };
+}
+
+const job = { variables: { prKey: "o/r#5", repo: "o/r", prNumber: 5 } } as never;
+
+test("scope blocks with no answered escalation → blocked, and surfaces the reviewed HEAD to bind the escalation", async () => {
+  const app = fakeApp([]);
+  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
+  assertEquals(out.convergeBlocked, true);
+  assertEquals(out.scopeBlocked, true);
+  assertEquals(out.headSha, "HEAD1", "the reviewed HEAD is returned so persist-escalation can bind it");
+});
+
+test("scope blocks but a human answered the escalation for the SAME HEAD → override honoured (loop broken)", async () => {
+  const app = fakeApp([
+    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "HEAD1", answer: "Full delivery — keep Closes." },
+  ]);
+  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
+  assertEquals(out.convergeBlocked, false, "the same-HEAD human answer satisfies the scope gate");
+  assertEquals(out.convergeBlockReason, "");
+  // A cleared scope block routes to finalize, so the block-only binding fields are not emitted.
+  assertEquals(out.scopeBlocked, undefined);
+});
+
+test("scope blocks and the answer was for a DIFFERENT HEAD (a new push) → still blocked", async () => {
+  const app = fakeApp([
+    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "OLDHEAD", answer: "Full delivery." },
+  ]);
+  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
+  assertEquals(out.convergeBlocked, true, "a stale override never carries across a new push");
+  assertEquals(out.scopeBlocked, true);
+});
+
+test("scope blocks and an answered NON-scope escalation sits at the same HEAD → not an override", async () => {
+  const app = fakeApp([
+    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 0, head_sha: "HEAD1", answer: "unrelated" },
+  ]);
+  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
+  assertEquals(out.convergeBlocked, true, "only a scope-integrity escalation opens the scope override door");
+});
+
+test("scope blocks but the reviewed HEAD is unreadable → keep the block (fail closed)", async () => {
+  const app = fakeApp([
+    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "HEAD1", answer: "override" },
+  ]);
+  const nullHead = (await makeHandler(deps({ headSha: null }))(job, app)) as Record<string, unknown>;
+  assertEquals(nullHead.convergeBlocked, true, "cannot verify an override against an unknown HEAD");
+  const throwHead = (await makeHandler(deps({ headThrows: true }))(job, app)) as Record<string, unknown>;
+  assertEquals(throwHead.convergeBlocked, true, "a HEAD read error keeps the block");
+});
+
+test("scope passes → not blocked, and no override lookup is needed", async () => {
+  const app = fakeApp([]);
+  const out = (await makeHandler(deps({ prBody: "Implements the whole thing.\n\nCloses #631" }))(job, app)) as Record<
+    string,
+    unknown
+  >;
+  assertEquals(out.convergeBlocked, false);
+  assertEquals(out.scopeBlocked, undefined);
+});
+
+test("newest answered scope escalation wins when a re-escalation was answered again at the same HEAD", async () => {
+  const app = fakeApp([
+    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "HEAD1", answer: "first" },
+    { id: 9, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "HEAD1", answer: "latest" },
+  ]);
+  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
+  assertEquals(out.convergeBlocked, false, "a re-answered override at the unchanged HEAD is honoured");
+});

package/workers/converge-gate/worker.ts

@@ -19,6 +19,15 @@
 // This is the enforcement backstop for the Magikcraft/nano-bpm#631 → PR #863 (`Closes #631`, `##
 // Scope` deferral, no follow-up → re-filed by hand as #872) failure class. See app/scopeGuard.ts.
 //
+// The scope-integrity block also carries a HUMAN-OVERRIDE door (#395): before it re-blocks, it
+// reads the commit now under review and consults the `escalations` answer bound to that SAME HEAD.
+// An operator who answered the scope question for this exact commit ("this fully delivers the issue
+// — keep the closing keyword") has explicitly overridden it, so the gate honours that answer
+// (audited) instead of re-deriving `scopeBlocked` from the PR body and re-escalating the identical
+// question forever. Binding to the HEAD sha keeps the override from carrying across a new push, and
+// (via `PrConvergeGateOut.headSha`/`scopeBlocked`) lets `persist-escalation-blockedcomments` stamp
+// the escalation with the reviewed commit so the door can open on the next round.
+//
 // It FAILS CLOSED: if the live GitHub state cannot be read, it blocks (escalates) rather than
 // letting an unverifiable "converged" through — the opposite of the no-progress guard, because a
 // merge-gating check must escalate-on-uncertainty so #770 cannot recur.
@@ -26,13 +35,14 @@ import type { AppJobHandler } from "@nanobpm/urban";
 import { type ConvergeGateResult, evaluateConvergeGate } from "../../app/convergeGate.ts";
 import {
   fetchLatestCopilotReviewBody,
+  fetchPrHead,
   fetchPrMeta,
   fetchReviewThreads,
   parseAckedAdvisories,
   parseSuppressedAdvisories,
   type ReviewThread,
 } from "../../app/github.ts";
-import { evaluateScopeGuard } from "../../app/scopeGuard.ts";
+import { evaluateScopeGuard, isScopeOverridden, type ScopeEscalationAnswer } from "../../app/scopeGuard.ts";
 import { parsePr } from "../../app/service.ts";
 import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -50,6 +60,9 @@ export type ReviewBodyReader = (repo: string, prNumber: number) => Promise<strin
 // Reads the PR's own description body. `null` = no usable transport (unverifiable → fail closed);
 // `""` = transport usable but the PR has an empty description (verified: nothing to scope-check).
 export type PrBodyReader = (repo: string, prNumber: number) => Promise<string | null>;
+// Reads the PR's current HEAD sha (the commit under review). `null` = unreadable/no transport — the
+// scope override cannot be verified or bound to a commit, so the gate keeps blocking (fail closed).
+export type HeadShaReader = (repo: string, prNumber: number) => Promise<string | null>;
 
 const defaultReadThreads: ThreadsReader = (repo, prNumber) =>
   fetchReviewThreads(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
@@ -59,6 +72,10 @@ const defaultReadPrBody: PrBodyReader = async (repo, prNumber) => {
   const meta = await fetchPrMeta(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
   return meta ? meta.body : null;
 };
+const defaultReadHeadSha: HeadShaReader = async (repo, prNumber) => {
+  const head = await fetchPrHead(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
+  return head ? head.headSha : null;
+};
 
 const BLOCK_UNVERIFIABLE =
   "Convergence blocked: could not verify the PR's review comments against GitHub. A human must confirm every Copilot review thread is resolved and every suppressed advisory acknowledged before this PR converges (reply to resume the loop).";
@@ -66,14 +83,56 @@ const BLOCK_UNVERIFIABLE =
 const BLOCK_UNVERIFIABLE_BODY =
   "Convergence blocked: could not read the PR description from GitHub to verify scope integrity. A human must confirm this PR does not close a broader-scoped parent with an untracked deferred remainder before it converges (reply to resume the loop).";
 
+// An `escalations` row as this worker reads it back when looking for a recorded human override.
+interface EscalationRow extends Record<string, unknown> {
+  id: number;
+  head_sha: string | null;
+  answer: string | null;
+  scope_block: number | boolean | null;
+}
+
+// Find the newest ANSWERED scope-integrity escalation for this PR whose recorded HEAD matches the
+// commit now under review (issue #395). This is the human-override door: `persist-escalation` binds
+// a scope block to the HEAD it was raised against, `answer-escalation` marks the row `answered`, and
+// here we honour that answer for the SAME HEAD so the gate stops re-deriving `scopeBlocked` from the
+// PR body and re-escalating the identical question forever. Newest-first so a re-escalated-then-
+// answered duplicate resolves to the operator's latest reply. Returns `null` on any read failure —
+// the caller then keeps the block (fail closed), never fabricates an override.
+async function findScopeOverride(
+  app: Parameters<AppJobHandler<In, Out>>[1],
+  prKey: string,
+  headSha: string,
+): Promise<ScopeEscalationAnswer | null> {
+  try {
+    // `scope_block` is a first-class column (persist-escalation writes it as 0/1), so filter on it
+    // in the query rather than reading every answered escalation and filtering in memory — a PR with
+    // many answered non-scope escalations no longer loads them all just to discard them.
+    const rows = await app.data.table<EscalationRow>("escalations", "id").find({
+      pr_key: prKey,
+      status: "answered",
+      scope_block: 1,
+    });
+    const scoped = rows
+      .map((r) => ({ escalationId: Number(r.id), headSha: r.head_sha ?? null, answer: r.answer ?? null }))
+      .sort((a, b) => (b.escalationId ?? 0) - (a.escalationId ?? 0));
+    for (const candidate of scoped) {
+      if (isScopeOverridden(headSha, candidate)) return candidate;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /** Build the handler with injectable GitHub readers. The default export binds the real readers;
  * tests inject stubs. Fails CLOSED — any unreadable/errored state blocks convergence. */
 export function makeHandler(deps: {
   readThreads: ThreadsReader;
   readReviewBody: ReviewBodyReader;
   readPrBody: PrBodyReader;
+  readHeadSha: HeadShaReader;
 }): AppJobHandler<In, Out> {
-  return async (job) => {
+  return async (job, app) => {
     const { prKey, repo, prNumber } = job.variables;
     // `parsePr` is total on any input (fails closed to `null` on a missing/non-string prKey), so
     // pass it straight through — a malformed prKey degrades to the fail-closed target check below.
@@ -83,6 +142,9 @@ export function makeHandler(deps: {
     if (!ghRepo || typeof ghNumber !== "number") {
       return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
     }
+    // The canonical escalations key. Prefer the carried prKey; fall back to the parsed identity so
+    // the override lookup still keys off `owner/repo#N` when only repo/prNumber survived.
+    const escPrKey = typeof prKey === "string" && prKey !== "" ? prKey : `${ghRepo}#${ghNumber}`;
 
     let result: ConvergeGateResult;
     let scopeReason: string;
@@ -127,13 +189,58 @@ export function makeHandler(deps: {
       return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE_BODY };
     }
 
+    // The human-override door for the scope-integrity block (issue #395). When the deterministic
+    // scope guard would re-block, read the commit now under review and consult the recorded
+    // escalation answer bound to that SAME HEAD: an operator who answered the scope question for
+    // this exact commit has explicitly overridden it ("this fully delivers the issue — keep the
+    // closing keyword"), so honour it (audited) instead of re-deriving the block from the body and
+    // re-escalating forever. Binding to the HEAD sha keeps the override from carrying across a new
+    // push (a different HEAD legitimately re-opens the gate); and if the human instead asked for a
+    // real split, the servicing agent pushes a fix — moving the HEAD so this stale override never
+    // fires. This is what turns the infinite escalation loop into a resolvable one.
+    let headSha: string | null = null;
+    let scopeBlocked = scopeReason !== "";
+    if (scopeBlocked) {
+      try {
+        headSha = await deps.readHeadSha(ghRepo, ghNumber);
+      } catch {
+        headSha = null;
+      }
+      if (headSha) {
+        const override = await findScopeOverride(app, escPrKey, headSha);
+        if (override) {
+          app.log.info("converge-gate: scope-integrity block overridden by human answer", {
+            prKey: escPrKey,
+            headSha,
+            escalationId: override.escalationId ?? null,
+            // The human answer is free-form operator input — never log it verbatim (it can carry
+            // sensitive content into application logs). Record only stable identifiers plus a
+            // minimal presence/length signal for debugging.
+            hasAnswer: override.answer != null && override.answer !== "",
+            answerLength: override.answer?.length ?? 0,
+          });
+          scopeReason = "";
+          scopeBlocked = false;
+        }
+      }
+    }
+
     // Both guards gate the same handoff to the merge loop: block if EITHER the review-comment gate
     // or the scope-integrity gate blocks, joining their reasons so the human sees every cause.
     const reason = [result.convergeBlockReason, scopeReason].filter((r) => r !== "").join(" ");
-    return {
-      convergeBlocked: result.convergeBlocked || scopeReason !== "",
+    const out: Out = {
+      convergeBlocked: result.convergeBlocked || scopeBlocked,
       convergeBlockReason: reason,
     };
+    // Surface the reviewed HEAD and the scope-block flag ONLY when scope actually blocks — the
+    // `persist-escalation-blockedcomments` arm (which runs only on a blocked gate) binds the
+    // escalation to this commit with them, opening the override door on the next round. A clean
+    // converge keeps its original `{ convergeBlocked, convergeBlockReason }` shape.
+    if (scopeBlocked) {
+      out.scopeBlocked = true;
+      out.headSha = headSha ?? undefined;
+    }
+    return out;
   };
 }
 
@@ -141,5 +248,6 @@ const handler = makeHandler({
   readThreads: defaultReadThreads,
   readReviewBody: defaultReadReviewBody,
   readPrBody: defaultReadPrBody,
+  readHeadSha: defaultReadHeadSha,
 });
 export default handler;

package/workers/persist-escalation/worker.ts

@@ -50,7 +50,7 @@ function workerOf(vars: Record<string, unknown>): string | undefined {
 }
 
 const handler: AppJobHandler<In> = async (job, app) => {
-  const { prKey, round, summary, repo, prNumber, prUrl, abandonUrl } = job.variables;
+  const { prKey, round, summary, repo, prNumber, prUrl, abandonUrl, headSha, scopeBlock } = job.variables;
   // `status` drives the escalation kind (control flow); a blank/absent status is an
   // unclassified escalation -> a question needing input. `question` is returned as a
   // process variable below so the downstream `wait-answer` userTask + `pr-escalation.form`
@@ -116,6 +116,13 @@ const handler: AppJobHandler<In> = async (job, app) => {
     worker,
     status: "open",
     asked_at: now,
+    // Bind a scope-integrity escalation to the reviewed commit (issue #395) so the converge-gate
+    // can honour a human answer as an override for THIS HEAD instead of re-deriving the block from
+    // the PR body and re-escalating forever. Only the scope-integrity arm passes these; every other
+    // arm leaves them absent (→ head_sha NULL, scope_block DEFAULT 0), so the override door opens
+    // exclusively for the block the human can actually answer.
+    head_sha: headSha,
+    scope_block: scopeBlock === true ? 1 : 0,
   });
   await app.data.table("pull_requests", "pr_key").update(prKey, {
     status: "escalated",