@nanobpm/nano-workforce 0.129.0 → 0.129.1

package/.github/workflows/pr-title-lint.yml

@@ -1,9 +1,11 @@
 name: PR title lint
 
 # Squash-merge uses the PR title as the commit subject on `main`, and
-# semantic-release (Angular preset) only cuts a release for `feat:`/`fix:`/`perf:`.
-# A non-conventional title therefore lands on `main` and is silently skipped by
-# the release job — so gate the title against the Conventional Commits grammar.
+# semantic-release (conventionalcommits preset) cuts a release for
+# `feat:`/`fix:`/`perf:`/`refactor:`/`build:`/`revert:`/`docs:` (see
+# `.releaserc.json` releaseRules). A non-conventional title therefore lands on
+# `main` and is silently skipped by the release job — so gate the title against
+# the Conventional Commits grammar.
 on:
   pull_request:
     types: [opened, edited, synchronize, reopened]

package/.releaserc.json

@@ -1,8 +1,42 @@
 {
   "branches": ["main"],
   "plugins": [
-    "@semantic-release/commit-analyzer",
-    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          { "type": "feat", "release": "minor" },
+          { "type": "fix", "release": "patch" },
+          { "type": "perf", "release": "patch" },
+          { "type": "refactor", "release": "patch" },
+          { "type": "build", "release": "patch" },
+          { "type": "revert", "release": "patch" },
+          { "type": "docs", "release": "patch" }
+        ]
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "conventionalcommits",
+        "presetConfig": {
+          "types": [
+            { "type": "feat", "section": "Features" },
+            { "type": "fix", "section": "Bug Fixes" },
+            { "type": "perf", "section": "Performance Improvements" },
+            { "type": "refactor", "section": "Code Refactoring" },
+            { "type": "build", "section": "Build System" },
+            { "type": "revert", "section": "Reverts" },
+            { "type": "docs", "section": "Documentation" },
+            { "type": "test", "hidden": true },
+            { "type": "ci", "hidden": true },
+            { "type": "chore", "hidden": true },
+            { "type": "style", "hidden": true }
+          ]
+        }
+      }
+    ],
     "@semantic-release/changelog",
     "@semantic-release/npm",
     "@semantic-release/github",

package/AGENTS.md

@@ -353,16 +353,20 @@ agents:
 - **DCO sign-off is enforced.** Every commit needs a `Signed-off-by` trailer —
   use `git commit -s` (or `git rebase --signoff`). A missing sign-off fails the
   DCO check.
-- **Conventional Commits.** `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`,
-  `test:`, imperative mood. Review-comment fix-ups are `chore:`, not `fix:`.
+- **Conventional Commits.** `feat:`, `fix:`, `perf:`, `refactor:`, `build:`,
+  `revert:`, `docs:`, `chore:`, `ci:`, `test:`, `style:`, imperative mood — see the
+  next bullet for which of these trigger a release. Review-comment fix-ups are
+  `chore:`, not `fix:`.
 - **PR titles must be Conventional too — they become the release trigger.** PRs
   land on `main` via **squash merge**, so the **PR title is the commit subject**
-  semantic-release analyses. Only `feat:` (minor) and `fix:`/`perf:` (patch) cut a
-  release; any other type — or a non-conventional title like `Redesign …` or
-  `Foundation: …` — lands on `main` and is **silently skipped** by the release job
+  semantic-release analyses. `feat:` cuts a **minor**; `fix:`, `perf:`,
+  `refactor:`, `build:`, `revert:`, and `docs:` cut a **patch** (see
+  `.releaserc.json` `releaseRules`); a `BREAKING CHANGE:` footer cuts a **major**.
+  Only `chore:`, `ci:`, `test:`, and `style:` are **no-release** — a PR titled
+  with one of those lands on `main` and is **silently skipped** by the release job
   (no version, no changelog, no deploy). A user-facing feature **must** be titled
   `feat:`. The `PR title lint` workflow (`.github/workflows/pr-title-lint.yml`)
-  enforces this; if a non-conventional title ever slips through, push one empty
+  enforces this; if a non-releasing title ever slips through, push one empty
   releasable commit (`git commit --allow-empty -s -m "feat(scope): …"`) to release
   the accumulated changes.
 - **Feature work in a worktree** off `origin/main`, one branch per change; open a

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.129.1](https://github.com/nanobpm/nano-workforce/compare/v0.129.0...v0.129.1) (2026-08-23)
+
+### Code Refactoring
+
+* **merge-loop:** sub-process topology + behavioural guards ([#466](https://github.com/nanobpm/nano-workforce/issues/466)) ([#490](https://github.com/nanobpm/nano-workforce/issues/490)) ([ac6f130](https://github.com/nanobpm/nano-workforce/commit/ac6f130d19e545c4d3da23d738c30c1cb6f2b981)), closes [Magikcraft/nano-bpm#971](https://github.com/Magikcraft/nano-bpm/issues/971)
+
 # [0.129.0](https://github.com/nanobpm/nano-workforce/compare/v0.128.0...v0.129.0) (2026-08-23)
 
 

package/app/mergeEscalationUserTask.test.ts

@@ -1,71 +1,37 @@
-// Structural + cross-layer regression guard for converging the merge-loop escalation onto the ONE
-// native user-task answer pathway (#256).
+// Cross-layer drift guard: the merge-loop escalation user task the model parks on must be one the
+// canonical completer (`agentCompletion.ts`) actually accepts and validates (#256, #466).
 //
-// 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.
+// The merge escalation converges on ONE native `wait-merge-answer` userTask (backed by the shared
+// `pr-escalation` form) so it is answerable from the one Tasks inbox. The *behavioural* invariants —
+// that the loop parks on that task, that answering it reconciles the escalations row and re-arms the
+// poller — are exercised end-to-end by the WASM engine in `mergeLoopBehaviour.test.ts`. But that
+// engine harness completes the task through the engine, NOT through nwf's application-level
+// completer, so it cannot catch the specific silent-drift failure this guard closes: the model
+// deploys and parks on `wait-merge-answer`, yet `agentCompletion.ts` refuses to drive it because the
+// id fell out of `ESCALATION_TASK_ELEMENTS` (or its form contract drifted) — a task no worker will
+// ever answer. This guard ties the model's user-task id to the completer's accepted set + form
+// contract so the two layers cannot diverge unnoticed.
 
 import { test } from "node:test";
-import { assert, assertStringIncludes } from "#test-assert";
+import { assert } 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");
-});
+const flat = readFileSync("resources/processes/merge-loop.bpmn", "utf8").replace(/\s+/g, " ");
 
-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.
+test("drift guard: the model's merge user-task element is one the canonical completer accepts", () => {
+  // (1) The model actually parks on `wait-merge-answer` as a native user task...
   assert(
-    !/<bpmn:intermediateCatchEvent\b[^>]*\bid="wait-merge-answer"/.test(flat),
-    "wait-merge-answer must no longer be an intermediateCatchEvent",
+    /<bpmn:userTask\b[^>]*\bid="wait-merge-answer"/.test(flat),
+    "the model must park the merge escalation on a userTask id='wait-merge-answer'",
   );
-});
-
-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.
+  // (2) ...and the completer accepts that exact id (else it deploys but is never answerable)...
   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.
+  // (3) ...resolving to the pr-escalation form contract (a missing answer is rejected; a present
+  // one accepted), proving the element maps 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)",

package/app/mergeLoopBehaviour.test.ts

@@ -0,0 +1,446 @@
+// Behavioural coverage for the sub-process merge-loop (issue #466).
+//
+// The merge-loop was refactored from a flat state machine into sub-processes
+// (`SP_cifix`, `SP_rebase`) whose outcomes are propagated to the top level via
+// end-event `ciOutcome`/`rebaseOutcome` output mappings and re-discriminated by
+// `gw-ci-outcome`/`gw-rebase-outcome`. The previous merge guards were *structural
+// text assertions* over the flat topology; they broke by construction under any
+// re-shaping and re-encoded the model's shape rather than its behaviour.
+//
+// Per direction (issue #466) these are replaced with **behavioural** tests that
+// deploy the committed model into the real WASM engine (`@nanobpm/urban-testkit`)
+// and drive tokens through it, asserting the observable invariant — activated
+// jobs, taken outcomes, terminal state, escalations, budget counters — so they
+// protect what the loop *does*, not how it is drawn. The invariants preserved
+// here are exactly those the retired guards protected:
+//   - mergeRetryArm (#334): transient-retry arm re-arms within budget, escalates
+//     when exhausted, advances the attempt counter only on a retry, no agent.
+//   - mergeCiReattempt (#134): fix-ci `reattempt`/no-verdict re-arms (never pages
+//     a human); blocked reconciles once from ground truth before escalating.
+//   - mergeRebaseArm: conflict → bounded rebase agent → re-arm / escalate /
+//     reconcile / wait-on-PR.
+//   - mergeEscalationQuestion (#329/#454): the four blocked/SLA triggers and the
+//     draft verdict each produce a distinct, human-actionable question; a
+//     persist-escalation `escalated:false` re-enters the poller instead of
+//     parking a dead user task.
+//   - mergeEscalationUserTask (#256): escalation parks on the native
+//     `wait-merge-answer` user task and the answer reconciles then re-arms.
+// Plus the terminate semantics the refactor had to preserve: `MergeAbandoned`
+// terminates the whole instance (it stays at the root, not inside a sub-process).
+import { after, test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+import {
+  assertThatInstance,
+  assertThatUserTask,
+  byProcessId,
+  createWasmEngineClient,
+  type WasmEngineClient,
+} from "@nanobpm/urban-testkit";
+
+const MODEL = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
+
+const AGENT_SLA_MS = 30 * 60 * 1000; // matches the PT30M we start instances with
+
+type Output = Record<string, unknown>;
+type Responder = Output | Output[] | ((job: { variables: Record<string, unknown> }) => Output);
+
+const ALL_JOB_TYPES = [
+  "pr.arm-merge",
+  "pr.merge",
+  "pr.mark-merged",
+  "senior:fix-ci",
+  "senior:rebase",
+  "pr.persist-escalation",
+  "pr.answer-escalation",
+  "pr.record-dependency",
+] as const;
+
+const DEFAULT_RESPONSES: Record<string, Responder> = {
+  "pr.arm-merge": {},
+  "pr.mark-merged": {},
+  "pr.record-dependency": {},
+  "pr.answer-escalation": {},
+  "pr.persist-escalation": { escalated: true },
+};
+
+// Every FEEL expression in the model references these; start them defined (null,
+// or a typed zero where the model compares/arithmetics the value, e.g.
+// `failingChecks > 0`) so a missing-variable access can never raise a spurious
+// incident in a test.
+const DEFAULT_VARS: Record<string, unknown> = {
+  prKey: "pr-1",
+  repo: "acme/app",
+  prNumber: 1,
+  prUrl: "https://example.test/pr/1",
+  ciFixMax: 3,
+  rebaseMax: 3,
+  mergeRetryMax: 3,
+  ciFixRound: 0,
+  rebaseRound: 0,
+  mergeRetryRound: 0,
+  agentSlaTimeout: "PT30M",
+  abandonBrief: null,
+  failingChecksList: null,
+  status: null,
+  mergeState: null,
+  mergeStatus: null,
+  ciBlockedReconciled: null,
+  failingChecks: 0,
+};
+
+/**
+ * Deploy the committed merge-loop and start one instance, wired to a per-job-type
+ * responder. A responder may be a fixed output, a queue consumed per activation,
+ * or a function of the job. A job type mapped to `null` registers **no** worker,
+ * so its token parks on the task — used to let an agent SLA boundary fire.
+ */
+async function startMergeLoop(opts: {
+  responses?: Record<string, Responder | null>;
+  vars?: Record<string, unknown>;
+} = {}): Promise<WasmEngineClient> {
+  const engine = await createWasmEngineClient();
+  await engine.deployResources([{ name: "merge-loop.bpmn", content: MODEL, contentType: "text/xml" }]);
+  const responses: Record<string, Responder | null> = { ...DEFAULT_RESPONSES, ...(opts.responses ?? {}) };
+  for (const jobType of ALL_JOB_TYPES) {
+    const responder = jobType in responses ? responses[jobType] : undefined;
+    if (responder === null) continue; // park the token (e.g. to let the SLA timer fire)
+    const queue = Array.isArray(responder) ? [...responder] : null;
+    await engine.registerWorker(jobType, (job) => {
+      // The escalation `question`/`status` are job-LOCAL input mappings on
+      // `merge-esc-*` (fed to `pr.persist-escalation`), so they never surface as
+      // instance variables — capture them off the job the worker sees instead.
+      if (jobType === "pr.persist-escalation") {
+        lastEscalationByEngine.set(engine, (job as { variables?: Record<string, unknown> }).variables ?? {});
+      }
+      if (queue) return queue.length > 1 ? queue.shift()! : queue[0] ?? {};
+      if (typeof responder === "function") return responder(job as { variables: Record<string, unknown> });
+      return (responder as Output | undefined) ?? {};
+    });
+  }
+  await engine.createInstance({
+    processDefinitionId: "merge-loop",
+    awaitCompletion: false,
+    variables: { ...DEFAULT_VARS, ...(opts.vars ?? {}) },
+  });
+  return engine;
+}
+
+// Positive checks use the engine-testkit `assertThat*` DSL below. The DSL has no
+// *negative* element matcher ("element X did NOT complete") and no *substring*
+// variable matcher (`hasVariable` is deep-equal), so the two readers below cover
+// exactly those gaps. They read via the **same canonical snapshot accessors the
+// DSL uses internally** (`instance.js`): completions from the snapshot-global
+// `elementStats` (`{ elementId, completed }`) and live vars from
+// `instances[].variables`. Sound because every test runs one isolated instance
+// per engine — the single-instance precondition the DSL's own aggregate read
+// relies on.
+
+/** Element ids completed by the single instance — mirrors the DSL's `completedElementIds`. */
+function completedElementIds(engine: WasmEngineClient): Set<string> {
+  const snap = engine.snapshot() as { elementStats?: { elementId: string; completed: number }[] };
+  return new Set((snap.elementStats ?? []).filter((s) => s.completed > 0).map((s) => s.elementId));
+}
+
+/** The single instance's live variables — mirrors the DSL's `variablesOf`. */
+function instanceVars(engine: WasmEngineClient): Record<string, unknown> {
+  const snap = engine.snapshot() as { instances?: { variables?: Record<string, unknown> }[] };
+  return snap.instances?.[0]?.variables ?? {};
+}
+
+/**
+ * The variables the `pr.persist-escalation` worker was last activated with, captured
+ * in `startMergeLoop`. The escalation `question`/`status` are job-local `zeebe:input`
+ * mappings on `merge-esc-*`, so they are only observable on the persist-escalation job
+ * — not as instance variables — this is the canonical read for the escalation payload.
+ */
+const lastEscalationByEngine = new WeakMap<WasmEngineClient, Record<string, unknown>>();
+function escalation(engine: WasmEngineClient): Record<string, unknown> {
+  return lastEscalationByEngine.get(engine) ?? {};
+}
+
+const engines: WasmEngineClient[] = [];
+
+/**
+ * urban-testkit's `assertThat*` DSL reads through a booted-app port: instance
+ * matchers use `app.snapshot()`, user-task matchers use
+ * `app.engine.{search,open}UserTasks`. These tests drive the WASM engine
+ * directly (no full app boot), so expose the client as its own read-model app:
+ * `snapshot()` is native, and `.engine` self-references so the task reads land
+ * on the same client.
+ */
+function asReadModelApp(engine: WasmEngineClient): WasmEngineClient {
+  (engine as unknown as { engine: WasmEngineClient }).engine = engine;
+  return engine;
+}
+
+async function boot(opts?: Parameters<typeof startMergeLoop>[0]): Promise<WasmEngineClient> {
+  const engine = asReadModelApp(await startMergeLoop(opts));
+  engines.push(engine);
+  return engine;
+}
+
+/** The key of the single open `wait-merge-answer` task, via the typed read model. */
+async function mergeAnswerTaskKey(engine: WasmEngineClient): Promise<string> {
+  const tasks = await engine.searchUserTasks({});
+  const row = tasks.find((t) => t.elementId === "wait-merge-answer");
+  assert(row, "expected an open wait-merge-answer user task");
+  return row.userTaskKey;
+}
+after(async () => {
+  await Promise.all(engines.map((e) => e.close()));
+});
+
+// ---------------------------------------------------------------------------
+// Happy paths
+// ---------------------------------------------------------------------------
+
+test("a ready PR merges and the instance completes via mark-merged", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "merged" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasNoIncident().hasCompletedElements("mark-merged");
+});
+
+test("a queued merge parks on the event gateway; the landed message marks it merged", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElements("wait-landed", "wait-evicted");
+  await engine.publishMessage({ name: "merge-landed", correlationKey: "pr-1" });
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasCompletedElements("mark-merged");
+});
+
+test("an evicted queued merge re-arms the poller rather than completing", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  await engine.publishMessage({ name: "merge-evicted", correlationKey: "pr-1" });
+  // back at the poller's wait, not merged
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  assert(!completedElementIds(engine).has("mark-merged"), "an evicted merge must not mark-merged");
+});
+
+// ---------------------------------------------------------------------------
+// Transient-retry arm (mergeRetryArm, #334)
+// ---------------------------------------------------------------------------
+
+test("a transient retry re-arms the poller within budget and advances the retry counter only on retry", async () => {
+  const engine = await boot({ responses: { "pr.merge": [{ mergeStatus: "retry" }, { mergeStatus: "merged" }] } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  // 1st attempt: retry (base moved) → within budget → re-arm → 2nd attempt: merged
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  // the retry re-armed and re-polled; feed a second mergeable so the 2nd attempt runs
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "a within-budget retry must NOT escalate");
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted();
+});
+
+test("a retry that exhausts the budget escalates as a repeated race, not a generic refusal", async () => {
+  const engine = await boot({
+    responses: { "pr.merge": { mergeStatus: "retry" } },
+    vars: { mergeRetryMax: 0 }, // first retry → mergeRetryRound 1 > 0 → exhausted
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "retry budget", "the retry escalation must read as a repeated race");
+});
+
+// ---------------------------------------------------------------------------
+// CI-fix sub-process (SP_cifix) — mergeCiReattempt (#134), #329
+// ---------------------------------------------------------------------------
+
+async function driveToCiFix(engine: WasmEngineClient): Promise<void> {
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({
+    name: "merge-ready",
+    correlationKey: "pr-1",
+    variables: { mergeState: "blocked", failingChecks: 1, failingChecksList: "build" },
+  });
+}
+
+test("a fixed CI verdict runs the agent, advances the fix counter, and re-arms the poller", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "fixed" } } });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("fix-ci")
+    .hasVariable("ciFixRound", 1); // the fix counter advanced across the sub-process boundary
+  const done = completedElementIds(engine);
+  assert(!done.has("merge-esc-attempt") && !done.has("merge-esc-conflict"), "a fixed verdict must never escalate");
+});
+
+test("a reattempt CI verdict re-arms the poller and never pages a human (#134)", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "reattempt" } } });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  const done = completedElementIds(engine);
+  assert(!done.has("merge-esc-attempt") && !done.has("merge-esc-conflict"), "a reattempt must not escalate");
+});
+
+test("a no-verdict CI result reconciles from ground truth (re-arm), not escalation (#134)", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { summary: "unclear" } } }); // no `status`
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "a missing status must not escalate");
+});
+
+test("a blocked CI verdict with nothing pushed reconciles once before escalating", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "blocked", pushed: false } } });
+  await driveToCiFix(engine);
+  // ci-reconcile re-arms and re-checks mergeable; it does not escalate on the first block
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("ci-reconcile")
+    .hasVariable("ciBlockedReconciled", true); // the one-shot reconcile is marked spent
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "the first block episode must reconcile, not page a human");
+});
+
+test("a blocked CI verdict that already pushed escalates with a could-not-fix question", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "blocked", pushed: true } } });
+  await driveToCiFix(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "CI-fix agent could not", "the question must name the could-not-fix trigger");
+});
+
+test("a CI-fix that discovers a dependency records it and waits on the other PR", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "waiting-on-pr", dependsOn: "acme/app#2" } } });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-deps")
+    .hasCompletedElements("record-merge-dep"); // a waiting-on-pr verdict records the dependency
+});
+
+test("CI-fix budget exhaustion escalates as not-mergeable without running the agent", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "fixed" } }, vars: { ciFixMax: 0 } });
+  await driveToCiFix(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  assert(!completedElementIds(engine).has("fix-ci"), "budget exhaustion must not run the fix-ci agent");
+});
+
+test("the fix-ci agent SLA interrupts the sub-process and escalates", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": null } }); // park on the agent so the SLA fires
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("fix-ci");
+  await engine.advanceTime(AGENT_SLA_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "time budget (SLA)", "the SLA escalation must name the SLA trigger");
+});
+
+// ---------------------------------------------------------------------------
+// Rebase sub-process (SP_rebase) — mergeRebaseArm
+// ---------------------------------------------------------------------------
+
+async function driveToRebase(engine: WasmEngineClient): Promise<void> {
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "conflict" } });
+}
+
+test("a conflict runs the bounded rebase agent and a rebased result re-arms the poller", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "rebased" } } });
+  await driveToRebase(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("rebase") // a conflict runs the rebase agent, not page a human
+    .hasVariable("rebaseRound", 1); // the rebase counter advanced across the sub-process boundary
+});
+
+test("a rebase that cannot resolve escalates with a conflict question", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "blocked" } } });
+  await driveToRebase(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "rebase agent could not resolve", "the question must name the conflict trigger");
+});
+
+test("a no-verdict rebase result reconciles from ground truth, not escalation (#134)", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { summary: "unclear" } } }); // no `status`
+  await driveToRebase(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "a missing rebase status must not escalate");
+});
+
+test("rebase budget exhaustion escalates as not-mergeable without running the agent", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "rebased" } }, vars: { rebaseMax: 0 } });
+  await driveToRebase(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  assert(!completedElementIds(engine).has("rebase"), "budget exhaustion must not run the rebase agent");
+});
+
+test("the rebase agent SLA interrupts the sub-process and escalates as not-mergeable", async () => {
+  const engine = await boot({ responses: { "senior:rebase": null } });
+  await driveToRebase(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("rebase");
+  await engine.advanceTime(AGENT_SLA_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+});
+
+// ---------------------------------------------------------------------------
+// Escalation user task (mergeEscalationUserTask #256, mergeEscalationQuestion #329/#454)
+// ---------------------------------------------------------------------------
+
+test("an escalation parks on the native user task; answering it reconciles then re-arms the poller", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "blocked" } } });
+  await driveToRebase(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  await engine.completeUserTask(await mergeAnswerTaskKey(engine), { answer: "rebased manually, retry" });
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("record-merge-answer"); // answering runs the pr.answer-escalation reconcile
+});
+
+test("a persist-escalation that opens nothing (escalated:false) re-enters the poller, not a dead user task", async () => {
+  const engine = await boot({
+    responses: { "senior:rebase": { status: "blocked" }, "pr.persist-escalation": { escalated: false } },
+  });
+  await driveToRebase(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  const openTasks = await engine.searchUserTasks({});
+  assert(
+    !openTasks.some((t) => t.elementId === "wait-merge-answer"),
+    "escalated:false must not park a user task",
+  );
+});
+
+test("a not-landable gate verdict gives a draft PR an actionable 'mark it ready' question (#454)", async () => {
+  const engine = await boot();
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "draft" } });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "draft", "a draft PR must get a mark-it-ready question");
+});
+
+// ---------------------------------------------------------------------------
+// Terminate semantics — the refactor kept MergeAbandoned at the root
+// ---------------------------------------------------------------------------
+
+test("an abandoned merge ends the whole instance via the root terminate, without merging", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "abandoned" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  // `MergeAbandoned` is a terminate end event at the ROOT scope: it ends all tokens, so the whole
+  // instance finishes (BPMN: a terminate end event *completes* the instance — `Completed`, not a
+  // cancellation `Terminated`). Had it lived inside `SP_cifix`/`SP_rebase`, the terminate would end
+  // only that sub-process scope and the outer poller would re-arm, leaving the instance ACTIVE —
+  // so `hasCompleted()` (nothing left running) is exactly what proves the terminate stayed at root.
+  const done = completedElementIds(engine);
+  assert(done.has("MergeAbandoned"), "the abandon terminate end event must fire");
+  assert(!done.has("mark-merged"), "an abandoned PR must not mark-merged");
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasCompletedElements("MergeAbandoned");
+  const open = await engine.searchUserTasks({});
+  assert(open.length === 0, "the root terminate must leave nothing running (no re-armed poller, no parked escalation)");
+});