@nanobpm/nano-workforce 0.114.0 → 0.114.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [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/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/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/package.json

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