@nanobpm/nano-workforce 0.46.0 → 0.46.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.46.1](https://github.com/nanobpm/nano-workforce/compare/v0.46.0...v0.46.1) (2026-08-12)
+
+
+### Bug Fixes
+
+* **trial-merge:** durable "needs attention" resolution + robust escalation key ([#131](https://github.com/nanobpm/nano-workforce/issues/131)) ([71200e8](https://github.com/nanobpm/nano-workforce/commit/71200e814a8c035a79f1eec37303781c70b6e6c0))
+
 # [0.46.0](https://github.com/nanobpm/nano-workforce/compare/v0.45.0...v0.46.0) (2026-08-12)
 
 

package/app/plan.test.ts

@@ -5,7 +5,7 @@
 // planner could revise forever. `positiveIntEnv` must fall back to the default on any value that
 // is not a positive integer, so the loop is always bounded.
 import { test } from "node:test";
-import { assertEquals, assertThrows } from "#test-assert";
+import { assertEquals, assertRejects, assertThrows } from "#test-assert";
 import { positiveIntEnv } from "./plan.ts";
 
 const KEY = "NANO_PLAN_REVIEW_ROUNDS_TEST";
@@ -303,6 +303,64 @@ test("answerTaskEscalation is a no-op when no open escalation matches the correl
   assertEquals(r.ok, false);
 });
 
+// Red/green regression (PR #131 suppressed advisory, app/plan.ts:455).
+//
+// Clearing a trial-merge wave's "Needs attention" row (`resolveTrialMergeAttention`)
+// is a best-effort cosmetic cleanup, but it must be RETRIABLE: if it ran only AFTER
+// the escalation was committed as `answered` and the resume message was published,
+// a transient DB error there would 500 the whole answer flow while the escalation is
+// already answered/resumed — a retry then 404s (no open escalation) and the red row
+// is pinned forever (the very failure the insert-first ordering elsewhere avoids).
+// The fix runs the idempotent resolution BEFORE the commit/publish, so a failure
+// leaves the escalation OPEN and nothing is orphaned — the caller can safely retry.
+test("answerTaskEscalation stays retriable (escalation open, no orphaned resume) when clearing 'Needs attention' fails", async () => {
+  const stores = escalationStores([
+    {
+      id: 1,
+      plan_key: "owner/repo#9",
+      task_id: "trial-merge-wave-0",
+      corr_key: "owner/repo#9:trial-merge-wave-0",
+      question: "Q",
+      status: "open",
+      answer: null,
+    },
+  ]);
+  stores.plan_trial_merges = {
+    rows: [{ id: 100, plan_key: "owner/repo#9", wave: 0, resolved: 0 }],
+    key: "id",
+  };
+  const base = memData(stores);
+  // Inject a transient failure in the trial-merge audit table's `update` only.
+  const data = {
+    table: (name: string, key: string) => {
+      const t = base.table(name, key);
+      if (name === "plan_trial_merges") {
+        return { ...t, update: () => Promise.reject(new Error("transient DB error")) };
+      }
+      return t;
+    },
+  } as any;
+
+  const published: any[] = [];
+  const engine = {
+    publishMessage: (m: any) => {
+      published.push(m);
+      return Promise.resolve();
+    },
+  } as any;
+
+  await assertRejects(() =>
+    answerTaskEscalation(data, engine, "owner/repo#9:trial-merge-wave-0", "proceed")
+  );
+
+  // Escalation must remain OPEN so a retry can recover (never committed as answered).
+  const esc = stores.plan_escalations.rows.find((x: any) => x.id === 1) as any;
+  assertEquals(esc.status, "open");
+  assertEquals(esc.answer, null);
+  // No orphaned resume message was published.
+  assertEquals(published.length, 0);
+});
+
 test("currentPlanReviewEpoch counts answered plan-review escalations only", async () => {
   const stores = {
     plan_review_escalations: {

package/app/plan.ts

@@ -13,6 +13,7 @@ import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
+import { resolveTrialMergeAttention, trialMergeWaveFromTaskId } from "./trialMerge.ts";
 
 /** The BPMN process this module drives (resources/processes/plan-fanout.bpmn). */
 export const PLAN_PROCESS_ID = "plan-fanout";
@@ -433,6 +434,20 @@ export async function answerTaskEscalation(
     .sort((a, b) => b.id - a.id)[0];
   if (!open) return { ok: false, reason: "no open escalation" };
   const ts = now();
+  // A trial-merge escalation (task_id `trial-merge-wave-<wave>`) leaves an
+  // append-only red audit row in `plan_trial_merges`. Answering it clears that
+  // row from the page's "Needs attention" tab — including a "proceed" override
+  // that records no re-run row (a re-run would supersede it, but a proceed would
+  // not, pinning the red row forever).
+  //
+  // Resolve it FIRST, before the escalation is committed as answered and the
+  // resume message is published. `resolveTrialMergeAttention` is idempotent, so
+  // if this throws (e.g. a transient DB error) the escalation is still open and
+  // the whole operation retries cleanly. Running it AFTER the commit/publish
+  // would make a failure here unrecoverable: the escalation is already answered,
+  // a retry 404s (no open escalation), and the red row is pinned forever.
+  const trialWave = trialMergeWaveFromTaskId(open.task_id);
+  if (trialWave != null) await resolveTrialMergeAttention(data, open.plan_key, trialWave);
   await planEscalations(data).update(open.id, { answer, status: "answered", answered_at: ts });
   // Mirror onto the task row so a re-dispatched agent (and the UI) sees the answer.
   for (const t of await planTasks(data).find({ plan_key: open.plan_key, task_id: open.task_id })) {

package/app/trialMerge.test.ts

@@ -1,6 +1,12 @@
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
-import { shouldRunTrialMerge, trialMergeDecision } from "./trialMerge.ts";
+import { assertEquals, assertRejects } from "#test-assert";
+import {
+  recordTrialMergeAudit,
+  resolveTrialMergeAttention,
+  shouldRunTrialMerge,
+  trialMergeDecision,
+  trialMergeWaveFromTaskId,
+} from "./trialMerge.ts";
 
 test("trialMergeDecision only escalates clean-merge suite failures", () => {
   assertEquals(trialMergeDecision("clean"), "proceed");
@@ -14,3 +20,89 @@ test("shouldRunTrialMerge skips lone heads and mergify queues", () => {
   assertEquals(shouldRunTrialMerge(2, { land: { method: "mergify-queue" } }), false);
   assertEquals(shouldRunTrialMerge(2, { land: { method: "gh-merge" } }), true);
 });
+
+// In-memory `plan_trial_merges` table backing the audit-resolution tests.
+function memData() {
+  const rows: any[] = [];
+  let nextId = 1;
+  const table = {
+    async insert(row: any) {
+      const r = { id: nextId++, ...row };
+      rows.push(r);
+      return r.id;
+    },
+    async find(where: any = {}) {
+      return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v)).map((r) => ({ ...r }));
+    },
+    async update(id: any, patch: any) {
+      const r = rows.find((x) => x.id === id);
+      if (r) Object.assign(r, patch);
+    },
+  };
+  const data = { table: () => table } as any;
+  return { data, rows, table };
+}
+
+test("recordTrialMergeAudit supersedes prior rows for the same wave", async () => {
+  const { data, rows } = memData();
+  // Wave 1 fails, then re-runs clean; wave 2 is independent.
+  const first = await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "suite-failed" });
+  await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 2, result: "suite-failed" });
+  const rerun = await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "clean" });
+
+  const byId = (id: number) => rows.find((r) => r.id === id);
+  assertEquals(byId(first).resolved, 1, "the superseded wave-1 red row is resolved");
+  assertEquals(byId(rerun).resolved, 0, "the fresh wave-1 row stays unresolved");
+  // The unrelated wave-2 row is untouched (still needs attention).
+  assertEquals(rows.filter((r) => r.wave === 2)[0].resolved, 0);
+});
+
+test("recordTrialMergeAudit updates a re-reporting job in place without superseding", async () => {
+  const { data, rows } = memData();
+  const id = await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "suite-failed", jobKey: "j1" });
+  const again = await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "clean", jobKey: "j1" });
+  assertEquals(again, id, "the same job_key updates its row in place");
+  assertEquals(rows.length, 1, "no duplicate/supersede row is created");
+  assertEquals(rows[0].result, "clean");
+  assertEquals(rows[0].resolved, 0);
+});
+
+test("recordTrialMergeAudit keeps the wave flagged if the superseding insert fails", async () => {
+  const { data, rows, table } = memData();
+  await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "suite-failed" });
+  // Simulate a crash/failure on the superseding insert. The new row must be
+  // inserted BEFORE prior rows are resolved, so a failure here must not leave
+  // the wave with zero unresolved rows (which would silently clear "Needs
+  // attention").
+  table.insert = async () => {
+    throw new Error("insert failed");
+  };
+  await assertRejects(() => recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "clean" }));
+  const unresolved = rows.filter((r) => r.wave === 1 && r.resolved !== 1);
+  assertEquals(unresolved.length, 1, "the wave still has an unresolved row after the failed insert");
+});
+
+test("resolveTrialMergeAttention clears every unresolved row for the wave", async () => {
+  const { data, rows } = memData();
+  await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "suite-failed" });
+  await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 3, result: "suite-failed" });
+  const cleared = await resolveTrialMergeAttention(data, "o/r#1", 1);
+  assertEquals(cleared, 1);
+  assertEquals(rows.filter((r) => r.wave === 1)[0].resolved, 1);
+  assertEquals(rows.filter((r) => r.wave === 3)[0].resolved, 0, "another wave is untouched");
+  // Idempotent: a second call resolves nothing new.
+  assertEquals(await resolveTrialMergeAttention(data, "o/r#1", 1), 0);
+});
+
+test("trialMergeWaveFromTaskId parses only trial-merge task ids", () => {
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-2"), 2);
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-0"), 0);
+  assertEquals(trialMergeWaveFromTaskId("some-feature-task"), null);
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-x"), null);
+  // Empty suffix must not silently map to wave 0 (Number("") === 0).
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-"), null);
+  // Non-integer / signed / whitespace suffixes are rejected.
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-1.5"), null);
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-+2"), null);
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-12"), 12);
+});

package/app/trialMerge.ts

@@ -28,6 +28,7 @@ export interface TrialMergeAuditRow {
   failing: string | null;
   summary: string | null;
   job_key: string | null;
+  resolved: number;
   created_at: string;
   updated_at: string;
 }
@@ -46,6 +47,17 @@ export function trialMergeTaskId(wave: number): string {
   return `${TRIAL_MERGE_TASK_PREFIX}${Math.max(0, Math.trunc(wave))}`;
 }
 
+/** Inverse of {@link trialMergeTaskId}: the wave a trial-merge escalation
+ * `task_id` refers to, or `null` when `taskId` is not a trial-merge escalation
+ * (e.g. an ordinary feature escalation). */
+export function trialMergeWaveFromTaskId(taskId: string): number | null {
+  if (!taskId.startsWith(TRIAL_MERGE_TASK_PREFIX)) return null;
+  const suffix = taskId.slice(TRIAL_MERGE_TASK_PREFIX.length);
+  if (!/^\d+$/.test(suffix)) return null;
+  const wave = Number(suffix);
+  return Number.isInteger(wave) && wave >= 0 ? wave : null;
+}
+
 const auditTable = (data: DataLayer) => data.table<TrialMergeAuditRow>("plan_trial_merges", "id");
 
 function jsonOrNull(v: unknown): string | null {
@@ -76,6 +88,8 @@ export async function recordTrialMergeAudit(
   if (jobKey) {
     const existing = (await table.find({ plan_key: row.planKey, job_key: jobKey })).sort((a, b) => b.id - a.id)[0];
     if (existing) {
+      // Same job re-reporting (a retry before its wait subscription opened):
+      // update in place — it is the same logical attempt, not a supersede.
       await table.update(existing.id, {
         result: row.result,
         heads: jsonOrNull(row.heads),
@@ -87,16 +101,57 @@ export async function recordTrialMergeAudit(
       return existing.id;
     }
   }
-  return Number(await table.insert({
-    plan_key: row.planKey,
-    wave: row.wave,
-    result: row.result,
-    heads: jsonOrNull(row.heads),
-    conflicts: jsonOrNull(row.conflicts),
-    failing: jsonOrNull(row.failing),
-    summary: row.summary ?? null,
-    job_key: jobKey,
-    created_at: ts,
-    updated_at: ts,
-  }));
+  // A fresh audit row for this wave supersedes every prior row for the same
+  // (plan_key, wave): those are now history, so mark them resolved. Without this
+  // the append-only log leaves an old red row in the page's "Needs attention"
+  // tab forever, even after the wave was re-run clean (issue: the tab never
+  // cleared). The newly-inserted row defaults `resolved = 0`, so a still-red
+  // latest attempt keeps showing until it too is superseded or answered.
+  //
+  // Insert the new (unresolved) row FIRST, then resolve the older rows — never
+  // the reverse. Resolving priors before the insert would leave the wave with
+  // zero unresolved rows if the insert (or the process) failed in between,
+  // silently clearing the "Needs attention" tab. Insert-first guarantees the
+  // wave always has at least one unresolved row through the transition.
+  const id = Number(
+    await table.insert({
+      plan_key: row.planKey,
+      wave: row.wave,
+      result: row.result,
+      heads: jsonOrNull(row.heads),
+      conflicts: jsonOrNull(row.conflicts),
+      failing: jsonOrNull(row.failing),
+      summary: row.summary ?? null,
+      job_key: jobKey,
+      resolved: 0,
+      created_at: ts,
+      updated_at: ts,
+    }),
+  );
+  for (const prior of await table.find({ plan_key: row.planKey, wave: row.wave })) {
+    if (prior.id !== id && prior.resolved !== 1) await table.update(prior.id, { resolved: 1, updated_at: ts });
+  }
+  return id;
+}
+
+/** Mark every trial-merge audit row for `(planKey, wave)` resolved, so the epic
+ * page's "Needs attention" tab stops surfacing it. Called when the wave's trial
+ * escalation is answered — including a "proceed" override that records no
+ * re-run row and so would otherwise leave the old red row pinned forever.
+ * Returns the number of rows newly resolved. */
+export async function resolveTrialMergeAttention(
+  data: DataLayer,
+  planKey: string,
+  wave: number,
+): Promise<number> {
+  const table = auditTable(data);
+  const ts = now();
+  let resolved = 0;
+  for (const r of await table.find({ plan_key: planKey, wave })) {
+    if (r.resolved !== 1) {
+      await table.update(r.id, { resolved: 1, updated_at: ts });
+      resolved++;
+    }
+  }
+  return resolved;
 }

package/db/migrations/021_trial_merge_resolved.sql

@@ -0,0 +1,44 @@
+-- Durable "needs attention" resolution for the trial-merge audit log (issue: the
+-- epic page's "Needs attention" tab never cleared).
+--
+-- `plan_trial_merges` is an append-only audit trail: a re-run after a suite
+-- failure INSERTs a fresh row but never supersedes the old red one, so a
+-- `merge-conflict`/`suite-failed` row stayed in "Needs attention" forever even
+-- after the escalation was answered and the wave re-run clean. Add an explicit
+-- `resolved` flag so the page can hide history, and backfill it for existing
+-- rows. Going forward `recordTrialMergeAudit` marks prior same-(plan,wave) rows
+-- resolved on each new insert (supersede-on-insert).
+--
+-- NB: the migration runner wraps each file in its own transaction — this file
+-- must NOT contain BEGIN/COMMIT.
+
+ALTER TABLE plan_trial_merges ADD COLUMN resolved INTEGER NOT NULL DEFAULT 0;
+
+-- Backfill 1 (supersede): any audit row that has a NEWER row (higher id) for the
+-- same (plan_key, wave) is superseded history — resolve it. The newest row per
+-- wave stays unresolved so a still-red latest attempt keeps showing.
+UPDATE plan_trial_merges
+SET resolved = 1
+WHERE EXISTS (
+  SELECT 1 FROM plan_trial_merges AS newer
+  WHERE newer.plan_key = plan_trial_merges.plan_key
+    AND newer.wave = plan_trial_merges.wave
+    AND newer.id > plan_trial_merges.id
+);
+
+-- Backfill 2 (answered): a red (needs-attention) row whose trial escalation has
+-- already been answered is resolved — even if no re-run row was ever recorded
+-- (e.g. the operator answered "proceed"/override). The trial escalation's
+-- task_id is 'trial-merge-wave-<wave>' (see app/trialMerge.ts trialMergeTaskId).
+UPDATE plan_trial_merges
+SET resolved = 1
+WHERE result IN ('merge-conflict', 'suite-failed')
+  AND EXISTS (
+    SELECT 1 FROM plan_escalations AS e
+    WHERE e.plan_key = plan_trial_merges.plan_key
+      AND e.task_id = 'trial-merge-wave-' || plan_trial_merges.wave
+      AND e.status = 'answered'
+  );
+
+CREATE INDEX IF NOT EXISTS idx_plan_trial_merges_attention
+  ON plan_trial_merges(plan_key, resolved, result);

package/package.json

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

@@ -273,12 +273,18 @@
           "source": "app",
           "table": "plan_trial_merges",
           "orderBy": { "field": "created_at", "dir": "desc" },
-          "filter": [{ "field": "result", "in": ["merge-conflict", "suite-failed"] }]
+          "filter": [
+            { "field": "result", "in": ["merge-conflict", "suite-failed"] },
+            { "field": "resolved", "in": [0] }
+          ]
         },
         "tabs": [
           {
             "label": "Needs attention",
-            "filter": [{ "field": "result", "in": ["merge-conflict", "suite-failed"] }]
+            "filter": [
+              { "field": "result", "in": ["merge-conflict", "suite-failed"] },
+              { "field": "resolved", "in": [0] }
+            ]
           },
           {
             "label": "Clean",

package/resources/processes/plan-fanout.bpmn

@@ -2,7 +2,7 @@
 <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" id="Definitions_nano_workforce_plan" targetNamespace="http://nanobpm.io/nano-workforce">
   <bpmn:message id="Message_featureEscalationAnswered" name="feature-escalation-answered">
     <bpmn:extensionElements>
-      <zeebe:subscription correlationKey="=planKey + &#34;:&#34; + task.id" />
+      <zeebe:subscription correlationKey="=escalationCorrKey" />
     </bpmn:extensionElements>
   </bpmn:message>
   <bpmn:message id="Message_planEscalationAnswered" name="plan-escalation-answered">

package/workers/persist-task-escalation/worker.ts

@@ -36,6 +36,7 @@ interface In extends Record<string, unknown> {
 }
 interface Out extends Record<string, unknown> {
   escalationId: number;
+  escalationCorrKey: string;
 }
 
 // A non-blank trimmed string, else undefined. A blank question/PR must not reach
@@ -106,7 +107,14 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   }
 
   await refreshOpenTaskEscalation(app.data, planKey);
-  return { escalationId };
+  // Emit the correlation key as a single scalar so the downstream
+  // `feature-escalation-answered` catch subscribes on `=escalationCorrKey`
+  // (freshly set, in scope) rather than re-deriving `=planKey + ":" + task.id`.
+  // The concatenation form errored to an empty, unmatchable key whenever `task`
+  // was not a Map at subscription-open, parking the token forever (see the
+  // engine incident fix). The value is identical to `featureCorrKey(planKey,
+  // taskId)`, so the app's answer-publish path still matches.
+  return { escalationId, escalationCorrKey: corrKey };
 };
 
 export default handler;