@nanobpm/nano-workforce 0.113.0 → 0.114.1

package/e2e/delivery-graph.e2e.ts

@@ -0,0 +1,197 @@
+// End-to-end proof that a COMPILED delivery graph deploys and runs ENGINE-NATIVELY on the WASM engine
+// + virtual clock (ADR 0005 slice S4) — the integration acceptance the whole slice hinges on. Driven
+// via `bootTestApp`, hermetic (deterministic shell-builtin `command` probes, no network, no GitHub;
+// the `pr` kind's merge-state semantics are S2's surface, proven there — S4 proves the wait NODE
+// executes engine-natively and gates, whatever the probe kind):
+//
+//   • RUNS END-TO-END + FAN-IN + LATE-BIND: a graph with `agent`, `wait`, `human` and `connector`
+//     nodes deploys and runs; the agent job fires, the wait gate resolves, the human task completes,
+//     the connector fires — and the graph reaches End only after the wait AND the human both feed the
+//     connector (fan-in). The human's emitted `artifact` fact LATE-BINDS into the connector's input.
+//   • RESUME NEVER DOUBLE-FIRES: after the connector has fired once, an at-least-once redelivery of the
+//     same dispatch (a resume) DEDUPES — the durable ledger still holds exactly one row (Decision 7).
+//   • CONCURRENCY-CORRECTNESS: while a `wait` is parked on a never-green probe, completing an UNRELATED
+//     parallel human node does NOT falsely resolve the wait (the node polls its OWN target — there is no
+//     shared message correlation an unrelated event could trip, inheriting #274/S2); the wait stays
+//     parked until its bounded budget elapses, then escalates (bounded → escalate, never wedged).
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { connectorDedupeKey, deliveryConnectorDispatches, dispatchConnector } from "../app/deliveryConnector.ts";
+import { readConnectorInput } from "../workers/delivery-connector/worker.ts";
+import { runDeliveryGraph } from "../app/deliveryRunner.ts";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GITHUB_ENV: Record<string, string> = { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "" };
+
+interface TakenFlow {
+  from: string;
+  to: string;
+}
+function takenFlows(app: TestApp): string[] {
+  const snap = app.snapshot();
+  const flows = Array.isArray(snap.takenSequenceFlows) ? snap.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+/** Boot a fresh app per scenario (the WASM engine's taken-flow snapshot is engine-global cumulative). */
+async function boot(dir: string): Promise<TestApp> {
+  return bootTestApp(APP_ROOT, { env: { ...GITHUB_ENV, NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+}
+
+describe("delivery-graph runner — engine-native execution (S4)", () => {
+  const dirs: string[] = [];
+  const apps: TestApp[] = [];
+  const freshDir = (): string => {
+    const d = mkdtempSync(join(tmpdir(), "nwf-delivery-e2e-"));
+    dirs.push(d);
+    return d;
+  };
+  const track = (app: TestApp): TestApp => {
+    apps.push(app);
+    return app;
+  };
+  after(async () => {
+    for (const app of apps) await app.stop?.();
+    for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  });
+
+  test("runs end-to-end: agent, wait, human execute; edges gate; fan-in works; human fact late-binds into the connector", async () => {
+    const app = track(await boot(freshDir()));
+
+    let agentFired = 0;
+    let connectorBoundFacts: unknown;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return {};
+    });
+    // Wrap the REAL connector job path so we can observe the late-bound facts it received. The worker
+    // itself is registered from the manifest; here we register a same-type observer stub for the e2e.
+    // Mirror the REAL worker's normalization — `readConnectorInput` (trim+require `target`, coerce a
+    // wrong-shaped payload/boundFacts) and `connectorDedupeKey` (derive the effective key from the
+    // author key OR the engine identity `processInstanceKey:elementId`, fail closed if neither) — so
+    // this observer exercises the same fail-closed/derivation behavior the production worker does and
+    // a regression in that surface can't hide behind a `String(... ?? "")` coercion.
+    await app.engine.registerWorker(
+      "pr.delivery-connector",
+      async (job) => {
+        const vars = job.variables as Record<string, unknown>;
+        connectorBoundFacts = vars.boundFacts;
+        const { target, payload, boundFacts } = readConnectorInput(
+          vars as Parameters<typeof readConnectorInput>[0],
+        );
+        const dedupeKey = connectorDedupeKey({
+          dedupeKey: (vars.dedupeKey as string | null | undefined) ?? null,
+          processInstanceKey: job.processInstanceKey ?? null,
+          elementId: job.elementId ?? null,
+        });
+        if (!dedupeKey) {
+          throw new Error("delivery-connector: no dedupe key (author-supplied or graph-derived) available");
+        }
+        return await dispatchConnector(
+          app.db,
+          { dedupeKey, target, payload, boundFacts },
+          new Date().toISOString(),
+        );
+      },
+      { fetchVariables: ["boundFacts", "target", "dedupeKey", "payload"] },
+    );
+
+    const graph: DeliveryGraph = {
+      name: "e2e end-to-end",
+      nodes: [
+        { id: "a", kind: "agent", agent: { jobType: "senior:demo" } },
+        { id: "w", kind: "wait", wait: { kind: "command", target: "true", poll: { everyMs: 5, backoff: "fixed" } } },
+        { id: "h", kind: "human", emits: [{ name: "art", type: "artifact" }] },
+        { id: "c", kind: "connector", connector: { target: "slack", dedupeKey: "c-e2e-1" } },
+      ],
+      edges: [
+        { from: "a", to: "h" },
+        { from: "h.art", to: "c" },
+        { from: "w", to: "c" },
+      ],
+    };
+
+    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S" });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // The agent node executed via its engine-native serviceTask body.
+    assert.equal(agentFired, 1, "the agent node's job fired once");
+
+    // The human node scheduled its per-node user task (the isDeliveryHumanElement convention id).
+    const open = await app.engine.searchUserTasks({ state: "CREATED" });
+    const human = open.find((t) => t.elementId?.startsWith("delivery-human-task__") && !t.elementId?.endsWith("__esc"));
+    assert.ok(human, `a human user task is open, got ${JSON.stringify(open.map((t) => t.elementId))}`);
+
+    // Before the human completes, the connector has NOT fired — the fan-in edge from `h` gates it.
+    assert.equal((await deliveryConnectorDispatches(app.db).find({})).length, 0, "connector waits on the human edge");
+
+    // Complete the human with a resolved artifact — its typed emit late-binds downstream.
+    await app.engine.completeUserTask(human.userTaskKey, { resolvedArtifact: "ARTIFACT-1", humanOutcome: "completed" });
+    await app.settle();
+
+    // The connector fired exactly once (fan-in of the wait AND the human both satisfied), and it
+    // received the human's emitted fact as a late-bound input.
+    const rows = await deliveryConnectorDispatches(app.db).find({ dedupe_key: "c-e2e-1" });
+    assert.equal(rows.length, 1, "the connector fired exactly once");
+    assert.equal(rows[0].outcome, "delivered");
+    assert.deepEqual(connectorBoundFacts, [{ from: "h", name: "art", value: "ARTIFACT-1" }], "the human fact late-binds into the connector");
+
+    // The graph reached End — the fan-in join released only after BOTH upstream branches completed.
+    assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the graph reached its End event");
+  });
+
+  test("resume never double-fires: an at-least-once redelivery of the connector dedupes", async () => {
+    const app = track(await boot(freshDir()));
+    // The connector fired once above's-style; here prove the idempotency directly against the ledger a
+    // resumed graph shares. First dispatch delivers; a redelivery of the SAME dispatch (the resume) is
+    // deduped and the durable ledger still holds exactly ONE row — the side effect never re-fires.
+    const first = await dispatchConnector(app.db, { dedupeKey: "resume-1", target: "slack" }, new Date().toISOString());
+    assert.equal(first.connectorOutcome, "delivered");
+    const replay = await dispatchConnector(app.db, { dedupeKey: "resume-1", target: "slack" }, new Date().toISOString());
+    assert.equal(replay.connectorOutcome, "deduped", "a resume redelivery dedupes");
+    assert.equal((await deliveryConnectorDispatches(app.db).find({ dedupe_key: "resume-1" })).length, 1, "exactly one durable dispatch");
+  });
+
+  test("concurrency-correctness: an unrelated human completion does not falsely resolve a parked wait", async () => {
+    const app = track(await boot(freshDir()));
+    // Two independent parallel branches: a NEVER-GREEN wait, and an unrelated human. The wait polls its
+    // own `false` target (never ready) — there is NO shared correlation an unrelated event could trip.
+    const graph: DeliveryGraph = {
+      name: "e2e concurrency",
+      nodes: [
+        { id: "gate", kind: "wait", wait: { kind: "command", target: "false", poll: { everyMs: 5, backoff: "fixed" } } },
+        { id: "side", kind: "human", emits: [{ name: "ok", type: "string" }] },
+      ],
+      edges: [],
+    };
+    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S", escalationSlaTimeout: "PT1H" });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // Complete the UNRELATED human node — an upstream event with no edge to the wait.
+    const open = await app.engine.searchUserTasks({ state: "CREATED" });
+    const side = open.find((t) => t.elementId?.startsWith("delivery-human-task__") && !t.elementId?.endsWith("__esc"));
+    assert.ok(side, "the unrelated human task is open");
+    await app.engine.completeUserTask(side.userTaskKey, { value: "done", humanOutcome: "completed" });
+    await app.settle();
+
+    // The wait polls `false` — it can NEVER resolve as ready, so completing the unrelated human could
+    // not trip it: the graph never reaches End (the wait never released its "ready" branch). Instead the
+    // wait is BOUNDED — its poll budget elapses and it escalates onto a human-completable task, parking
+    // for a human rather than silently wedging or falsely resolving.
+    assert.ok(!takenFlows(app).some((f) => f.endsWith("->End")), "the wait branch never falsely resolves to End");
+    const esc = (await app.engine.searchUserTasks({ state: "CREATED" })).filter((t) => t.elementId?.endsWith("__esc"));
+    assert.ok(
+      esc.length >= 1,
+      `the parked wait escalates (bounded), never falsely resolved by the unrelated event, got ${JSON.stringify((await app.engine.searchUserTasks({ state: "CREATED" })).map((t) => t.elementId))}`,
+    );
+  });
+});

package/nano.app.json

@@ -199,6 +199,10 @@
     {
       "taskType": "pr.readiness-probe",
       "handler": "workers/readiness-probe/worker.ts"
+    },
+    {
+      "taskType": "pr.delivery-connector",
+      "handler": "workers/delivery-connector/worker.ts"
     }
   ],
   "externalTaskTypes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.113.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/delivery-connector/worker.test.ts

@@ -0,0 +1,44 @@
+// Unit coverage for the pr.delivery-connector worker's input validation (workers/delivery-connector/worker.ts).
+// Job variables are UNTYPED at runtime, so the worker must not forward a misconfigured node's garbage
+// into the (side-effecting) connector I/O surface: a blank `target` fails CLOSED, and a wrong-shaped
+// `payload`/`boundFacts` is coerced to null with a surfaced warning rather than passed through.
+import { test } from "node:test";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { readConnectorInput } from "./worker.ts";
+
+test("readConnectorInput: a blank/missing target fails closed (a connector with no destination is meaningless)", () => {
+  for (const target of [undefined, "", "   "]) {
+    assertThrows(() => readConnectorInput({ target }), Error, "target");
+  }
+});
+
+test("readConnectorInput: a valid target is trimmed and passed through; well-shaped payload/boundFacts survive", () => {
+  const facts = [{ from: "n1", name: "mergedSha", value: "abc" }];
+  const r = readConnectorInput({ target: "  slack  ", payload: { channel: "#rel" }, boundFacts: facts });
+  assertEquals(r.target, "slack");
+  assertEquals(r.payload, { channel: "#rel" });
+  assertEquals(r.boundFacts, facts);
+  assertEquals(r.warnings.length, 0);
+});
+
+test("readConnectorInput: absent payload/boundFacts default to null with no warning", () => {
+  const r = readConnectorInput({ target: "slack" });
+  assertEquals(r.payload, null);
+  assertEquals(r.boundFacts, null);
+  assertEquals(r.warnings.length, 0);
+});
+
+test("readConnectorInput: a non-object payload / non-array boundFacts is coerced to null and warned (never forwarded)", () => {
+  const r = readConnectorInput({ target: "slack", payload: "oops" as unknown as Record<string, unknown>, boundFacts: "nope" as unknown as [] });
+  assertEquals(r.payload, null, "a scalar payload never reaches the connector surface");
+  assertEquals(r.boundFacts, null, "a non-array boundFacts never reaches the connector surface");
+  assertEquals(r.warnings.length, 2, "both coercions are surfaced for logging (not silent)");
+  assert(r.warnings.some((w) => w.includes("payload")), "the payload coercion is named");
+  assert(r.warnings.some((w) => w.includes("boundFacts")), "the boundFacts coercion is named");
+});
+
+test("readConnectorInput: an array payload is rejected (arrays are not plain objects)", () => {
+  const r = readConnectorInput({ target: "slack", payload: [1, 2, 3] as unknown as Record<string, unknown> });
+  assertEquals(r.payload, null);
+  assertEquals(r.warnings.length, 1);
+});