@nanobpm/nano-workforce 0.77.0 → 0.79.0

package/app/agentic/transcript-fork.ts

@@ -0,0 +1,151 @@
+// nano-workforce — replay-by-reseed / fork of a transcript log (ADR 0056, #251).
+//
+// The H3 read path (#222) can RESUME the same stream from an offset (reattach parity), but it cannot
+// FORK: seed a NEW stream from an existing log so an exited agent's session can be branched or re-run
+// from a chosen point ("what-if" a different continuation). dsh gets this for free because a session IS
+// its append-only log, so forking is just re-seeding a new session from an existing log up to offset N.
+// This module gives the transcript store the same capability WITHOUT touching the store package: it
+// reads the source log and re-records it into a fresh stream through the store's own idempotent,
+// offset-keyed {@link TranscriptStore.record} — so the fork is itself append-only and offset-parity
+// with its source, and replays through the SAME resume-from-offset read path a native stream uses.
+//
+// Invariants preserved (ADR 0056): app-tier only, append-only (we only ever `record`, never mutate),
+// advisory (a fork is a new advisory transcript — it gates no BPMN flow), and offset/resume wire-shape
+// parity (the fork keeps the source offsets, so a reattach behaves identically on the branch).
+
+import type { TranscriptChunk, TranscriptLifecycle, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+
+/** Raised when a fork/reseed cannot proceed — the source is missing, or the target already exists. */
+export class TranscriptForkError extends Error {
+  readonly source: string;
+  readonly target: string;
+  constructor(source: string, target: string, message: string) {
+    super(message);
+    this.name = "TranscriptForkError";
+    this.source = source;
+    this.target = target;
+  }
+}
+
+/** Options controlling how a source log is reseeded into a new stream. */
+export interface ForkTranscriptOptions {
+  /**
+   * Seed only chunks with `offset <= throughOffset` (inclusive) — the point the branch diverges from.
+   * Omit to fork the WHOLE source log (every retained chunk). A `throughOffset` below the source's
+   * oldest retained offset yields an empty fork (a valid, if trivial, branch point).
+   */
+  readonly throughOffset?: number;
+  /**
+   * The forked stream's retention lifecycle. Defaults to `ephemeral` — a fork is a captured branch,
+   * retained-whole then swept like any completed session, not a growing live stream.
+   */
+  readonly lifecycle?: TranscriptLifecycle;
+  /**
+   * Allow reseeding into a target that already exists. Off by default: forking onto a populated stream
+   * would interleave two logs' bytes and defeat offset-parity, so we refuse rather than clobber. When
+   * on, seeding is still idempotent (offset-keyed), so re-running the SAME fork is a safe no-op — but
+   * the existing target must already hold exactly this seed prefix (same offsets, same chunk bytes,
+   * same lifecycle); a target that diverges from the prefix throws rather than silently interleaving.
+   */
+  readonly allowExisting?: boolean;
+}
+
+/** The outcome of a {@link forkTranscript}: the new stream, how many chunks it seeded, and its window. */
+export interface ForkResult {
+  /** The forked stream id (the `target` argument). */
+  readonly stream: string;
+  /** The source stream the fork was seeded from. */
+  readonly source: string;
+  /** Number of chunks newly persisted into the fork. */
+  readonly seeded: number;
+  /** The highest source offset included in the fork (undefined when the fork is empty). */
+  readonly throughOffset?: number;
+  /** The forked stream's metadata after seeding. */
+  readonly meta: TranscriptStream;
+}
+
+/**
+ * Fork a transcript: seed a NEW stream (`target`) from an existing log (`source`) up to a chosen offset,
+ * so an exited session can be branched and replayed independently.
+ *
+ * The fork keeps the SOURCE offsets (offset-parity), so it resumes through the identical
+ * resume-from-offset read path a native stream uses. It reads the source's retained window
+ * (`store.read`), takes the prefix at or below `throughOffset` (default: the whole log), and re-records
+ * it into `target` via the store's idempotent offset-keyed `record` — so the operation is append-only
+ * and safe to re-run. The branch is fully independent of its source thereafter: appending to either
+ * stream never affects the other.
+ *
+ * Throws {@link TranscriptForkError} when the source has no transcript, when the target already
+ * exists and `allowExisting` is not set, or when `allowExisting` is set but the existing target does
+ * not already match the reseed prefix exactly (divergent chunk bytes/offsets or a different lifecycle).
+ */
+export function forkTranscript(
+  store: TranscriptStore,
+  source: string,
+  target: string,
+  options: ForkTranscriptOptions = {},
+): ForkResult {
+  if (source === target) {
+    throw new TranscriptForkError(source, target, "cannot fork a stream onto itself");
+  }
+  if (store.get(source) === undefined) {
+    throw new TranscriptForkError(source, target, `source stream "${source}" has no transcript to fork`);
+  }
+  const existing = store.get(target);
+  if (existing !== undefined && !options.allowExisting) {
+    throw new TranscriptForkError(source, target, `target stream "${target}" already exists (pass allowExisting to reseed it)`);
+  }
+
+  const lifecycle: TranscriptLifecycle = options.lifecycle ?? "ephemeral";
+  const through = options.throughOffset;
+  const chunks: TranscriptChunk[] = store
+    .read(source)
+    .filter((c) => through === undefined || c.offset <= through);
+
+  // Reseeding onto an EXISTING target (allowExisting) is only safe when that target already holds
+  // exactly the prefix we are about to seed. `record()` is offset-keyed and idempotent, so it silently
+  // no-ops any offset already present — if the existing chunk at that offset differs (or the target
+  // carries offsets outside this prefix, or a different lifecycle), the reseed would leave a stream
+  // that is a MIXTURE of the prior data and the seed, breaking the documented offset-parity invariant.
+  // Validate the overlap before writing and refuse rather than clobber/interleave.
+  if (existing !== undefined) {
+    if (existing.lifecycle !== lifecycle) {
+      throw new TranscriptForkError(
+        source,
+        target,
+        `target stream "${target}" already exists with lifecycle "${existing.lifecycle}", cannot reseed as "${lifecycle}"`,
+      );
+    }
+    const seedByOffset = new Map(chunks.map((c) => [c.offset, c.chunk]));
+    for (const c of store.read(target)) {
+      const expected = seedByOffset.get(c.offset);
+      if (expected === undefined || expected !== c.chunk) {
+        throw new TranscriptForkError(
+          source,
+          target,
+          `target stream "${target}" already contains data that does not match the reseed prefix at offset ${c.offset}; refusing to interleave`,
+        );
+      }
+    }
+  }
+
+  // Open the fork explicitly so an empty fork (throughOffset predating the log) is still a real,
+  // listed stream under its own lifecycle rather than a phantom — mirrors the store's open-then-record.
+  store.open(target, lifecycle);
+  const seeded = chunks.length > 0 ? store.record(target, chunks, lifecycle) : 0;
+
+  const meta = store.get(target);
+  if (meta === undefined) {
+    // Defensive: open() above guarantees a row, so this only fires on a store contract breach.
+    throw new TranscriptForkError(source, target, `fork of "${source}" into "${target}" did not persist a stream`);
+  }
+
+  const result: ForkResult = {
+    stream: target,
+    source,
+    seeded,
+    meta,
+  };
+  const last = chunks.at(-1);
+  return last !== undefined ? { ...result, throughOffset: last.offset } : result;
+}

package/app/agentic/transcript-read.ts

@@ -17,11 +17,12 @@
 import type { TranscriptChunk, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
 import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
+import { utf8ByteLength } from "./transcript-events.ts";
 
 /** Total captured bytes across a set of retained chunks (UTF-8, the on-the-wire terminal encoding). */
 export function byteLengthOf(chunks: readonly TranscriptChunk[]): number {
   let total = 0;
-  for (const c of chunks) total += Buffer.byteLength(c.chunk, "utf8");
+  for (const c of chunks) total += utf8ByteLength(c.chunk);
   return total;
 }
 

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.79.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
       }