@nanobpm/nano-workforce 0.113.0 → 0.114.1

package/app/deliveryRunner.test.ts

@@ -0,0 +1,111 @@
+// Unit coverage for the delivery-graph RUNNER's PURE prepare step (ADR 0005 slice S4). `prepareDeliveryGraph`
+// compiles a graph, content-addresses its deploy id, rewrites the base process id, and builds the
+// `nodeInputs` seed — all without touching the engine. These tests pin, directly:
+//   • the content-addressed id (`delivery-graph-<sha12>`), and that it is DETERMINISTIC (same graph → same
+//     id) but CONTENT-SENSITIVE (a different graph → a different id) — the property that makes redeploy
+//     idempotent and stale definitions GC-identifiable (the ADR definition-lifecycle open question),
+//   • the base process id is rewritten to the content-addressed id in the deployable BPMN,
+//   • each node kind seeds the exact `nodeInputs` fields its compiled subProcess ioMapping reads,
+//   • a malformed graph returns the S1 compile errors and prepares nothing.
+// The engine-native EXECUTION of a prepared graph (deploy + run + gate + fan-in + late-bind + dedupe) is
+// proven end-to-end in `e2e/delivery-graph.e2e.ts`.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { prepareDeliveryGraph, runDeliveryGraph } from "./deliveryRunner.ts";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+
+const GRAPH: DeliveryGraph = {
+  name: "release runbook",
+  nodes: [
+    { id: "open-b", kind: "agent", agent: { jobType: "senior:feature", prompt: "un-draft + merge #B" } },
+    { id: "watch-b", kind: "wait", wait: { kind: "pr", target: "owner/repo#42", match: { prState: "merged" } }, emits: [{ name: "mergedSha", type: "string" }] },
+    { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" }, emits: [{ name: "resolvedArtifact", type: "artifact" }] },
+    { id: "consume", kind: "connector", connector: { target: "npm:install", dedupeKey: "consume-1" } },
+  ],
+  edges: [
+    { from: "open-b", to: "watch-b" },
+    { from: "watch-b.mergedSha", to: "publish" },
+    { from: "publish.resolvedArtifact", to: "consume" },
+  ],
+};
+
+function prepareOk(graph: DeliveryGraph, options = {}) {
+  const r = prepareDeliveryGraph(graph, options);
+  assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
+  return r.prepared;
+}
+
+test("content-addressed id: deterministic for the same graph, content-sensitive across graphs", () => {
+  const a = prepareOk(GRAPH);
+  const b = prepareOk(GRAPH);
+  assert(/^delivery-graph-[0-9a-f]{12}$/.test(a.processDefinitionId), `id is content-addressed, got ${a.processDefinitionId}`);
+  assertEquals(a.processDefinitionId, b.processDefinitionId);
+
+  // A structurally different graph gets a DIFFERENT id (no collision / no accidental redeploy-as-same).
+  const other = prepareOk({ ...GRAPH, nodes: [...GRAPH.nodes, { id: "extra", kind: "agent", agent: { jobType: "senior:feature" } }], edges: [...GRAPH.edges, { from: "consume", to: "extra" }] });
+  assert(other.processDefinitionId !== a.processDefinitionId, "a different graph yields a different id");
+});
+
+test("the deployable BPMN rewrites the base process id to the content-addressed deploy id", () => {
+  const p = prepareOk(GRAPH);
+  assert(p.bpmn.includes(`<bpmn:process id="${p.processDefinitionId}"`), "process id is the content-addressed id");
+  assert(!p.bpmn.includes('<bpmn:process id="delivery-graph"'), "the base id no longer appears as the process id");
+});
+
+test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMapping reads", () => {
+  const p = prepareOk(GRAPH, { nodeTimeout: "PT10M", probeTimeout: "PT20M", escalationSlaTimeout: "PT2H", escalationAssignee: "alice", runKey: "run-7" });
+  // Element ids are positional by sorted node id: consume, open-b, publish, watch-b → n0..n3.
+  const inputs = p.nodeInputs;
+  const byField = (pred: (v: Record<string, unknown>) => boolean) => Object.values(inputs).find((v) => pred(v as Record<string, unknown>)) as Record<string, unknown> | undefined;
+
+  const agent = byField((v) => v.jobType === "senior:feature");
+  assertEquals(agent, { jobType: "senior:feature", appendPrompt: "un-draft + merge #B", timeout: "PT10M" });
+
+  const wait = byField((v) => "gateKey" in v);
+  assertEquals(wait?.gateKey, "run-7:n3");
+  assertEquals(wait?.probeTimeout, "PT20M");
+  assert(wait?.probe && typeof wait.probe === "object", "the wait node carries its ReadinessProbe descriptor");
+
+  const human = byField((v) => "escalationSlaTimeout" in v);
+  assertEquals(human, { escalationSlaTimeout: "PT2H", escalationAssignee: "alice" });
+
+  const connector = byField((v) => v.target === "npm:install");
+  assertEquals(connector, { target: "npm:install", dedupeKey: "consume-1", payload: null, timeout: "PT10M" });
+});
+
+test("wait gateKeys default to a fresh per-run token so concurrent runs of one graph never cross-correlate", () => {
+  const gateKeyOf = (p: ReturnType<typeof prepareOk>) =>
+    (Object.values(p.nodeInputs).find((v) => "gateKey" in v) as { gateKey?: string } | undefined)?.gateKey;
+
+  const a = prepareOk(GRAPH);
+  const b = prepareOk(GRAPH);
+  assert(gateKeyOf(a) && gateKeyOf(b), "each run seeds a wait gateKey");
+  assert(gateKeyOf(a) !== gateKeyOf(b), "two runs of the same graph get DISTINCT default gate scopes");
+  // The gate key must NOT be derived from the (shared) content digest — that is the bug this guards.
+  assert(!gateKeyOf(a)?.startsWith(a.processDefinitionId.slice(-12)), "default gateKey is not the graph digest");
+  // The deployable definition (id + bpmn) stays deterministic regardless of the per-run gate scope.
+  assertEquals(a.processDefinitionId, b.processDefinitionId);
+  assertEquals(a.bpmn, b.bpmn);
+
+  // An explicit runKey is honoured verbatim (reproducible seed).
+  const seeded = prepareOk(GRAPH, { runKey: "run-7" });
+  assertEquals(gateKeyOf(seeded), "run-7:n3");
+});
+
+test("a malformed graph returns the S1 compile errors and prepares nothing", () => {
+  const r = prepareDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] } as unknown as DeliveryGraph);
+  assert(!r.ok, "a dangling edge fails to prepare");
+  assert(r.errors.some((e) => e.path === "edges[0].to"), `expected a dangling-edge error, got ${JSON.stringify(r.errors)}`);
+});
+
+test("runDeliveryGraph coerces a numeric engine processInstanceKey to a string handle", async () => {
+  // The engine can yield a NUMERIC key; the handle is typed `string` and downstream expects a string.
+  const engine = {
+    deployResources: async () => [],
+    createInstance: async () => ({ processInstanceKey: 987654321 as unknown as string }),
+  };
+  const r = await runDeliveryGraph(engine, GRAPH);
+  assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
+  assertEquals(r.handle.processInstanceKey, "987654321");
+  assertEquals(typeof r.handle.processInstanceKey, "string");
+});

package/app/deliveryRunner.ts

@@ -0,0 +1,169 @@
+// nano-workforce — the delivery-graph RUNNER (ADR 0005 slice S4). The integration step that turns the
+// PURE compiled preview (S1's `compileDeliveryGraph`) into a RUNNING, engine-native process: it deploys
+// the compile-to-native one-shot definition and starts an instance, seeding each node's config so the
+// inlined subProcess bodies (agent/wait/human/connector) delegate to their existing worker / user-task
+// bodies. It builds NO execution machinery of its own (Decision 2 — the graph SCHEDULES; the engine
+// runs it); its whole job is deploy + seed + start.
+//
+// Definition lifecycle (the ADR open question, resolved here): the deployed process id is
+// CONTENT-ADDRESSED — `delivery-graph-<sha256(bpmn)[:12]>`. Identical graphs compile byte-identically
+// (S1 determinism) → identical id → an idempotent redeploy (the engine versions the same id, never a
+// duplicate definition per run); different graphs get different ids and never collide; and because the
+// id ENCODES its content, a stale one-shot definition is GC-identifiable by a later sweeper (out of
+// scope to implement the sweeper — the naming is what enables it). The base id the compiler emits
+// (`DELIVERY_GRAPH_PROCESS_ID`) is the single substitution target, so the runner never hardcodes it.
+
+import { createHash, randomUUID } from "node:crypto";
+import type { EngineClient } from "@nanobpm/urban";
+import type { DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
+import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
+
+/** The bounded-timeout / SLA envelope every node inherits (Decision: bounded → escalate). ISO-8601
+ * durations. Defaults are conservative; a caller (the S5 door) may tighten them per run. */
+export interface DeliveryRunTimeouts {
+  /** `agent`/`connector` service-node bounded timeout before it escalates onto a human-completable task. */
+  nodeTimeout?: string;
+  /** `wait` gate poll budget before it escalates (the engine bound; the probe itself is read-only). */
+  probeTimeout?: string;
+  /** `human` node SLA before it records an `escalated` outcome and settles. */
+  escalationSlaTimeout?: string;
+  /** Optional explicit assignee for `human` nodes + escalation tasks (else candidate-group routed). */
+  escalationAssignee?: string | null;
+}
+
+export interface DeliveryRunOptions extends DeliveryRunTimeouts {
+  /** A per-run token that scopes each `wait` node's gate key (`<runKey>:<element>`) so two concurrent
+   * runs of the same graph never share a gate correlation. Defaults to a fresh random per-run token
+   * (`randomUUID()`) — NOT the graph digest, which every run of an identical graph would share and so
+   * cross-correlate. Pass an explicit `runKey` only when you need a reproducible/externally-owned gate
+   * scope. */
+  runKey?: string;
+}
+
+const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
+  nodeTimeout: "PT30M",
+  probeTimeout: "PT30M",
+  escalationSlaTimeout: "P1D",
+};
+
+/** The per-node config the compiled subProcess ioMappings read from `nodeInputs.<element>`. A closed
+ * union mirrored by the compiler's `ioMappingLines` — the two must agree on field names (a drift here
+ * silently seeds `null` into a node body), so both derive from the same node kinds. */
+type NodeInput =
+  | { jobType: string; appendPrompt: string; timeout: string }
+  | { gateKey: string; probe: unknown; probeTimeout: string }
+  | { escalationSlaTimeout: string; escalationAssignee: string | null }
+  | { target: string; dedupeKey: string | null; payload: Record<string, unknown> | null; timeout: string };
+
+/** The result of compiling + preparing a graph for deployment: the content-addressed process id, the
+ * deployable BPMN (base id rewritten), and the seeded `nodeInputs` map — everything `runDeliveryGraph`
+ * needs, exposed separately so a caller can deploy/inspect without starting an instance. */
+export interface PreparedDeliveryGraph {
+  processDefinitionId: string;
+  bpmn: string;
+  nodeInputs: Record<string, NodeInput>;
+}
+
+export type PrepareDeliveryResult =
+  | { ok: true; prepared: PreparedDeliveryGraph }
+  | { ok: false; errors: { path: string; message: string }[] };
+
+/** A live delivery-graph run: the deployed definition + the started instance + the seed it ran with. */
+export interface DeliveryRunHandle extends PreparedDeliveryGraph {
+  processInstanceKey: string;
+}
+
+export type RunDeliveryResult =
+  | { ok: true; handle: DeliveryRunHandle }
+  | { ok: false; errors: { path: string; message: string }[] };
+
+/** Compile a graph and prepare it for deployment WITHOUT touching the engine: content-address its id,
+ * rewrite the base process id, and build the `nodeInputs` seed. The deployable DEFINITION (the
+ * content-addressed `processDefinitionId` and the `bpmn`) is deterministic — the same graph yields the
+ * same id, which is what makes redeploy idempotent — because the gate scope lives in `nodeInputs`
+ * (runtime instance variables), not in the BPMN. The default `runKey` is a fresh random per-run token,
+ * so each call's `wait` `gateKey`s differ (two concurrent runs of the same graph never cross-correlate);
+ * pass an explicit `runKey` for a reproducible seed. Returns the S1 compile errors verbatim for a
+ * malformed graph. */
+export function prepareDeliveryGraph(graph: DeliveryGraph, options: DeliveryRunOptions = {}): PrepareDeliveryResult {
+  const compiled = compileDeliveryGraph(graph);
+  if (!compiled.ok) return { ok: false, errors: compiled.errors };
+
+  const digest = createHash("sha256").update(compiled.bpmn).digest("hex").slice(0, 12);
+  const processDefinitionId = `${DELIVERY_GRAPH_PROCESS_ID}-${digest}`;
+  const bpmn = rewriteProcessId(compiled.bpmn, processDefinitionId);
+
+  const runKey = options.runKey?.trim() || randomUUID();
+  const timeouts = {
+    nodeTimeout: options.nodeTimeout ?? DEFAULTS.nodeTimeout,
+    probeTimeout: options.probeTimeout ?? DEFAULTS.probeTimeout,
+    escalationSlaTimeout: options.escalationSlaTimeout ?? DEFAULTS.escalationSlaTimeout,
+    escalationAssignee: options.escalationAssignee ?? null,
+  };
+  const elementByNodeId = new Map(compiled.resolved.nodes.map((n) => [n.id, n.element]));
+  const nodeInputs: Record<string, NodeInput> = {};
+  for (const node of graph.nodes) {
+    const element = elementByNodeId.get(node.id);
+    if (element === undefined) continue; // unreachable — resolved covers every node — but keep total.
+    nodeInputs[element] = buildNodeInput(node, { runKey, element, ...timeouts });
+  }
+  return { ok: true, prepared: { processDefinitionId, bpmn, nodeInputs } };
+}
+
+/** Deploy + start a compiled graph as a running engine-native instance. Idempotent at the DEFINITION
+ * level (content-addressed id — redeploying the same graph re-uses the definition); each call still
+ * starts a fresh INSTANCE (a distinct run of that definition). Returns the run handle, or the compile
+ * errors for a malformed graph (the engine is never touched in that case). */
+export async function runDeliveryGraph(
+  engine: Pick<EngineClient, "deployResources" | "createInstance">,
+  graph: DeliveryGraph,
+  options: DeliveryRunOptions = {},
+): Promise<RunDeliveryResult> {
+  const prep = prepareDeliveryGraph(graph, options);
+  if (!prep.ok) return prep;
+  const { processDefinitionId, bpmn, nodeInputs } = prep.prepared;
+
+  await engine.deployResources([{ name: `${processDefinitionId}.bpmn`, content: bpmn, contentType: "application/xml" }]);
+  const { processInstanceKey } = await engine.createInstance({
+    processDefinitionId,
+    variables: { nodeInputs },
+  });
+  // The engine can yield a numeric key; `DeliveryRunHandle.processInstanceKey` is typed `string` and
+  // downstream consumers expect a string — coerce (codebase-wide `String(...)` pattern, e.g. app/plan.ts).
+  return {
+    ok: true,
+    handle: { processDefinitionId, bpmn, nodeInputs, processInstanceKey: String(processInstanceKey) },
+  };
+}
+
+/** Rewrite the compiled BPMN's base `bpmn:process` id to the content-addressed deploy id. The base id
+ * appears exactly once — as the process element's `id` attribute (element ids are `n<i>`/`gw*`/`Start`/
+ * `End`, never the process id) — so a single targeted replacement is unambiguous. */
+function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
+  return bpmn.replace(`id="${DELIVERY_GRAPH_PROCESS_ID}"`, `id="${processDefinitionId}"`);
+}
+
+/** Build the `nodeInputs.<element>` seed for one node, per its kind — the exact fields the compiled
+ * subProcess ioMapping pulls. Total over the closed kind set. */
+function buildNodeInput(
+  node: DeliveryNode,
+  ctx: { runKey: string; element: string; nodeTimeout: string; probeTimeout: string; escalationSlaTimeout: string; escalationAssignee: string | null },
+): NodeInput {
+  switch (node.kind) {
+    case "agent":
+      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: ctx.nodeTimeout };
+    case "wait":
+      return { gateKey: `${ctx.runKey}:${ctx.element}`, probe: node.wait, probeTimeout: ctx.probeTimeout };
+    case "human":
+      return { escalationSlaTimeout: ctx.escalationSlaTimeout, escalationAssignee: ctx.escalationAssignee };
+    case "connector":
+      return {
+        target: node.connector.target,
+        dedupeKey: node.connector.dedupeKey ?? null,
+        payload: node.connector.payload ?? null,
+        timeout: ctx.nodeTimeout,
+      };
+    default:
+      return assertNever(node, "buildNodeInput");
+  }
+}

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/app/userTasks.test.ts

@@ -6,6 +6,7 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
+import { DELIVERY_HUMAN_ELEMENT } from "./deliveryHuman.ts";
 import type { PlanReview } from "./plan.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
 import {
@@ -19,6 +20,7 @@ import {
   type PrEscalationRow,
   reconcileUserTasks,
   TRIAL_MERGE_ELEMENT,
+  userTaskKindLabel,
   type UserTaskRow,
 } from "./userTasks.ts";
 
@@ -91,6 +93,40 @@ test("buildUserTaskRow: an unknown (non-escalation) element yields null — no a
   assertEquals(row, null);
 });
 
+test("userTaskKindLabel/buildUserTaskRow: an INLINED delivery-human element surfaces under one label; a non-matching internal task is dropped (app/userTasks.ts:122)", () => {
+  // The S4 compiler inlines each `human` node (and its bounded-timeout escalation twin) with a
+  // per-node id `delivery-human-task__<el>[__esc]`, which a bare `USER_TASK_KIND_LABELS` lookup would
+  // miss — so the delivery-human convention MUST be recognised through `isDeliveryHumanElement`.
+  const LABEL = "Delivery: human step";
+  // The bare static body id and both inlined conventions resolve to the one delivery-human label…
+  assertEquals(userTaskKindLabel(DELIVERY_HUMAN_ELEMENT), LABEL);
+  assertEquals(userTaskKindLabel(`${DELIVERY_HUMAN_ELEMENT}__ship-it`), LABEL);
+  assertEquals(userTaskKindLabel(`${DELIVERY_HUMAN_ELEMENT}__ship-it__esc`), LABEL);
+  // …while a non-matching internal task (a near-miss that is NOT the delivery-human prefix) is not a
+  // surfaced kind, so it never leaks into the inbox.
+  assertEquals(userTaskKindLabel("delivery-human-taskish"), undefined);
+  assertEquals(userTaskKindLabel("some-internal-task"), undefined);
+
+  // And end-to-end through the row builder: an inlined delivery-human task projects a labelled row…
+  const inlined = buildUserTaskRow(
+    { userTaskKey: "ut-dh", elementId: `${DELIVERY_HUMAN_ELEMENT}__ship-it`, subjectType: "delivery", subjectKey: "graph-1", question: "approve the release?" },
+    AT,
+  );
+  assert(inlined !== null);
+  assertEquals(inlined?.element_id, `${DELIVERY_HUMAN_ELEMENT}__ship-it`);
+  assertEquals(inlined?.kind_label, LABEL);
+  assertEquals(inlined?.subject_type, "delivery");
+  assertEquals(inlined?.question, "approve the release?");
+  // …whereas a non-matching internal task still yields null (the leak guard holds for the near-miss).
+  assertEquals(
+    buildUserTaskRow(
+      { userTaskKey: "ut-dh2", elementId: "delivery-human-taskish", subjectType: "delivery", subjectKey: "graph-1" },
+      AT,
+    ),
+    null,
+  );
+});
+
 test("buildUserTaskRow: a blank userTaskKey yields null; a known kind with a blank subject key still builds (issue #358)", () => {
   // The completable key is load-bearing (the page completes THROUGH it), so a blank one is still null.
   assertEquals(

package/app/userTasks.ts

@@ -19,7 +19,7 @@
 // it open.
 import type { DataLayer } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
-import { DELIVERY_HUMAN_ELEMENT } from "./deliveryHuman.ts";
+import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, type FeatureEscalationRow } from "./feature.ts";
 import type { PlanReview } from "./plan.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
@@ -80,6 +80,16 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [DELIVERY_HUMAN_ELEMENT]: "Delivery: human step",
 };
 
+/** The Tasks-inbox label for an open user-task `elementId`, or `undefined` when the element is not a
+ *  surfaced kind (so an arbitrary internal user task is never listed). Exact table lookup PLUS the
+ *  delivery-human convention: the S4 compiler inlines each `human` node (and each service node's
+ *  bounded-timeout escalation twin) with a per-node id `delivery-human-task__<el>[__esc]`, which a bare
+ *  table lookup would miss — matched through the single-source-of-truth `isDeliveryHumanElement`
+ *  predicate so every inlined human/escalation task surfaces under the one delivery-human label. */
+export function userTaskKindLabel(elementId: string): string | undefined {
+  return USER_TASK_KIND_LABELS[elementId] ?? (isDeliveryHumanElement(elementId) ? USER_TASK_KIND_LABELS[DELIVERY_HUMAN_ELEMENT] : undefined);
+}
+
 /** The denormalised context the poller has resolved for an open escalation user task. */
 export interface UserTaskContext {
   userTaskKey: string;
@@ -108,7 +118,7 @@ export interface UserTaskContext {
  *  tasks out of the inbox). */
 export function buildUserTaskRow(ctx: UserTaskContext, at: string = now()): UserTaskRow | null {
   const userTaskKey = ctx.userTaskKey.trim();
-  const kindLabel = USER_TASK_KIND_LABELS[ctx.elementId];
+  const kindLabel = userTaskKindLabel(ctx.elementId);
   if (!userTaskKey || !kindLabel) return null;
   const subjectKey = ctx.subjectKey.trim() || (ctx.processKey ?? "").trim() || userTaskKey;
   const question = typeof ctx.question === "string" && ctx.question.trim() ? ctx.question.trim() : null;

package/db/migrations/055_delivery_connector_dedupe.sql

@@ -0,0 +1,26 @@
+-- The delivery-graph `connector` node's idempotency ledger (ADR 0005 Decision 6/7, slice S4). A
+-- `connector` is the epic's one SIDE-EFFECTING node kind (`agent`/`wait`/`human` are read-only or
+-- human-gated): it drives an outbound action against the forward-declared connector I/O surface. The
+-- engine delivers a service-task job AT-LEAST-ONCE — a worker/hub restart, a lost completion ack, or a
+-- graph resume re-activates the same job — so a naive connector would double-fire its side effect on
+-- every redelivery. This ledger makes each dispatch fire AT-MOST-ONCE per dedupe key: the worker
+-- claims the key here BEFORE performing the action, and a redelivery that finds the key already
+-- claimed short-circuits to the recorded outcome instead of re-dispatching.
+--
+-- The UNIQUE fence on `dedupe_key` is the durable at-most-once guarantee (the canonical durable-fence
+-- idiom — cf. `ux_merges_abandon_pr_closed` in 053 and the world-store ledgers in 049): a concurrent
+-- redelivery that races the claim loses the insert and is classified by `app/dbFence.ts`
+-- (`isUniqueConstraintFence`) as the SAME idempotent outcome, never a spurious job failure. The key is
+-- author-supplied (`connector.dedupeKey`) or graph-derived (`<processInstanceKey>:<elementId>`) — both
+-- stable across a re-activation of the same node instance.
+CREATE TABLE IF NOT EXISTS delivery_connector_dispatches (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  dedupe_key TEXT NOT NULL,
+  target TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  detail TEXT,
+  dispatched_at TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS ux_delivery_connector_dedupe
+  ON delivery_connector_dispatches (dedupe_key);

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;