@nanobpm/nano-workforce 0.45.0 → 0.46.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [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)
+
+
+### Features
+
+* add plan review escalation ([#128](https://github.com/nanobpm/nano-workforce/issues/128)) ([b67cc9e](https://github.com/nanobpm/nano-workforce/commit/b67cc9ebd84ef251e38e1e0fc332f712f82438c2)), closes [owner/repo#N](https://github.com/owner/repo/issues/N)
+
 # [0.45.0](https://github.com/nanobpm/nano-workforce/compare/v0.44.1...v0.45.0) (2026-08-12)
 
 

package/SPEC.md

@@ -511,6 +511,44 @@ the loop runs one parallel `implement` MI fan-out per wave:
   directive in a sub-issue body, mapping each prerequisite `#M` to `issue-M` in the
   adopted task's `dependsOn` — so a human-declared blocking order survives adoption.
 
+### 13.2 Trial-merge integration gate (D3) — issue #69
+
+Before a wave's still-open heads land, the fan-out runs a **D3 trial merge** to catch
+**emergent** conflicts: heads that merge cleanly but whose *combination* breaks the
+target repo's suite. `app/trialMerge.ts` classifies the result `clean | merge-conflict
+| suite-failed`; only `suite-failed` escalates (`trialMergeDecision`). Textual
+merge-conflicts are pass-through — D2/D6 own merge-exclusion and merge-train ordering.
+It runs only for `headCount >= 2` on non-mergify repos (`shouldRunTrialMerge`).
+
+Flow (`resources/processes/plan-fanout.bpmn`): `gw-trial-needed` → `trial-merge`
+(`senior:trial-merge`) → `record-trial-merge` (audit row in `plan_trial_merges`) →
+`gw-trial` (`trial red?`). On red it persists a plan-level escalation
+(`pr.persist-task-escalation`, task id `trial-merge-wave-<N>`, corrKey
+`<plan_key>:trial-merge-wave-<N>`) and parks at `wait-trial-answer`
+(`feature-escalation-answered`). The operator answers exactly `proceed` to override and
+continue, or anything else to **rerun** the trial after pushing a fix.
+
+**Known gap — inherited vs emergent failures (issue #129, PLANNED).** As shipped, D3
+escalates on *any* red combined suite, including a failure that was **already red on
+each head individually** (e.g. a per-PR build defect, or a repo-wide workspace
+build-ordering bug). That parks a human on something that is not an integration
+decision. The target behaviour is an **autonomy ladder**:
+
+1. **Shift-left** — a head whose *required* checks are red never enters the trial merge;
+  the convergence loop's `senior:fix-ci` path owns per-PR failures. D3 only sees
+  individually-green heads.
+2. **Baseline-diff** — the `senior:trial-merge` agent reports, per failing check,
+  whether it was green on each head alone; D3 escalates **only** on checks that
+  *regress under combination* (green-per-head → red-combined) and attributes inherited
+  failures back to the owning head's loop.
+3. **Auto-remediation** — for deterministic, agent-diagnosable classes (build ordering,
+  lockfile drift, renamed scripts) a `senior:integration-fix` agent pushes the fix and
+  reruns the trial before any human is parked (reusing the escalate→wait→rerun/proceed
+  branch from the plan-review escalation, PR #128).
+
+A human escalation is then reserved for its one true case: **two slices that each pass
+but encode incompatible decisions about a shared contract** — a genuine design call.
+
 ## 14. Open questions / future
 
 - **Provisioning the existing PR branch** — resolved: the `c8ctl` host-git
@@ -524,6 +562,8 @@ the loop runs one parallel `implement` MI fan-out per wave:
 - **Supervised vs external worker** — the agent runs as an external
   `c8ctl nano work` daemon by default; a supervised in-server mode is possible
   later (ADR 0041 decision).
+- **Autonomous D3** — shift-left + baseline-diff + auto-remediation so the trial-merge
+  gate only escalates genuine cross-slice design conflicts (§13.2, issue #129).
 - **Prompt versioning/hash** per PR for auditability.
 - **Auth on the web UI** — the manifest `security` block (ADR 0028) if this is
   exposed beyond localhost.

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";
@@ -70,6 +70,10 @@ function memTable(rows: any[], key: string) {
       rows.push(r);
       return Promise.resolve(r);
     },
+    count: (q: any) =>
+      Promise.resolve(
+        rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length,
+      ),
     update: (k: any, patch: any) => {
       const r = rows.find((x) => x[key] === k);
       if (r) Object.assign(r, patch);
@@ -97,8 +101,8 @@ test("re-plan of a finished issue clears stale plan_reviews rows", async () => {
     },
     plan_reviews: {
       rows: [
-        { plan_key: PLAN_KEY, round: 0 },
-        { plan_key: PLAN_KEY, round: 1 },
+        { plan_key: PLAN_KEY, epoch: 0, round: 0 },
+        { plan_key: PLAN_KEY, epoch: 0, round: 1 },
       ],
       key: "plan_key",
     },
@@ -195,7 +199,13 @@ test("re-plan of a finished issue clears stale open escalations and the denormal
 // task row, and publishing the correlated resume message — that had no unit coverage. These
 // drive both against the in-memory data layer above and assert the oldest-first surfacing,
 // the answer mirroring, and the published message.
-import { answerTaskEscalation, refreshOpenTaskEscalation } from "./plan.ts";
+import {
+  answerPlanEscalation,
+  answerTaskEscalation,
+  currentPlanReviewEpoch,
+  PLAN_ESCALATION_MESSAGE,
+  refreshOpenTaskEscalation,
+} from "./plan.ts";
 
 function escalationStores(rows: unknown[]): Record<string, { rows: unknown[]; key: string }> {
   return {
@@ -293,6 +303,131 @@ 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: {
+      rows: [
+        { id: 1, plan_key: "owner/repo#10", status: "answered" },
+        { id: 2, plan_key: "owner/repo#10", status: "open" },
+        { id: 3, plan_key: "owner/repo#other", status: "answered" },
+      ],
+      key: "id",
+    },
+  };
+  assertEquals(await currentPlanReviewEpoch(memData(stores), "owner/repo#10"), 1);
+});
+
+test("answerPlanEscalation records directive, clears the plan pointer, and publishes the resume message", async () => {
+  const stores = {
+    plans: {
+      rows: [{
+        plan_key: "owner/repo#11",
+        open_plan_escalation_id: 7,
+        open_plan_findings: "reviewer findings",
+        open_plan_round: 2,
+      }],
+      key: "plan_key",
+    },
+    plan_review_escalations: {
+      rows: [{
+        id: 7,
+        plan_key: "owner/repo#11",
+        epoch: 0,
+        round: 2,
+        findings: "reviewer findings",
+        status: "open",
+        directive: null,
+        note: null,
+      }],
+      key: "id",
+    },
+  };
+  const published: any[] = [];
+  const engine = {
+    publishMessage: (m: any) => {
+      published.push(m);
+      return Promise.resolve();
+    },
+  } as any;
+
+  const r = await answerPlanEscalation(memData(stores), engine, "owner/repo#11", "revise", "Use issue-1 as seam.");
+  assertEquals(r.ok, true);
+  assertEquals(r.directive, "revise");
+  const esc = stores.plan_review_escalations.rows[0] as any;
+  assertEquals(esc.status, "answered");
+  assertEquals(esc.directive, "revise");
+  assertEquals(esc.note, "Use issue-1 as seam.");
+  const plan = stores.plans.rows[0] as any;
+  assertEquals(plan.open_plan_escalation_id, null);
+  assertEquals(plan.open_plan_findings, null);
+  assertEquals(plan.open_plan_round, null);
+  assertEquals(published[0].name, PLAN_ESCALATION_MESSAGE);
+  assertEquals(published[0].correlationKey, "owner/repo#11");
+  assertEquals(published[0].variables.planEscalationDirective, "revise");
+  assertEquals(
+    String(published[0].variables.planFindings).includes("Use issue-1 as seam."),
+    true,
+  );
+});
+
 // Coverage for the epic base-branch control (issue nano-ide #124 / 019_plan_base_branch.sql).
 //
 // A plan may pin a base branch so the fleet branches off — and opens every PR against — a long-lived

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";
@@ -44,6 +45,13 @@ export interface Plan {
   open_task_question: string | null;
   open_task_corr_key: string | null;
   open_task_id: string | null;
+  // Denormalised "open plan-review escalation" pointer (# plan-review escalation): when the
+  // adversarial plan-review cap is reached without approval, the process parks for a human
+  // proceed/revise directive. These fields surface the newest open plan-level escalation on the
+  // plans page without overloading the implementation-phase `plan_escalations` table.
+  open_plan_escalation_id: number | null;
+  open_plan_findings: string | null;
+  open_plan_round: number | null;
   // Wave-merge barrier (007_wave_gate.sql): the wave index whose PRs the plan is currently
   // waiting to see MERGED before dispatching the next wave, or null when not parked at the barrier.
   gate_wave: number | null;
@@ -115,6 +123,10 @@ export const planEscalations = (data: DataLayer) =>
  * subscription correlates on `<plan_key>:<task_id>` (see plan-fanout.bpmn). */
 export const FEATURE_ESCALATION_MESSAGE = "feature-escalation-answered";
 
+/** The message the plan-fanout process catches to resume a plan-review escalation; its
+ * subscription correlates on `<plan_key>` (see plan-fanout.bpmn). */
+export const PLAN_ESCALATION_MESSAGE = "plan-escalation-answered";
+
 /** Build the per-task message correlation key the process parks on. */
 export const featureCorrKey = (planKey: string, taskId: string) => `${planKey}:${taskId}`;
 
@@ -136,6 +148,7 @@ export const planTaskDeps = (data: DataLayer) =>
  * (crash/timeout after the insert) reuses its row instead of appending a duplicate round. */
 export interface PlanReview {
   plan_key: string;
+  epoch: number;
   round: number;
   approved: number;
   findings: string | null;
@@ -144,6 +157,31 @@ export interface PlanReview {
 }
 export const planReviews = (data: DataLayer) => data.table<PlanReview>("plan_reviews", "plan_key");
 
+export type PlanEscalationDirective = "proceed" | "revise";
+
+export function parsePlanEscalationDirective(input: unknown): PlanEscalationDirective | null {
+  const s = typeof input === "string" ? input.trim().toLowerCase() : "";
+  return s === "proceed" || s === "revise" ? s : null;
+}
+
+/** One plan-review cap escalation. Kept in a dedicated table rather than overloading
+ * `plan_escalations`: the latter is task-scoped (`task_id`/`corr_key` are NOT NULL and mirrored
+ * onto `plan_tasks`), while this row is plan-scoped and drives the review epoch reset. */
+export interface PlanReviewEscalation {
+  id: number;
+  plan_key: string;
+  epoch: number;
+  round: number;
+  findings: string | null;
+  status: string;
+  directive: PlanEscalationDirective | null;
+  note: string | null;
+  asked_at: string;
+  answered_at: string | null;
+}
+export const planReviewEscalations = (data: DataLayer) =>
+  data.table<PlanReviewEscalation>("plan_review_escalations", "id");
+
 /** Read a positive-integer env override, falling back when unset/blank/invalid. A bad value
  * (e.g. "", "abc", "0", "2.5") must NOT silently become `NaN`/`0` — that would make the round
  * cap `round + 1 >= cap` always false and allow an unbounded revise loop. */
@@ -154,11 +192,17 @@ export function positiveIntEnv(name: string, fallback: number): number {
   return Number.isInteger(n) && n > 0 ? n : fallback;
 }
 
-/** Max adversarial plan-review rounds. Reaching the cap WITHOUT approval is a hard failure: the
- * fan-out raises a `PLAN_REJECTED` incident rather than dispatching an un-approved plan (issue
- * #86). The last round's findings are still recorded. */
+/** Max adversarial plan-review rounds per epoch. Reaching the cap WITHOUT approval parks the
+ * fan-out on a human plan-review escalation rather than dispatching an un-approved plan (issue
+ * #86). A human `revise` answer starts a fresh epoch, so the next plan gets a full new budget. */
 export const MAX_PLAN_REVIEW_ROUNDS = positiveIntEnv("NANO_PLAN_REVIEW_ROUNDS", 3);
 
+/** The current review epoch is derived from the append-only escalation log: every answered
+ * plan-review escalation represents a human decision to leave the prior budget behind. */
+export async function currentPlanReviewEpoch(data: DataLayer, planKey: string): Promise<number> {
+  return await planReviewEscalations(data).count({ plan_key: planKey, status: "answered" });
+}
+
 /** A plan is "done" in exactly these states; everything else (planning, dispatched)
  * is in flight. The cancel guard and the active view key off this. */
 export const PLAN_TERMINAL_STATUSES: readonly string[] = ["done", "failed", "abandoned"];
@@ -279,14 +323,18 @@ export async function startPlan(
     // Clear them here — the table is keyed on `plan_key`, so one delete drops the
     // whole set (mirrors how record-plan clears `plan_task_deps`).
     await planReviews(data).delete(parsed.planKey);
-    // Same class of stale-row bug for the implementation-phase escalation state
-    // (issue #25): `plan_escalations` is keyed on `id` (not `plan_key`), so drop
-    // the prior run's rows one-by-one. Otherwise a still-"open" escalation from
-    // the previous run survives the re-plan and `refreshOpenTaskEscalation`
-    // re-surfaces a question for a `task_id` we just deleted from `plan_tasks`.
+    // Same class of stale-row bug for escalation state: task escalations are keyed on `id` (not
+    // `plan_key`), so drop the prior run's rows one-by-one. Otherwise a still-"open" escalation
+    // from the previous run survives the re-plan and `refreshOpenTaskEscalation` re-surfaces a
+    // question for a `task_id` we just deleted from `plan_tasks`.
     for (const e of await planEscalations(data).find({ plan_key: parsed.planKey })) {
       await planEscalations(data).delete(e.id);
     }
+    // Plan-review escalations are also keyed on `id` because they are an audit trail; clear them
+    // on a fresh submission so the epoch derived from answered escalations resets to 0.
+    for (const e of await planReviewEscalations(data).find({ plan_key: parsed.planKey })) {
+      await planReviewEscalations(data).delete(e.id);
+    }
     // Same for the structured impl-change deltas (D5, #55): keyed on `id`, so drop the prior run's
     // rows one-by-one, otherwise a stale delta lingers in the epic report for a task we just deleted.
     await clearTaskDeltas(data, parsed.planKey);
@@ -303,6 +351,9 @@ export async function startPlan(
       open_task_question: null,
       open_task_corr_key: null,
       open_task_id: null,
+      open_plan_escalation_id: null,
+      open_plan_findings: null,
+      open_plan_round: null,
       blackboard_token: token,
       base_branch: base,
       updated_at: ts,
@@ -383,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 })) {
@@ -398,3 +463,63 @@ export async function answerTaskEscalation(
   await refreshOpenTaskEscalation(data, open.plan_key);
   return { ok: true, escalationId: open.id, planKey: open.plan_key, taskId: open.task_id };
 }
+
+export function normalizePlanEscalationDirective(input: unknown): PlanEscalationDirective {
+  return parsePlanEscalationDirective(input) ?? "revise";
+}
+
+function renderPlanEscalationFindings(open: PlanReviewEscalation, note: string): string {
+  const parts = [
+    `Plan review reached its round budget at epoch ${open.epoch}, round ${open.round}.`,
+    "",
+    "Reviewer findings:",
+    (open.findings ?? "").trim() || "(no reviewer findings were provided.)",
+  ];
+  if (note) {
+    parts.push("", "Human guidance:", note);
+  } else {
+    parts.push("", "Human directive: revise the plan within the allowed task boundaries.");
+  }
+  return parts.join("\n");
+}
+
+/** Answer the newest open plan-review escalation. `proceed` is an explicit human override that lets
+  * the current (unapproved) plan continue to wave dispatch; `revise` (the default) folds the human
+  * note into `planFindings` and starts a fresh review epoch on the next planner pass. */
+export async function answerPlanEscalation(
+  data: DataLayer,
+  engine: EngineClient,
+  planKey: string,
+  directiveInput: unknown,
+  noteInput: unknown,
+) {
+  const open = (await planReviewEscalations(data).find({ plan_key: planKey, status: "open" }))
+    .sort((a, b) => b.id - a.id)[0];
+  if (!open) return { ok: false, reason: "no open plan escalation" };
+
+  const directive = normalizePlanEscalationDirective(directiveInput);
+  const note = typeof noteInput === "string" ? noteInput.trim() : "";
+  const ts = now();
+  await planReviewEscalations(data).update(open.id, {
+    directive,
+    note: note || null,
+    status: "answered",
+    answered_at: ts,
+  });
+  await plans(data).update(planKey, {
+    open_plan_escalation_id: null,
+    open_plan_findings: null,
+    open_plan_round: null,
+    updated_at: ts,
+  });
+
+  await engine.publishMessage({
+    name: PLAN_ESCALATION_MESSAGE,
+    correlationKey: planKey,
+    variables: {
+      planEscalationDirective: directive,
+      planFindings: directive === "revise" ? renderPlanEscalationFindings(open, note) : "",
+    },
+  });
+  return { ok: true, escalationId: open.id, planKey, directive };
+}

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;
 }