@nanobpm/nano-workforce 0.77.0 → 0.78.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.78.0](https://github.com/nanobpm/nano-workforce/compare/v0.77.0...v0.78.0) (2026-08-17)
+
+
+### Features
+
+* converge the merge-loop escalation onto one native user-task pathway ([#256](https://github.com/nanobpm/nano-workforce/issues/256)) ([#257](https://github.com/nanobpm/nano-workforce/issues/257)) ([16551ee](https://github.com/nanobpm/nano-workforce/commit/16551ee59015081dcf20294ffdd05a078564b775))
+
 # [0.77.0](https://github.com/nanobpm/nano-workforce/compare/v0.76.0...v0.77.0) (2026-08-17)
 
 

package/SPEC.md

@@ -103,19 +103,22 @@ known at submit time, carried as a process variable and stored on the DB row.
 │      │                     ├── review-ready (msg catch, key = prKey) → round++ ─────┐
 │      │                     └── =reviewWaitTimeout (timer catch)                     │
 │      │                          → [Escalate: review stalled] (blocked)              │
-│      │                          → [Wait: escalation-answered] ──────────────────────┤
+│      │                          → [Wait: wait-answer userTask] ─────────────────────┤
 │      │                                                                             │
 │      └── needs_input     [Record escalation]                       │               │
 │          or blocked  →   (kind = question | blocker)               │               │
-│                          → [Wait: escalation-answered] (msg catch) │               │
+│                          → [Wait: wait-answer userTask]            │               │
+│                          → [record-answer: pr.answer-escalation]   │               │
 │                          → set answer ──────────────────────────────┤               │
 │                                                                    │               │
 └────────────────────────────────────────────────────────────────────┴───────────────┘
 
 Both `needs_input` (the agent has a question) and `blocked` (the agent is stuck
 on something external — auth, a failing push, a missing secret) route to the
-**same escalation path**: record it, sleep at `escalation-answered`, then retry
-the same round with the human's `answer`. They differ only by escalation `kind`,
+**same escalation path**: record it, park on the native `wait-answer` user task
+(answered through the canonical `completeUserTask` door and surfaced in the Tasks
+inbox), reconcile the answer via the `record-answer` (`pr.answer-escalation`)
+step, then retry the same round with the human's `answer`. They differ only by escalation `kind`,
 which the UI uses to label the card. Neither ends the run — a human always gets
 a chance to unblock and resume.
 
@@ -200,16 +203,15 @@ Consequences the prompt (`resources/prompts/review-round.md`) encodes:
 |---|---|---|---|
 | `pr-submitted` | — (start) | submit route/webhook | `{repo, prNumber, prUrl, prKey}` |
 | `review-ready` | `prKey` | **poller** | `{reviewId, reviewState, submittedAt}` |
-| `escalation-answered` | `prKey` | merge-loop answer (`answerEscalation`) | `{answer, escalationId}` |
 | `deps-cleared` | `prKey` | **poller** (merge) | — (all `Depends-on` PRs merged) |
 | `merge-ready` | `prKey` | **poller** (merge) | `{mergeState}` (`ready` \| `conflict` \| `blocked`); when `blocked`, also `{failingChecks, failingChecksList}` for the `senior:fix-ci` branch |
 | `merge-landed` | `prKey` | **poller** (merge) | — (queued PR merged, or merged out-of-band) |
 
-Note `escalation-answered` is now used only by the `merge-loop` process (the
-`convergence-loop` review escalation is a native `userTask` answered through the
-task inbox, not this message). The merge-loop `.bpmn` gives it a distinct message
-**id** (and distinct envelope shape ids) to avoid duplicate-id collisions when the
-manifest deploys both files.
+The `escalation-answered` message was retired (#256): the merge-loop escalation is
+now a native `wait-merge-answer` `userTask`, exactly like the `convergence-loop`
+review escalation (`wait-answer`). Both are answered through the ONE canonical
+`completeUserTask` door and surface in the Tasks inbox — there is no longer a
+merge-only message pathway.
 
 ## 7. Domain model (SQLite — `db/migrations/001_init.sql`) — PROPOSED
 
@@ -287,8 +289,8 @@ The full, authoritative contract is `openapi.yaml` (Swagger UI at
 | `GET` | `/app/api/version` | app + engine version |
 | `POST` | `/app/api/actions/start/convergence-loop` | parse the PR ref → create the aggregate + start the process (the ONE submit door — page + external callers) |
 | `POST` | `/app/api/actions/start/plan-fanout` | parse the issue ref → start a plan fan-out run (the ONE plan door) |
-| `POST` | `/app/api/actions/message` (`escalation-answered`) | answer an open merge-loop escalation → publish `escalation-answered` (the four #156 escalation kinds are native user tasks answered via the task inbox) |
-| `POST` | `/app/api/actions/complete-user-task` | complete an open native user-task escalation from the Tasks page (plan-review / trial-merge / PR `wait-answer`) → `completeEscalationAsHuman` (the same resume path the task inbox uses) |
+| `POST` | `/app/api/actions/message` | publish a BPMN message (optionally correlated) into the engine (generic; every escalation kind is now answered via `/actions/complete-user-task`) |
+| `POST` | `/app/api/actions/complete-user-task` | complete an open native user-task escalation from the Tasks page (plan-review / trial-merge / PR `wait-answer` / PR merge `wait-merge-answer`) → `completeEscalationAsHuman` (the same resume path the task inbox uses) |
 | `GET`/`POST` | `/app/api/hooks/blackboard` | per-plan coordination blackboard (capability-token side-channel) |
 | `GET` | `/app/api/hooks/abandon` | cooperative abandon check (per-PR capability token) |
 
@@ -401,7 +403,7 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
                                                         └─ could not fix ─► escalate ─┐               │             │
                                                                                       ▼               ▼             ▼
                                                              wait: answered ─► (re-arm) ◄──────── (all escalations)
-                                                                   (escalation-answered)
+                                                            (wait-merge-answer userTask)
 ```
 
 - **CI auto-fix** — a `blocked` verdict means a **required check failed**
@@ -438,7 +440,8 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   recorded in the `merges` audit table.
 - **Escalation** — a conflict or a failing gate raises the same
   `pr.persist-escalation` worker as the review stage (status `escalated`), answered
-  via the merge-loop `escalation-answered` message; answering re-arms and retries.
+  via the native `wait-merge-answer` `userTask` (the same `completeUserTask` door as
+  the review escalation, #256); answering re-arms and retries.
 - **Terminal** — `merged` (with `merged_at`), or `converged` when
   `NANO_PR_AUTO_MERGE=0` (review-only), or `abandoned` on cancel.
 

package/app/agentCompletion.ts

@@ -68,6 +68,7 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
   "plan-review-decision",
   "trial-merge-decision",
   "wait-answer", // PR review-loop escalation (convergence-loop.bpmn, U3)
+  "wait-merge-answer", // PR merge-loop escalation (merge-loop.bpmn) — same native user-task path (#256)
 ]);
 
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
@@ -78,6 +79,7 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "plan-review-decision": "plan-review-decision",
   "trial-merge-decision": "trial-merge-decision",
   "wait-answer": "pr-escalation",
+  "wait-merge-answer": "pr-escalation",
 };
 
 interface FormContract {

package/app/agentGuide.ts

@@ -33,7 +33,8 @@ const RAW_GUIDE: string = (() => {
       "- `GET /version` — which code is live.",
       "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, convergeOnly?, maxRounds?, dependsOn? }`).",
       "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue, baseBranch }` or `{ url, baseBranch }`; base is required — a missing `epic/*` base is auto-created, and `confirmDefaultBase`/`allowSharedBase` gate the default-branch and shared-base cases — see ADR 0003).",
-      "- `POST /actions/message` — answer an escalation (`escalation-answered`, correlate by PR key).",
+      "- `POST /actions/complete-user-task` — answer an escalation (`{ userTaskKey, variables }`); the parked user task's key comes from `GET /status`/the Tasks inbox, and the typed variables match its `.form` (e.g. a PR escalation's `{ answer }`).",
+      "- `POST /actions/message` — publish a BPMN message (optionally correlated) into the engine.",
       "",
       "Engine (Camunda-8 v2 REST) base for debugging: `__ENGINE__`.",
       "Source repository: `nanobpm/nano-workforce`.",

package/app/answer-escalation.test.ts

@@ -8,7 +8,7 @@
 // completion and must transition the latest open row to `answered`, recording the submitted answer.
 //
 // It must ALSO move the `pull_requests` row off `status="escalated"` back to `"converging"`, exactly
-// as the merge-loop's `answerEscalation` message path does. Otherwise the PR stays `escalated` (with
+// (the single reconcile step both the review and merge loops run). Otherwise the PR stays `escalated` (with
 // a now-null `openEscalation`) until the re-entered round's `persist-round` runs — an inconsistent
 // `/status` window and a divergence from the merge loop the two paths are meant to share.
 import { test } from "node:test";
@@ -60,7 +60,7 @@ test("retires the latest open escalation to answered with the submitted answer",
   assertEquals(typeof updates[0].patch.answered_at, "string", "answered_at is stamped");
   assertEquals(prUpdates.length, 1, "the PR row is moved off `escalated`");
   assertEquals(prUpdates[0].key, "o/r#1", "the PR keyed by prKey is updated");
-  assertEquals(prUpdates[0].patch.status, "converging", "mirrors answerEscalation: back to converging");
+  assertEquals(prUpdates[0].patch.status, "converging", "answered escalation returns the PR to converging");
   assertEquals(typeof prUpdates[0].patch.updated_at, "string", "updated_at is stamped");
 });
 

package/app/mergeEscalationUserTask.test.ts

@@ -0,0 +1,77 @@
+// Structural + cross-layer regression guard for converging the merge-loop escalation onto the ONE
+// native user-task answer pathway (#256).
+//
+// Before #256 the merge loop parked on a durable `escalation-answered` message catch answered by a
+// bespoke `answerEscalation()` publish — a SECOND answer pathway invisible to the Tasks inbox, so a
+// merge escalation could not be answered from the nwf UI at all. It now parks on a native
+// `wait-merge-answer` userTask (backed by `pr-escalation.form`) followed by the SAME
+// `pr.answer-escalation` reconcile step the review loop's `wait-answer` runs, so both loops answer
+// through the one canonical `completeUserTask` door and surface in the one Tasks inbox.
+//
+// These are pure text assertions over the committed BPMN (no engine), matching the repo's
+// lightweight model-guard style (see mergeRebaseArm.test.ts), plus a drift guard tying the model's
+// user-task element id to the completer's accepted escalation set so the two can't silently diverge.
+
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+import { ESCALATION_TASK_ELEMENTS, validateEscalationVariables } from "./agentCompletion.ts";
+
+const bpmn = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+function hasFlow(source: string, target: string): boolean {
+  const re = new RegExp(
+    `<bpmn:sequenceFlow\\b[^>]*\\bsourceRef="${source}"[^>]*\\btargetRef="${target}"|` +
+      `<bpmn:sequenceFlow\\b[^>]*\\btargetRef="${target}"[^>]*\\bsourceRef="${source}"`,
+  );
+  return re.test(flat);
+}
+
+test("the merge escalation parks on a native wait-merge-answer userTask backed by pr-escalation.form", () => {
+  const task = flat.match(/<bpmn:userTask\b[^>]*\bid="wait-merge-answer"[\s\S]*?<\/bpmn:userTask>/);
+  assert(task, "wait-merge-answer must be a <bpmn:userTask>");
+  assertStringIncludes(task![0], 'formId="pr-escalation"', "it must render the shared pr-escalation form");
+  assertStringIncludes(task![0], "<zeebe:userTask", "it must be a native (Zeebe) user task");
+});
+
+test("the answered task reconciles the escalations row, then re-arms the merge poller", () => {
+  // wait-merge-answer → record-merge-answer (pr.answer-escalation) → arm-merge, mirroring the review
+  // loop's wait-answer → record-answer. Without the reconcile step the escalations row would stay
+  // `open` forever after the task completes (a phantom on /status).
+  const record = flat.match(/<bpmn:serviceTask\b[^>]*\bid="record-merge-answer"[\s\S]*?<\/bpmn:serviceTask>/);
+  assert(record, "record-merge-answer service task must exist");
+  assertStringIncludes(record![0], 'type="pr.answer-escalation"', "it must run the shared reconcile worker");
+  assert(hasFlow("wait-merge-answer", "record-merge-answer"), "wait-merge-answer → record-merge-answer missing");
+  assert(hasFlow("record-merge-answer", "arm-merge"), "record-merge-answer → arm-merge (re-arm) missing");
+});
+
+test("the legacy escalation-answered message pathway is gone", () => {
+  assert(!flat.includes("escalation-answered"), "the escalation-answered message must be removed");
+  assert(!flat.includes("Message_mergeEscAnswered"), "the merge escalation message declaration must be removed");
+  // The answer wait must no longer be a message catch — it is now a user task.
+  assert(
+    !/<bpmn:intermediateCatchEvent\b[^>]*\bid="wait-merge-answer"/.test(flat),
+    "wait-merge-answer must no longer be an intermediateCatchEvent",
+  );
+});
+
+test("drift guard: the model's merge user-task element is one the canonical completer accepts", () => {
+  // The completer refuses any user task outside ESCALATION_TASK_ELEMENTS, so a model that parks on
+  // `wait-merge-answer` while the code doesn't accept it would deploy but never be answerable — the
+  // exact silent-drift failure mode this guard closes.
+  assert(
+    ESCALATION_TASK_ELEMENTS.has("wait-merge-answer"),
+    "ESCALATION_TASK_ELEMENTS must accept wait-merge-answer",
+  );
+  // And it must map to the pr-escalation form contract (answer required) — a missing answer is
+  // rejected, proving the element resolves to the same form the model renders.
+  assert(
+    validateEscalationVariables("wait-merge-answer", {}) !== null,
+    "wait-merge-answer must enforce the pr-escalation form contract (answer required)",
+  );
+  assert(
+    validateEscalationVariables("wait-merge-answer", { answer: "rebased and retried" }) === null,
+    "a valid answer must satisfy the wait-merge-answer form contract",
+  );
+});

package/app/pollUserTasks.test.ts

@@ -114,6 +114,29 @@ test("pollUserTasks: projects feature / plan-review / trial-merge / PR-wait esca
   assertEquals(byKey["ut-pr"].question, "conflicting reviews");
 });
 
+test("pollUserTasks: projects a merge-loop wait-merge-answer escalation into user_tasks as \"PR merge\"", async () => {
+  // During the merge phase a PR's process_key points at its merge-loop instance; the merge escalation
+  // parks on a native `wait-merge-answer` userTask (#256) and writes the SAME `escalations` row the
+  // review loop does, so the inbox surfaces it exactly like a review escalation — just labelled by
+  // stage. This guards the poller accepting the merge element alongside `wait-answer`.
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#31", status: "escalated", process_key: "mp-31", url: "https://github.com/o/r/pull/31" },
+    ],
+    escalations: [{ id: 1, pr_key: "o/r#31", status: "open", question: "not mergeable — resolve the conflict" }],
+  });
+  const engine = fakeEngine({ "mp-31": [{ userTaskKey: "ut-merge", elementId: "wait-merge-answer" }] });
+
+  await pollUserTasks(data, engine);
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["ut-merge"]);
+  assertEquals(byKey["ut-merge"].element_id, "wait-merge-answer");
+  assertEquals(byKey["ut-merge"].kind_label, "PR merge");
+  assertEquals(byKey["ut-merge"].subject_type, "pr");
+  assertEquals(byKey["ut-merge"].question, "not mergeable — resolve the conflict");
+});
+
 test("pollUserTasks: removes a row once its task is no longer open (completed / out-of-band)", async () => {
   const { data, stores } = memData({
     user_tasks: [

package/app/service.ts

@@ -39,6 +39,7 @@ import {
   latestTrialMergeQuestion,
   PLAN_REVIEW_ELEMENT,
   PR_WAIT_ANSWER_ELEMENT,
+  PR_WAIT_MERGE_ANSWER_ELEMENT,
   prEscalations,
   reconcileUserTasks,
   TRIAL_MERGE_ELEMENT,
@@ -578,35 +579,6 @@ export async function startMerge(
   return { prKey: pr.prKey, mergeProcessKey: processInstanceKey };
 }
 
-/** Answer an open escalation → record it and resume the process. */
-export async function answerEscalation(
-  data: DataLayer,
-  engine: EngineClient,
-  prKey: string,
-  answer: string,
-) {
-  const open = (await escs(data).find({ pr_key: prKey, status: "open" })).sort((a, b) => b.id - a.id);
-  if (open.length === 0) return { ok: false, reason: "no open escalation" };
-  const ts = now();
-  await escs(data).update(open[0].id, { answer, status: "answered", answered_at: ts });
-  // `pr.persist-escalation` always INSERTs a new open row, so a retry can leave duplicate open rows
-  // for this PR. Retire any older ones to `stale` so none is left `open` to phantom-surface on
-  // /status (mirrors `submitPr`'s resubmit cleanup and the review loop's `pr.answer-escalation`).
-  for (const dup of open.slice(1)) {
-    await escs(data).update(dup.id, { status: "stale" });
-  }
-  await prs(data).update(prKey, {
-    status: "converging",
-    updated_at: ts,
-  });
-  await engine.publishMessage({
-    name: "escalation-answered",
-    correlationKey: prKey,
-    variables: { answer, escalationId: open[0].id },
-  });
-  return { ok: true, escalationId: open[0].id };
-}
-
 /** A PR currently in flight, as reported by the status endpoint. */
 export interface ActivePr {
   prKey: string;
@@ -632,11 +604,11 @@ export interface ActivePr {
  * without reading the datasource directly. The open-escalation question is derived from the
  * canonical `escalations` audit row — the single source of truth (no denormalised PR-row
  * pointer). A PR reads `status="escalated"` only while a token is parked awaiting a human answer,
- * and the row it raised carries `status="open"` until that answer is recorded — by the review
- * loop's `pr.answer-escalation` step on `wait-answer` completion, or the merge loop's
- * `answerEscalation` message path. Deriving from the row (not a per-loop wait mechanism) surfaces
- * BOTH loops' escalations: the merge loop parks on a message catch with no user task, so a
- * user-task probe would silently hide it. Once answered the row leaves `open`, so `openEscalation`
+ * and the row it raised carries `status="open"` until that answer is recorded — by the
+ * `pr.answer-escalation` step on the `wait-answer` (review loop) or `wait-merge-answer` (merge loop)
+ * user-task completion. Both loops now park on a native user task answered through the one canonical
+ * `completeUserTask` door (#256), so deriving from the row (not a per-loop wait mechanism) surfaces
+ * BOTH loops' escalations uniformly. Once answered the row leaves `open`, so `openEscalation`
  * derives back to null. */
 export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
   const all = await prs(data).all();
@@ -1594,13 +1566,13 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
         continue;
       }
       for (const t of tasks) {
-        if (t.elementId !== PR_WAIT_ANSWER_ELEMENT) continue;
+        if (t.elementId !== PR_WAIT_ANSWER_ELEMENT && t.elementId !== PR_WAIT_MERGE_ANSWER_ELEMENT) continue;
         const question = latestOpenEscalationQuestion(await prEscalations(data).find({ pr_key: pr.pr_key, status: "open" }));
         push(
           buildUserTaskRow(
             {
               userTaskKey: t.userTaskKey,
-              elementId: PR_WAIT_ANSWER_ELEMENT,
+              elementId: t.elementId,
               subjectType: "pr",
               subjectKey: pr.pr_key,
               subjectUrl: pr.url,

package/app/userTasks.ts

@@ -36,6 +36,12 @@ export const TRIAL_MERGE_ELEMENT = "trial-merge-decision";
  *  review loop and is handed to the next round. */
 export const PR_WAIT_ANSWER_ELEMENT = "wait-answer";
 
+/** The PR merge-loop escalation user task (merge-loop.bpmn) — a human answer that resumes the merge
+ *  loop (re-arms the merge poller) when the PR can't be landed (not mergeable / merge blocked). The
+ *  same native user-task path as the review loop's `wait-answer` (#256), answered through the one
+ *  canonical `completeUserTask` door and surfaced in this same Tasks inbox. */
+export const PR_WAIT_MERGE_ANSWER_ELEMENT = "wait-merge-answer";
+
 /** One row per currently-open native user-task escalation, denormalised for the Tasks page. Keyed on
  *  the completable `user_task_key` (a task is open at most once). Present iff the engine reports the
  *  task open; `pollUserTasks` deletes it once the task is gone. */
@@ -63,6 +69,7 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [PLAN_REVIEW_ELEMENT]: "Plan review",
   [TRIAL_MERGE_ELEMENT]: "Trial merge",
   [PR_WAIT_ANSWER_ELEMENT]: "PR review",
+  [PR_WAIT_MERGE_ANSWER_ELEMENT]: "PR merge",
 };
 
 /** The denormalised context the poller has resolved for an open escalation user task. */

package/docs/agent-guide.md

@@ -204,20 +204,23 @@ curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application
   -d '{ "userTaskKey": "<key>", "variables": { "action": "rebase", "notes": "Re-run after the fix." } }'
 ```
 
-**Answer a merge-loop escalation** (the one out-of-scope kind that still uses the
-durable message catch, not a user task). Use the message name `escalation-answered`,
-correlated by the PR key:
+**Answer a PR escalation** (both the review-loop `wait-answer` and the merge-loop
+`wait-merge-answer` — both are now native user tasks answered the same way, #256).
+Use the PR key's parked user task and submit the `pr-escalation` form's `{ answer }`:
 
 ```bash
-curl -sS -X POST __BASE__/actions/message \
+curl -sS -X POST __BASE__/actions/complete-user-task \
   -H 'content-type: application/json' \
   -d '{
-        "name": "escalation-answered",
-        "correlationKey": "owner/repo#123",
+        "userTaskKey": "<key>",
         "variables": { "answer": "Yes — cap the retries at 5 and proceed." }
       }'
 ```
 
+The `userTaskKey` comes from `GET /status` or the Tasks inbox. This is the ONE
+canonical answer door for every escalation kind; the merge loop no longer uses a
+durable `escalation-answered` message catch.
+
 If `NANO_PR_WEBHOOK_SECRET` is set on the deployment, add `-H "x-hook-secret: <secret>"`.
 
 The answer is delivered to the agent as its next-round context (e.g. the `answer`,

package/openapi.yaml

@@ -1182,11 +1182,9 @@ paths:
   /actions/message:
     post:
       operationId: postMessage
-      summary: "Publish a message / answer an escalation. For the merge-loop `escalation-answered`
-        name, runs the merge-loop escalation answer flow; otherwise a plain publishMessage. The
-        epic #156 escalation
-        kinds (task, plan-review, trial-merge, PR review-loop) are native user tasks answered via
-        the task inbox (POST /tasks/api/complete), not this route."
+      summary: "Publish a BPMN message (optionally correlated) into the engine. Every escalation kind
+        (task, plan-review, trial-merge, PR review-loop, PR merge-loop) is a native user task answered
+        via the Tasks inbox / POST /actions/complete-user-task, not this route."
       requestBody:
         required: true
         content:

package/operations/getAgentInstructions.test.ts

@@ -42,7 +42,7 @@ test("the guide covers every capability the endpoint promises", async () => {
   assert(md.includes("start/convergence-loop"), "covers submitting a PR for convergence");
   assert(md.includes("convergeOnly"), "documents review-only vs. merge");
   assert(md.includes("start/plan-fanout"), "covers submitting an epic");
-  assert(md.includes("escalation-answered"), "covers answering escalations");
+  assert(md.includes("complete-user-task"), "covers answering escalations via the native user-task door");
   // …debug the system.
   assert(md.includes("/jobs/search") && md.includes("/incidents/search"), "covers engine REST debugging");
   assert(md.includes("processKey") || md.includes("process_key"), "relates instances to PRs");

package/operations/postMessage.ts

@@ -1,19 +1,14 @@
 // POST /app/api/actions/message → operationId `postMessage` (ADR 0058, base /app/api).
-// Replaces the hand-rolled action that overrode the generic publishMessage action. For the
-// merge-loop `escalation-answered` message we run the merge-loop escalation answer flow; any other
-// message falls back to a plain publishMessage.
+// Replaces the hand-rolled action that overrode the generic publishMessage action: publish an
+// arbitrary BPMN message (optionally correlated) into the engine.
 //
-// The four #156 escalation kinds (task, plan-review, trial-merge, PR review-loop) are now native
-// `userTask`s answered directly through the task inbox (`POST /tasks/api/complete`), so this
-// delegate no longer carries their bespoke `feature-escalation-answered` / `plan-escalation-answered`
-// discriminators. The merge-loop escalation is still a durable message catch (out of scope for
-// #156), so its `escalation-answered` branch is kept.
-//
-// The runtime validates the body against openapi.yaml (`name` is required, so a missing name is a 400
-// for free); this delegate keeps the message-name dispatch — the discriminator + downstream behavior
-// is app logic, not something the JSON schema can express.
+// Every escalation kind is now a native `userTask` answered through the ONE canonical human/agent
+// completer (`completeUserTask` → `completeUserTaskAttributed`) and surfaced in the Tasks inbox —
+// including the merge-loop escalation, which converged from a durable `escalation-answered` message
+// catch onto a native user task (#256). So this delegate no longer carries any bespoke
+// escalation-answer discriminator; it is a thin, generic message publish. The runtime validates the
+// body against openapi.yaml (`name` is required, so a missing name is a 400 for free).
 
-import { answerEscalation } from "../app/service.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("postMessage", async ({ body }, app) => {
@@ -24,17 +19,6 @@ export default defineOperation("postMessage", async ({ body }, app) => {
     return { status: 400, body: { error: "name is required" } };
   }
 
-  if (name === "escalation-answered") {
-    const prKey = String(b.correlationKey ?? "");
-    const answer = String(b.variables?.answer ?? "").trim();
-    if (!prKey) return { status: 400, body: { error: "correlationKey is required" } };
-    if (!answer) return { status: 400, body: { error: "answer is required" } };
-    const r = await answerEscalation(app.data, app.engine, prKey, answer);
-    if (r.ok) app.log.info("merge-loop escalation answered", { name, prKey });
-    else app.log.warn("postMessage: no open merge-loop escalation to answer", { name, prKey });
-    return { status: r.ok ? 200 : 404, body: r };
-  }
-
   await app.engine.publishMessage({
     name,
     correlationKey: b.correlationKey != null ? String(b.correlationKey) : undefined,

package/operations/startAndMessage.test.ts

@@ -216,9 +216,20 @@ test("postMessage → 400 when name is blank", async () => {
   assertEquals(r.body.error, "name is required");
 });
 
-test("postMessage → 400 when escalation-answered lacks a correlationKey", async () => {
-  const res = await postMessage(input({ name: "escalation-answered", variables: { answer: "yes" } }), app);
+test("postMessage publishes any named message generically (no bespoke escalation branch)", async () => {
+  // Every escalation kind is now a native user task answered via /actions/complete-user-task (#256),
+  // so postMessage no longer special-cases `escalation-answered`; it is a thin generic publish. The
+  // former `escalation-answered`-without-correlationKey 400 branch is gone — such a message now just
+  // publishes (uncorrelated) like any other.
+  let published: { name: string; correlationKey?: string; variables?: unknown } | undefined;
+  const pubApp = {
+    log: noopLog(),
+    engine: { publishMessage: (m: any) => ((published = m), Promise.resolve()) },
+  } as any as AppApi;
+  const res = await postMessage(input({ name: "merge-ready", correlationKey: "o/r#1", variables: { x: 1 } }), pubApp);
   const r = res as any;
-  assertEquals(r.status, 400);
-  assertEquals(r.body.error, "correlationKey is required");
+  assertEquals(r.status, 200);
+  assertEquals(r.body.ok, true);
+  assertEquals(published?.name, "merge-ready");
+  assertEquals(published?.correlationKey, "o/r#1");
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.77.0",
+  "version": "0.78.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/tasks.page.json

@@ -235,7 +235,7 @@
       "type": "dataGrid",
       "id": "pr-reviews",
       "props": {
-        "title": "PR review escalations",
+        "title": "PR escalations",
         "data": {
           "kind": "datasource",
           "source": "app",
@@ -244,7 +244,8 @@
             {
               "field": "element_id",
               "in": [
-                "wait-answer"
+                "wait-answer",
+                "wait-merge-answer"
               ]
             }
           ],
@@ -258,6 +259,10 @@
             "field": "subject_key",
             "header": "PR"
           },
+          {
+            "field": "kind_label",
+            "header": "Stage"
+          },
           {
             "field": "subject_url",
             "header": "PR link"
@@ -283,7 +288,25 @@
               "field": "question",
               "label": "Escalation question"
             }
-          ]
+          ],
+          "form": {
+            "showWhenField": "user_task_key",
+            "title": "Answer escalation",
+            "promptField": "question",
+            "inputKey": "answer",
+            "inputLabel": "Your answer",
+            "submitLabel": "Answer & resume",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "successLabel": "Answered — the loop will resume",
+              "body": {
+                "userTaskKey": "{{row.user_task_key}}",
+                "variables": {
+                  "answer": "{{form.answer}}"
+                }
+              }
+            }
+          }
         },
         "refreshMs": 5000
       }

package/resources/processes/merge-loop.bpmn

@@ -23,14 +23,6 @@
       <zeebe:subscription correlationKey="=prKey" />
     </bpmn:extensionElements>
   </bpmn:message>
-  <bpmn:message id="Message_mergeEscAnswered" name="escalation-answered">
-    <bpmn:extensionElements>
-      <zeebe:subscription correlationKey="=prKey" />
-      <zeebe:properties>
-        <zeebe:property name="io.nanobpm.dataEnvelope.in" value="MergeEscalationAnswered" />
-      </zeebe:properties>
-    </bpmn:extensionElements>
-  </bpmn:message>
   <bpmn:process id="merge-loop" name="PR Merge" isExecutable="true">
     <bpmn:extensionElements>
       <nano:shapes>
@@ -87,10 +79,6 @@
           <nano:extend name="prKey" type="string" />
           <nano:extend name="dependsOn" type="string" optional="true" />
         </nano:shape>
-        <nano:shape id="MergeEscalationAnswered" name="escalation-answered message payload">
-          <nano:extend name="answer" type="string" />
-          <nano:extend name="escalationId" type="integer" />
-        </nano:shape>
       </nano:shapes>
     </bpmn:extensionElements>
     <bpmn:startEvent id="MergeStart" name="PR converged">
@@ -206,12 +194,33 @@
       <bpmn:incoming>f_ci_sla</bpmn:incoming>
       <bpmn:outgoing>f_m_escA</bpmn:outgoing>
     </bpmn:serviceTask>
-    <bpmn:intermediateCatchEvent id="wait-merge-answer" name="Wait: escalation answered">
+    <bpmn:userTask id="wait-merge-answer" name="Answer escalation">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="pr-escalation" />
+        <zeebe:userTask />
+        <zeebe:ioMapping>
+          <zeebe:input source="=question" target="question" />
+          <zeebe:input source="=prKey" target="prKey" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
       <bpmn:incoming>f_m_escC</bpmn:incoming>
       <bpmn:incoming>f_m_escA</bpmn:incoming>
+      <bpmn:outgoing>f_m_answerRecord</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:serviceTask id="record-merge-answer" name="Record answer">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.answer-escalation" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrAnswerEscalationIn" />
+        </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:input source="=prKey" target="prKey" />
+          <zeebe:input source="=answer" target="answer" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_m_answerRecord</bpmn:incoming>
       <bpmn:outgoing>f_m_answer</bpmn:outgoing>
-      <bpmn:messageEventDefinition id="med_mergeEscAnswered" messageRef="Message_mergeEscAnswered" />
-    </bpmn:intermediateCatchEvent>
+    </bpmn:serviceTask>
     <bpmn:exclusiveGateway id="gw-ci-fix" name="auto-fix CI?" default="f_ci_giveup">
       <bpmn:incoming>f_m_mCiFix</bpmn:incoming>
       <bpmn:outgoing>f_ci_go</bpmn:outgoing>
@@ -355,7 +364,8 @@
     <bpmn:sequenceFlow id="f_m_done" sourceRef="mark-merged" targetRef="MergeEnd" />
     <bpmn:sequenceFlow id="f_m_escC" sourceRef="merge-esc-conflict" targetRef="wait-merge-answer" />
     <bpmn:sequenceFlow id="f_m_escA" sourceRef="merge-esc-attempt" targetRef="wait-merge-answer" />
-    <bpmn:sequenceFlow id="f_m_answer" sourceRef="wait-merge-answer" targetRef="arm-merge" />
+    <bpmn:sequenceFlow id="f_m_answerRecord" sourceRef="wait-merge-answer" targetRef="record-merge-answer" />
+    <bpmn:sequenceFlow id="f_m_answer" sourceRef="record-merge-answer" targetRef="arm-merge" />
     <bpmn:sequenceFlow id="f_reb_sla" name="agent SLA elapsed" sourceRef="be_rebase_sla" targetRef="merge-esc-conflict" />
     <bpmn:sequenceFlow id="f_ci_sla" name="agent SLA elapsed" sourceRef="be_fixci_sla" targetRef="merge-esc-attempt" />
   </bpmn:process>
@@ -419,9 +429,9 @@
         <dc:Bounds x="1638" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_MergeEnd" bpmnElement="MergeEnd">
-        <dc:Bounds x="1838" y="102" width="36" height="36" />
+        <dc:Bounds x="1870" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1831" y="143" width="50" height="14" />
+          <dc:Bounds x="1863" y="143" width="50" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_merge-esc-conflict" bpmnElement="merge-esc-conflict">
@@ -431,10 +441,10 @@
         <dc:Bounds x="1438" y="1040" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_wait-merge-answer" bpmnElement="wait-merge-answer">
-        <dc:Bounds x="1670" y="1062" width="36" height="36" />
-        <bpmndi:BPMNLabel>
-          <dc:Bounds x="1731" y="1103" width="74" height="42" />
-        </bpmndi:BPMNLabel>
+        <dc:Bounds x="1638" y="1040" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_record-merge-answer" bpmnElement="record-merge-answer">
+        <dc:Bounds x="1838" y="1040" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-ci-fix" bpmnElement="gw-ci-fix" isMarkerVisible="true">
         <dc:Bounds x="863" y="1535" width="50" height="50" />
@@ -517,7 +527,7 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_done" bpmnElement="f_m_done">
         <di:waypoint x="1738" y="120" />
-        <di:waypoint x="1838" y="120" />
+        <di:waypoint x="1870" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_giveup" bpmnElement="f_ci_giveup">
         <di:waypoint x="913" y="1560" />
@@ -568,11 +578,15 @@
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escC" bpmnElement="f_m_escC">
         <di:waypoint x="1338" y="1560" />
         <di:waypoint x="1688" y="1560" />
-        <di:waypoint x="1688" y="1098" />
+        <di:waypoint x="1688" y="1120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_answerRecord" bpmnElement="f_m_answerRecord">
+        <di:waypoint x="1738" y="1080" />
+        <di:waypoint x="1838" y="1080" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_answer" bpmnElement="f_m_answer">
-        <di:waypoint x="1688" y="1098" />
-        <di:waypoint x="1688" y="1140" />
+        <di:waypoint x="1888" y="1120" />
+        <di:waypoint x="1888" y="1140" />
         <di:waypoint x="402" y="1140" />
         <di:waypoint x="402" y="160" />
       </bpmndi:BPMNEdge>
@@ -612,13 +626,13 @@
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_go" bpmnElement="f_ci_go">
         <di:waypoint x="888" y="1585" />
         <di:waypoint x="888" y="1605" />
-        <di:waypoint x="1726" y="1605" />
-        <di:waypoint x="1726" y="555" />
+        <di:waypoint x="1958" y="1605" />
+        <di:waypoint x="1958" y="555" />
         <di:waypoint x="1018" y="555" />
         <di:waypoint x="1018" y="580" />
         <di:waypoint x="1038" y="580" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1731" y="1046" width="49" height="28" />
+          <dc:Bounds x="1963" y="1066" width="49" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_blocked" bpmnElement="f_ci_blocked">
@@ -685,13 +699,13 @@
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_gBlocked" bpmnElement="f_m_gBlocked">
         <di:waypoint x="1088" y="95" />
         <di:waypoint x="1088" y="75" />
-        <di:waypoint x="1894" y="75" />
-        <di:waypoint x="1894" y="820" />
+        <di:waypoint x="1926" y="75" />
+        <di:waypoint x="1926" y="820" />
         <di:waypoint x="1418" y="820" />
         <di:waypoint x="1418" y="1060" />
         <di:waypoint x="1438" y="1060" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1899" y="441" width="53" height="14" />
+          <dc:Bounds x="1931" y="441" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_done" bpmnElement="f_ci_done">
@@ -704,7 +718,7 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escA" bpmnElement="f_m_escA">
         <di:waypoint x="1538" y="1080" />
-        <di:waypoint x="1670" y="1080" />
+        <di:waypoint x="1638" y="1080" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_sla" bpmnElement="f_reb_sla">
         <di:waypoint x="1088" y="978" />

package/workers/answer-escalation/worker.ts

@@ -1,6 +1,7 @@
-// pr.answer-escalation — retires the review-loop escalation the operator just answered.
-//
-// The review-loop escalation is a native `wait-answer` userTask (backed by `pr-escalation.form`).
+// pr.answer-escalation — retires the escalation the operator just answered, for BOTH the review loop
+// (`wait-answer`, convergence-loop.bpmn) and the merge loop (`wait-merge-answer`, merge-loop.bpmn).
+// Both loops now park on a native `wait-*` userTask (backed by `pr-escalation.form`) and run this same
+// reconcile step on completion (#256) — there is one answer path, not two.
 // Completing that task resumes the token, but the engine folds the completed instance's variables
 // away — so without this step the durable `escalations` audit row raised by `pr.persist-escalation`
 // would stay `status="open"` forever, its `answer`/`answered_at` never recorded. That both loses the
@@ -8,9 +9,8 @@
 // single source of truth, ADR "derivation over duplication") would keep surfacing a phantom open
 // escalation on `/status` after it was answered.
 //
-// This mirrors the merge-loop's message-catch answer path (`answerEscalation` in app/service.ts):
-// both answer the newest still-open `escalations` row, mark any duplicate open rows `stale` (a
-// retry of `pr.persist-escalation` can leave more than one open), AND move the `pull_requests` row
+// It answers the newest still-open `escalations` row, marks any duplicate open rows `stale` (a
+// retry of `pr.persist-escalation` can leave more than one open), AND moves the `pull_requests` row
 // off `status="escalated"` back to `"converging"`, so an answered escalation is never left dangling
 // and `/status` never shows an escalated PR with a null question or a phantom open row. The token
 // resume itself is owned by the engine (userTask completion), so this worker only reconciles the
@@ -28,7 +28,7 @@ interface Escalation extends Record<string, unknown> {
 }
 
 // The PR-row fields this worker reconciles when an escalation is answered. Only `status`/`updated_at`
-// are written (mirroring `answerEscalation`); the rest of the row is untouched.
+// are written; the rest of the row is untouched.
 interface PullRequest extends Record<string, unknown> {
   pr_key: string;
   status: string;
@@ -51,7 +51,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
   // open row, so a retry/duplicate activation can leave more than one open — answering only the
   // newest would leave an older duplicate `open`, a phantom `activePrs` keeps deriving while the PR
   // is still `escalated`. Answer the newest (it carries the operator's reply) and mark any remaining
-  // open rows `stale`, mirroring `answerEscalation` and `submitPr`'s resubmit cleanup.
+  // open rows `stale`, mirroring `submitPr`'s resubmit cleanup.
   const open = (await escs.find({ pr_key: prKey, status: "open" })).sort((a, b) => b.id - a.id);
   if (open.length > 0) {
     const ts = new Date().toISOString();
@@ -63,7 +63,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
     for (const dup of open.slice(1)) {
       await escs.update(dup.id, { status: "stale" });
     }
-    // Mirror the merge loop's `answerEscalation`: move the PR off `status="escalated"` back to
+    // Move the PR off `status="escalated"` back to
     // `"converging"` now that the question is answered. Without this the row stays `escalated` (with
     // a now-null derived `openEscalation`) until the re-entered round's `persist-round` runs — a
     // `/status` inconsistency and a divergence from the merge path both loops are meant to share.

package/app/answerEscalation.test.ts

@@ -1,67 +0,0 @@
-// Red/green regression for answerEscalation (merge-loop message path) — Copilot review of PR #180.
-//
-// `pr.persist-escalation` always INSERTs a fresh `escalations` row with `status="open"`, so a
-// retry/duplicate activation can leave more than one open row for the same PR. answerEscalation
-// only closed the NEWEST open row, leaving older duplicates `open` — a phantom that keeps
-// `activePrs` deriving an open escalation while the PR is still `escalated`. Every open row for the
-// PR must leave `open` in this completion (newest answered, the rest marked `stale`), exactly as
-// `submitPr`'s resubmit cleanup already does. Mirrors the review loop's `pr.answer-escalation`.
-import { test } from "node:test";
-import { assertEquals } from "#test-assert";
-import type { DataLayer, EngineClient } from "@nanobpm/urban";
-import { answerEscalation } from "./service.ts";
-
-function memData(escalations: any[], prs: any[]): DataLayer {
-  const table = (name: string, key: string) => ({
-    async find(where: Record<string, unknown>) {
-      const src = name === "escalations" ? escalations : prs;
-      return src.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-    },
-    async update(k: unknown, patch: Record<string, unknown>) {
-      const src = name === "escalations" ? escalations : prs;
-      const r = src.find((x) => x[key] === k);
-      if (r) Object.assign(r, patch);
-      return r;
-    },
-  });
-  return { table } as any as DataLayer;
-}
-
-function fakeEngine(published: any[]): EngineClient {
-  return {
-    async publishMessage(m: any) {
-      published.push(m);
-    },
-  } as any as EngineClient;
-}
-
-test("answerEscalation answers the newest open row and marks duplicate open rows stale", async () => {
-  const escalations = [
-    { id: 3, pr_key: "o/r#1", status: "open", answer: null, answered_at: null },
-    { id: 7, pr_key: "o/r#1", status: "open", answer: null, answered_at: null },
-    { id: 9, pr_key: "o/r#2", status: "open", answer: null, answered_at: null },
-  ];
-  const prs = [{ pr_key: "o/r#1", status: "escalated", updated_at: "t0" }];
-  const published: any[] = [];
-  const res = await answerEscalation(memData(escalations, prs), fakeEngine(published), "o/r#1", "Cap at 5.");
-
-  assertEquals(res, { ok: true, escalationId: 7 }, "the newest open row is the one answered");
-  const answered = escalations.find((e) => e.id === 7);
-  const stale = escalations.find((e) => e.id === 3);
-  const other = escalations.find((e) => e.id === 9);
-  assertEquals(answered?.status, "answered");
-  assertEquals(answered?.answer, "Cap at 5.");
-  assertEquals(stale?.status, "stale", "the older duplicate open row is retired to stale");
-  assertEquals(other?.status, "open", "the other PR's open row is untouched");
-  assertEquals(prs[0].status, "converging", "the PR row is moved off escalated");
-  assertEquals(published.length, 1, "the resume message is published once");
-  assertEquals(published[0].variables.escalationId, 7);
-});
-
-test("answerEscalation is a no-op when no row is open", async () => {
-  const escalations = [{ id: 7, pr_key: "o/r#1", status: "answered", answer: "x", answered_at: "t" }];
-  const published: any[] = [];
-  const res = await answerEscalation(memData(escalations, []), fakeEngine(published), "o/r#1", "again");
-  assertEquals(res, { ok: false, reason: "no open escalation" });
-  assertEquals(published.length, 0);
-});