@nanobpm/nano-workforce 0.145.0 → 0.146.0

package/app/mergeLandedWait.ts

@@ -0,0 +1,39 @@
+// Merge-queue landing liveness policy — kept as a pure module (no env, no I/O) so it is trivially
+// testable, mirroring app/agentSla.ts. `app/service.ts` seeds the validated `landedWaitTimeout`
+// process variable when it starts the merge-loop; the merge-loop's `wait-landed-timeout` timer catch
+// (the timer arm of the `eg-landed` event-based gateway, racing `merge-landed` / `merge-evicted`)
+// evaluates its `<bpmn:timeDuration>=landedWaitTimeout` at timer creation (FEEL-expression timer
+// durations, engine-native).
+//
+// This closes the merge-queue landing liveness gap (issue #556): `attempt-merge` classifies a merge
+// as `queued` on an ambiguous "merge queue" signal (or a REST "accepted but not yet landed"
+// fallback) WITHOUT verifying the PR was actually enqueued. On a repo where a plain `gh pr merge`
+// does not enqueue (e.g. Mergify, which needs an explicit `@Mergifyio queue`), the PR is never
+// placed in any queue, yet the loop parks at `wait-landed` awaiting a `merge-landed` that can never
+// be published — ACTIVE, no incident, no escalation, forever. Bounding the wait with a timer arm
+// makes that impossible: when the timeout elapses the token routes to the existing merge escalation
+// so a human is pulled in (add it to the queue / merge it, then reply to retry). It is a durable,
+// in-process backstop — no external watchdog required, mirroring the convergence loop's
+// `wait-review-timeout`.
+
+import { isoDuration } from "./reviewWait.ts";
+
+/** Default merge-queue landing timeout (ISO-8601 duration): how long the merge loop waits for a
+ * `queued` PR to actually land before the timer arm of the `eg-landed` event-based gateway fires and
+ * it escalates to a human. Deliberately generous — a native GitHub merge queue legitimately takes a
+ * while to build the prospective merged commit and run its required checks — while still bounded so a
+ * never-enqueued PR (the Mergify-eligible-but-unqueued wedge, #556) surfaces to a human rather than
+ * hanging forever. */
+export const DEFAULT_MERGE_LANDED_WAIT_TIMEOUT = "PT1H";
+
+/** Validate the operator-supplied merge-queue landing timeout (env
+ * `NANO_PR_MERGE_LANDED_WAIT_TIMEOUT`, ISO-8601 duration), falling back to
+ * {@link DEFAULT_MERGE_LANDED_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 mergeLandedWaitTimeout(
+  raw: string | undefined,
+  def: string = DEFAULT_MERGE_LANDED_WAIT_TIMEOUT,
+): string {
+  return isoDuration(raw, def);
+}

package/app/mergeLoopBehaviour.test.ts

@@ -41,6 +41,7 @@ import {
 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
 
 type Output = Record<string, unknown>;
 type Responder = Output | Output[] | ((job: { variables: Record<string, unknown> }) => Output);
@@ -80,6 +81,7 @@ const DEFAULT_VARS: Record<string, unknown> = {
   rebaseRound: 0,
   mergeRetryRound: 0,
   agentSlaTimeout: "PT30M",
+  landedWaitTimeout: "PT30M",
   abandonBrief: null,
   failingChecksList: null,
   status: null,
@@ -206,11 +208,36 @@ test("a queued merge parks on the event gateway; the landed message marks it mer
   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");
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElements("wait-landed", "wait-evicted", "wait-landed-timeout");
   await engine.publishMessage({ name: "merge-landed", correlationKey: "pr-1" });
   assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasCompletedElements("mark-merged");
 });
 
+test("a queued merge that never lands escalates when the landing timeout fires (#556)", async () => {
+  // The Mergify wedge: `attempt-merge` classifies the merge `queued` on an ambiguous signal, but the
+  // repo never actually enqueued the PR, so `merge-landed` can never be published. Without the timer
+  // arm the token would park at `wait-landed` forever (ACTIVE, no incident). The timer bounds it.
+  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().hasActiveElement("wait-landed");
+  await engine.advanceTime(LANDED_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-landed");
+  assert(!completedElementIds(engine).has("mark-merged"), "a never-landed queued merge must not mark-merged");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "did not land within the merge-queue landing timeout", "the escalation must name the landing-timeout trigger");
+});
+
+test("answering the landing-timeout escalation re-arms the merge poller (#556)", 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.advanceTime(LANDED_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  await engine.completeUserTask(await mergeAnswerTaskKey(engine), { answer: "queued it manually, retry" });
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+});
+
 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/service.ts

@@ -54,6 +54,7 @@ import {
 import { activeStatusesFor, derivedTrackingTable } from "./instanceTracking.ts";
 import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
+import { mergeLandedWaitTimeout } from "./mergeLandedWait.ts";
 import {
   freshHeadRunAction,
   headRunPresenceCount,
@@ -156,6 +157,18 @@ export const AGENT_SLA_TIMEOUT = agentSlaTimeout(process.env.NANO_PR_AGENT_SLA_T
  * default so an uninterpretable timer is never deployed. */
 export const REVIEW_WAIT_TIMEOUT = reviewWaitTimeout(process.env.NANO_PR_REVIEW_WAIT_TIMEOUT);
 
+/** How long the merge loop waits for a `queued` PR to actually land before escalating to a human.
+ * Seeded as the `landedWaitTimeout` process variable at merge start and evaluated by the merge-loop's
+ * `wait-landed-timeout` timer catch (the timer arm of the `eg-landed` event-based gateway, racing the
+ * `merge-landed` / `merge-evicted` messages). `attempt-merge` classifies a merge as `queued` on an
+ * ambiguous "merge queue" signal without verifying a real enqueue, so on a repo that never actually
+ * queues a plain `gh pr merge` (e.g. Mergify) the loop would otherwise park at `wait-landed` forever
+ * (issue #556). ISO-8601 duration; a malformed `NANO_PR_MERGE_LANDED_WAIT_TIMEOUT` falls back to the
+ * default so an uninterpretable timer is never deployed. */
+export const MERGE_LANDED_WAIT_TIMEOUT = mergeLandedWaitTimeout(
+  process.env.NANO_PR_MERGE_LANDED_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). */
@@ -708,6 +721,7 @@ export async function startMerge(
       mergeRetryRound: 0,
       mergeRetryMax: MAX_MERGE_RETRIES,
       agentSlaTimeout: AGENT_SLA_TIMEOUT,
+      landedWaitTimeout: MERGE_LANDED_WAIT_TIMEOUT,
       // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
       rootRequestKey,
       abandonUrl: abUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.145.0",
+  "version": "0.146.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",