@nanobpm/nano-workforce 0.163.3 → 0.165.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.165.0](https://github.com/nanobpm/nano-workforce/compare/v0.164.0...v0.165.0) (2026-08-31)
+
+### Features
+
+* **overview:** add Dismiss row action to Active Features grid ([#644](https://github.com/nanobpm/nano-workforce/issues/644)) ([cda5962](https://github.com/nanobpm/nano-workforce/commit/cda59628d31a37faf26e3a749b6443b33f532d7d)), closes [#643](https://github.com/nanobpm/nano-workforce/issues/643)
+
+## [0.164.0](https://github.com/nanobpm/nano-workforce/compare/v0.163.3...v0.164.0) (2026-08-31)
+
+### Features
+
+* **merge-loop:** bound wait-mergeable with a timeout + stall probe ([#636](https://github.com/nanobpm/nano-workforce/issues/636)) ([#640](https://github.com/nanobpm/nano-workforce/issues/640)) ([e12dd04](https://github.com/nanobpm/nano-workforce/commit/e12dd0426d0c7b3defe24d339502397b24b9302c))
+
 ## [0.163.3](https://github.com/nanobpm/nano-workforce/compare/v0.163.2...v0.163.3) (2026-08-31)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -124,6 +124,14 @@ export const ENV_CONTRACTS = {
     semantics: "Maximum transient base/head-moved merge-race retries per PR before escalating.",
     default: "5",
   },
+  NANO_PR_MAX_MERGE_STALL_ROUNDS: {
+    category: "env",
+    name: "NANO_PR_MAX_MERGE_STALL_ROUNDS",
+    owner: "app/service.ts",
+    semantics:
+      "Maximum mergeable-wait-timeout stall-probe re-derivations (dead-poller backstop, #636) before escalating; 0 escalates on the first stall.",
+    default: "3",
+  },
   NANO_PR_REVIEW_WAIT_TIMEOUT: {
     category: "env",
     name: "NANO_PR_REVIEW_WAIT_TIMEOUT",
@@ -143,6 +151,13 @@ export const ENV_CONTRACTS = {
     semantics:
       "How long the merge loop waits for a queued PR to actually land before escalating (FEEL/ISO-8601 duration).",
   },
+  NANO_PR_MERGEABLE_WAIT_TIMEOUT: {
+    category: "env",
+    name: "NANO_PR_MERGEABLE_WAIT_TIMEOUT",
+    owner: "app/service.ts",
+    semantics:
+      "How long the merge loop waits for the poller's `merge-ready` before the stall-probe timer arm fires (dead-poller backstop, #636; FEEL/ISO-8601 duration).",
+  },
   NANO_PR_AUTO_MERGE: {
     category: "env",
     name: "NANO_PR_AUTO_MERGE",

package/app/mergeLoopBehaviour.test.ts

@@ -42,6 +42,7 @@ const MODEL = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
 
 const AGENT_SLA_MS = 30 * 60 * 1000; // matches the PT30M we start instances with
 const LANDED_WAIT_MS = 30 * 60 * 1000; // matches the PT30M landedWaitTimeout we start instances with
+const MERGEABLE_WAIT_MS = 30 * 60 * 1000; // matches the PT30M mergeableWaitTimeout we start instances with
 
 type Output = Record<string, unknown>;
 type Responder = Output | Output[] | ((job: { variables: Record<string, unknown> }) => Output);
@@ -49,6 +50,7 @@ type Responder = Output | Output[] | ((job: { variables: Record<string, unknown>
 const ALL_JOB_TYPES = [
   "pr.arm-merge",
   "pr.merge",
+  "pr.merge-stall-probe",
   "pr.mark-merged",
   "senior:fix-ci",
   "senior:rebase",
@@ -82,6 +84,9 @@ const DEFAULT_VARS: Record<string, unknown> = {
   mergeRetryRound: 0,
   agentSlaTimeout: "PT30M",
   landedWaitTimeout: "PT30M",
+  mergeableWaitTimeout: "PT30M",
+  mergeStallRounds: 0,
+  mergeStallMax: 3,
   abandonBrief: null,
   failingChecksList: null,
   status: null,
@@ -238,6 +243,112 @@ test("answering the landing-timeout escalation re-arms the merge poller (#556)",
   assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
 });
 
+// ---------------------------------------------------------------------------
+// Mergeable-wait bounded-wait backstop (#636) — a stalled poller must never
+// wedge the instance at `waiting_merge` forever. The `gw-merge-wait` event-based
+// gateway races the poller's `merge-ready` message against a `mergeableWaitTimeout`
+// timer; on timeout `merge-stall-probe` re-derives mergeability and the existing
+// `gw-mergeable` routes to the correct arm — or, once `mergeStallMax` is exhausted,
+// to human escalation.
+// ---------------------------------------------------------------------------
+
+test("wait-mergeable races merge-ready against a timer (no bare catch) (#636)", async () => {
+  // After the poller arms the merge, the token forks the event-based gateway: it parks at BOTH the
+  // `merge-ready` catch and the timeout timer. Before the fix, `wait-mergeable` was a bare catch —
+  // no timer sibling — so a dead poller wedged it forever.
+  const engine = await boot();
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElements("wait-mergeable", "wait-mergeable-timeout");
+});
+
+test("a dead poller's PR is probed on timeout and advances to merge — never wedges (#636)", async () => {
+  // No `merge-ready` is EVER published (the poller is dead). RED (before the fix): the instance sits
+  // at `wait-mergeable` forever. GREEN: the timer fires, `merge-stall-probe` re-derives `ready`, and
+  // the existing `ready` arm merges the PR.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
+      "pr.merge": { mergeStatus: "merged" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .hasCompleted()
+    .hasNoIncident()
+    .hasCompletedElements("merge-stall-probe", "attempt-merge", "mark-merged");
+});
+
+test("a CONFLICTING PR whose poller never signalled reaches the rebase arm via the timeout path (#636)", async () => {
+  // The incident that motivated #636: a `CONFLICTING`/`DIRTY` PR (base advanced under it) parked at
+  // `waiting_merge` because the poller never signalled — the auto-rebase arm was never reached. The
+  // timer path re-derives `conflict` and routes it to the bounded rebase agent.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "conflict", failingChecks: 0, failingChecksList: "" },
+      "senior:rebase": { status: "rebased" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("merge-stall-probe", "rebase") // reached the rebase arm via the timeout path
+    .hasVariable("rebaseRound", 1);
+});
+
+test("a blocked PR probed on timeout reaches the CI-fix arm via the timeout path (#636)", async () => {
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "blocked", failingChecks: 1, failingChecksList: "build" },
+      "senior:fix-ci": { status: "fixed" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("merge-stall-probe", "fix-ci")
+    .hasVariable("ciFixRound", 1);
+});
+
+test("the probe advances mergeStallRounds and re-arms within budget (#636)", async () => {
+  // A re-derived `conflict` re-arms after the rebase; the stall counter advanced so a still-dead
+  // poller cannot loop the probe forever — it is bounded by mergeStallMax.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "conflict", failingChecks: 0, failingChecksList: "" },
+      "senior:rebase": { status: "rebased" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop")).hasVariable("mergeStallRounds", 1);
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "a within-budget stall must NOT escalate");
+});
+
+test("the stall-round cap escalates to a human instead of looping forever (#636)", async () => {
+  // `mergeStallMax: 0` — escalate on the first stall. The probe runs once, `gw-merge-stall` finds the
+  // budget exhausted, and routes to `merge-esc-conflict` → the native `wait-merge-answer` user task
+  // rather than re-arming into another timeout round.
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "conflict", failingChecks: 0, failingChecksList: "" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-stall-probe", "merge-esc-conflict");
+  assert(!completedElementIds(engine).has("mark-merged"), "an exhausted stall must not 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" });

package/app/mergeableWait.test.ts

@@ -0,0 +1,39 @@
+// Unit coverage for the mergeable-wait liveness timeout policy. The value is baked into every
+// merge-loop instance's `mergeableWaitTimeout` process variable and evaluated by the
+// `wait-mergeable-timeout` timer catch (the timer arm of the `gw-merge-wait` event-based gateway),
+// so a malformed operator env must never deploy an uninterpretable `<bpmn:timeDuration>` — it falls
+// back to the default instead. Run with `node --test`.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { DEFAULT_MERGEABLE_WAIT_TIMEOUT, mergeableWaitTimeout } from "./mergeableWait.ts";
+
+test("mergeableWaitTimeout: blank / absent / malformed → default", () => {
+  assert.equal(mergeableWaitTimeout(undefined), DEFAULT_MERGEABLE_WAIT_TIMEOUT);
+  assert.equal(mergeableWaitTimeout(""), DEFAULT_MERGEABLE_WAIT_TIMEOUT);
+  assert.equal(mergeableWaitTimeout("   "), DEFAULT_MERGEABLE_WAIT_TIMEOUT);
+  assert.equal(mergeableWaitTimeout("30m"), DEFAULT_MERGEABLE_WAIT_TIMEOUT); // missing leading P/T
+  assert.equal(mergeableWaitTimeout("P"), DEFAULT_MERGEABLE_WAIT_TIMEOUT); // no component
+  assert.equal(mergeableWaitTimeout("PT"), DEFAULT_MERGEABLE_WAIT_TIMEOUT); // T with no time part
+  assert.equal(mergeableWaitTimeout("garbage"), DEFAULT_MERGEABLE_WAIT_TIMEOUT);
+});
+
+test("mergeableWaitTimeout: a valid ISO-8601 duration is honoured and upper-cased", () => {
+  assert.equal(mergeableWaitTimeout("PT30M"), "PT30M");
+  assert.equal(mergeableWaitTimeout("pt2h"), "PT2H");
+  assert.equal(mergeableWaitTimeout("P1D"), "P1D");
+  assert.equal(mergeableWaitTimeout("  pt45m  "), "PT45M");
+});
+
+test("mergeableWaitTimeout: an explicit fallback is honoured for a bad value", () => {
+  assert.equal(mergeableWaitTimeout("nope", "PT10M"), "PT10M");
+  assert.equal(mergeableWaitTimeout("PT15M", "PT10M"), "PT15M");
+});
+
+test("the default is itself a well-formed ISO-8601 duration (never an uninterpretable timer)", () => {
+  // Validate the default against the grammar with a *distinct* fallback: if the default were
+  // malformed it would fall through to the sentinel, so equality to itself proves it parses.
+  const sentinel = "PT1S";
+  assert.notEqual(DEFAULT_MERGEABLE_WAIT_TIMEOUT, sentinel);
+  assert.equal(mergeableWaitTimeout(DEFAULT_MERGEABLE_WAIT_TIMEOUT, sentinel), DEFAULT_MERGEABLE_WAIT_TIMEOUT);
+});

package/app/mergeableWait.ts

@@ -0,0 +1,38 @@
+// Mergeable-wait liveness policy — kept as a pure module (no env, no I/O) so it is trivially
+// testable, mirroring app/mergeLandedWait.ts. `app/service.ts` seeds the validated
+// `mergeableWaitTimeout` process variable when it starts the merge-loop; the merge-loop's
+// `wait-mergeable-timeout` timer catch (the timer arm of the `gw-merge-wait` event-based gateway,
+// racing the poller's `merge-ready` message) evaluates its `<bpmn:timeDuration>=mergeableWaitTimeout`
+// at timer creation (FEEL-expression timer durations, engine-native).
+//
+// This closes the mergeable-wait liveness gap (issue #636): `wait-mergeable` was the only long-lived
+// wait in the merge loop with NO bounded-wait timer — a bare `intermediateCatchEvent` woken *solely*
+// by the in-process poller's `merge-ready` message. If that poller stalls (dies across a redeploy,
+// errors on a PR, or skips a verdict) the instance parks at `waiting_merge` forever, with no timeout
+// and no escalation — the entire conflict/CI remediation machinery (`gw-mergeable` → rebase / CI-fix
+// / escalate) sits downstream of `wait-mergeable`, so it is never entered. Bounding the wait with a
+// timer arm makes that impossible: when the timeout elapses the token routes to `merge-stall-probe`,
+// which re-derives ground-truth mergeability from GitHub and feeds the existing `gw-mergeable` arms
+// (or, after the stall-round cap is exhausted, escalates to a human). It is a durable, in-process
+// backstop — no external watchdog required — mirroring the convergence loop's `wait-review-timeout`
+// and the merge loop's own `wait-landed-timeout`.
+
+import { isoDuration } from "./reviewWait.ts";
+
+/** Default mergeable-wait timeout (ISO-8601 duration): how long the merge loop waits for the poller
+ * to publish `merge-ready` before the timer arm of the `gw-merge-wait` event-based gateway fires and
+ * `merge-stall-probe` re-derives mergeability from ground truth. Deliberately short — a healthy
+ * poller signals within one poll interval, so a 30-minute silence means the poller is dead and the
+ * PR must be reconciled — while still generous enough not to fire against a merely-slow poll pass. */
+export const DEFAULT_MERGEABLE_WAIT_TIMEOUT = "PT30M";
+
+/** Validate the operator-supplied mergeable-wait timeout (env `NANO_PR_MERGEABLE_WAIT_TIMEOUT`,
+ * ISO-8601 duration), falling back to {@link DEFAULT_MERGEABLE_WAIT_TIMEOUT} when absent, blank, or
+ * malformed — a bad env value must never deploy an uninterpretable timer expression. Derives its
+ * validation from the single canonical {@link isoDuration}. */
+export function mergeableWaitTimeout(
+  raw: string | undefined,
+  def: string = DEFAULT_MERGEABLE_WAIT_TIMEOUT,
+): string {
+  return isoDuration(raw, def);
+}

package/app/service.ts

@@ -53,6 +53,7 @@ import {
 } from "./github.ts";
 import { activeStatusesFor, derivedTrackingTable } from "./instanceTracking.ts";
 import { pollLineage } from "./lineage.ts";
+import { mergeableWaitTimeout } from "./mergeableWait.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { mergeLandedWaitTimeout } from "./mergeLandedWait.ts";
 import {
@@ -143,6 +144,15 @@ export const MAX_REBASE_ROUNDS = clampCiFixBudget(process.env.NANO_PR_MAX_REBASE
  * retry (a race escalates immediately). Reuses the CI-fix budget clamp (allows 0 = disable). */
 export const MAX_MERGE_RETRIES = clampCiFixBudget(process.env.NANO_PR_MAX_MERGE_RETRIES, 5);
 
+/** How many times the mergeable-wait timeout backstop (`merge-stall-probe`) will re-derive
+ * mergeability from ground truth and re-arm the merge stage before giving up and escalating to a
+ * human. Bounds the timer arm of the `gw-merge-wait` event-based gateway so a dead in-process poller
+ * (the #636 wedge) can never loop the probe forever: once the cap is exhausted, `gw-merge-stall`
+ * routes to `merge-esc-conflict` (human escalation) instead of re-arming. Default 3; set
+ * `NANO_PR_MAX_MERGE_STALL_ROUNDS=0` to escalate on the first stall. Reuses the CI-fix budget clamp
+ * (allows 0 = escalate immediately, ceiling-capped). */
+export const MAX_MERGE_STALL_ROUNDS = clampCiFixBudget(process.env.NANO_PR_MAX_MERGE_STALL_ROUNDS, 3);
+
 /** How long a merge-loop AGENT service task (rebase / fix-ci) may sit without completing before its
  * interrupting timer boundary fires and the PR escalates for human attention. Seeded as the
  * `agentSlaTimeout` process variable at merge start and evaluated by those tasks' boundary timers.
@@ -170,6 +180,19 @@ export const MERGE_LANDED_WAIT_TIMEOUT = mergeLandedWaitTimeout(
   process.env.NANO_PR_MERGE_LANDED_WAIT_TIMEOUT,
 );
 
+/** How long the merge loop waits for the in-process poller to publish `merge-ready` before the timer
+ * arm of the `gw-merge-wait` event-based gateway fires and `merge-stall-probe` re-derives
+ * mergeability from ground truth. Seeded as the `mergeableWaitTimeout` process variable at merge
+ * start and evaluated by the merge-loop's `wait-mergeable-timeout` timer catch. `wait-mergeable` was
+ * the only long-lived wait in the merge loop with NO bounded-wait timer, so a stalled poller (dead
+ * across a redeploy, errored on a PR, or a skipped verdict) parked the instance at `waiting_merge`
+ * forever with no timeout and no escalation (issue #636). ISO-8601 duration; a malformed
+ * `NANO_PR_MERGEABLE_WAIT_TIMEOUT` falls back to the default so an uninterpretable timer is never
+ * deployed. */
+export const MERGEABLE_WAIT_TIMEOUT = mergeableWaitTimeout(
+  process.env.NANO_PR_MERGEABLE_WAIT_TIMEOUT,
+);
+
 /** Cooldown (ms) between the poller's automatic Copilot re-request nudges for a single waiting PR.
  * Copilot dismisses re-requests, so the poller retries — but not on every tick; this throttles it
  * to one attempt per window. Set via `NANO_PR_REVIEW_NUDGE_MINUTES` (minutes). */
@@ -723,6 +746,9 @@ export async function startMerge(
       mergeRetryMax: MAX_MERGE_RETRIES,
       agentSlaTimeout: AGENT_SLA_TIMEOUT,
       landedWaitTimeout: MERGE_LANDED_WAIT_TIMEOUT,
+      mergeableWaitTimeout: MERGEABLE_WAIT_TIMEOUT,
+      mergeStallRounds: 0,
+      mergeStallMax: MAX_MERGE_STALL_ROUNDS,
       // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
       rootRequestKey,
       abandonUrl: abUrl,

package/nano.app.json

@@ -144,6 +144,10 @@
       "taskType": "pr.mark-merged",
       "handler": "workers/mark-merged/worker.ts"
     },
+    {
+      "taskType": "pr.merge-stall-probe",
+      "handler": "workers/merge-stall-probe/worker.ts"
+    },
     {
       "taskType": "pr.record-dependency",
       "handler": "workers/record-dependency/worker.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.163.3",
+  "version": "0.165.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/overview.page.json

@@ -187,6 +187,17 @@
           { "field": "delivery_label", "header": "Delivery" },
           { "field": "updated_at", "header": "Updated", "width": "9rem", "format": "datetime" }
         ],
+        "rowActions": [
+          {
+            "label": "Dismiss",
+            "confirm": "Tick off this finished run? It acknowledges the run as done and files it under History.",
+            "showWhenField": "stage_state",
+            "action": {
+              "path": "/app/api/actions/acknowledge-done",
+              "body": { "feature_key": "{{row.feature_key}}" }
+            }
+          }
+        ],
         "detail": {
           "fields": [
             { "field": "outcome", "label": "Outcome" }