@nanobpm/nano-workforce 0.165.0 → 0.167.0

package/app/planReadModel.test.ts

@@ -38,9 +38,10 @@ const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migratio
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
 
 const ROLLUPS_MIGRATION = "082_plan_rollups_declare_once.sql";
-const READ_MODEL_MIGRATION = "083_plan_read_model_declare_once.sql";
+const READ_MODEL_MIGRATION = "097_plan_read_model_terminal_dismiss.sql";
 // The forward chain whose net effect the end-to-end tests exercise: the original hand-authored VIEWs
-// (059/060/061/074/080) then the declare-once supersessions (082/083). Mirrors the runtime migrator.
+// (059/060/061/074/080), the declare-once supersessions (082/083), then the terminal-dismiss
+// supersession (097). Mirrors the runtime migrator.
 const MIGRATION_CHAIN = [
   "059_plan_wave_summary.sql",
   "060_plan_wave_rollup.sql",
@@ -48,8 +49,9 @@ const MIGRATION_CHAIN = [
   "074_plan_read_model_derive_bucket.sql",
   "080_plan_read_model_derive_terminal.sql",
   ROLLUPS_MIGRATION,
-  READ_MODEL_MIGRATION,
+  "083_plan_read_model_declare_once.sql",
   "084_plan_wave_tasks_effective_status.sql",
+  READ_MODEL_MIGRATION,
 ];
 
 // The base `plans` / `plan_tasks` / `pull_requests` shapes the VIEWs read, plus a stand-in for the
@@ -173,7 +175,7 @@ test("DRIFT GUARD: migration 082 embeds each rollup's VIEW DDL VERBATIM from rol
   }
 });
 
-test("DRIFT GUARD: migration 083 embeds each derived column VERBATIM from planReadModel.sqlSelectFor (the VIEW cannot drift from the declaration)", () => {
+test("DRIFT GUARD: migration 097 embeds each derived column VERBATIM from planReadModel.sqlSelectFor (the VIEW cannot drift from the declaration)", () => {
   const sql = MIG(READ_MODEL_MIGRATION);
   for (const col of PLAN_READ_MODEL_DERIVED) {
     const emitted = planReadModel.sqlSelectFor(col, { baseAlias: PLAN_READ_MODEL_BASE_ALIAS });
@@ -183,29 +185,27 @@ test("DRIFT GUARD: migration 083 embeds each derived column VERBATIM from planRe
         `from app/planReadModel.ts (or add a new superseding migration). Expected to contain:\n  ${emitted} AS ${col}`,
     );
   }
-  // DROP+CREATE that supersedes 080 and folds in (drops) the now-redundant intermediate VIEWs, keeping
+  // DROP+CREATE that supersedes 083's plan_read_model VIEW body (the terminal-dismiss #641 arm), keeping
   // every base column an aliased pass-through so the static pages↔schema contract guard still sees them.
-  assert(/DROP VIEW IF EXISTS plan_read_model;/.test(sql), "083 must DROP the superseded plan_read_model first");
-  assert(/DROP VIEW IF EXISTS plan_delivery;/.test(sql), "083 must fold in (drop) the retired plan_delivery");
-  assert(/DROP VIEW IF EXISTS plan_wave_label;/.test(sql), "083 must fold in (drop) the retired plan_wave_label");
-  assert(/CREATE VIEW plan_read_model AS/.test(sql), "083 must (re)create plan_read_model");
+  assert(/DROP VIEW IF EXISTS plan_read_model;/.test(sql), "097 must DROP the superseded plan_read_model first");
+  assert(/CREATE VIEW plan_read_model AS/.test(sql), "097 must (re)create plan_read_model");
   for (const base of ["plan_key", "repo", "issue_number", "title", "process_key", "epic_phase", "promotion_pr", "promotion_state"]) {
-    assert(sql.includes(`pl.${base} AS ${base}`), `083 must pass base column "${base}" through the VIEW`);
+    assert(sql.includes(`pl.${base} AS ${base}`), `097 must pass base column "${base}" through the VIEW`);
   }
   // The hand-authored display strings (D3 — no TS twin) live in this VIEW over the derived columns.
-  assert(sql.includes("AS delivery_label"), "083 must carry the hand-authored delivery_label display column");
-  assert(sql.includes("AS wave_label"), "083 must carry the hand-authored wave_label display column");
+  assert(sql.includes("AS delivery_label"), "097 must carry the hand-authored delivery_label display column");
+  assert(sql.includes("AS wave_label"), "097 must carry the hand-authored wave_label display column");
   // The FROM/JOIN relation names are DERIVED from the declaration (baseTable + each lookup's rollup name
   // + join keys), not hand-hardcoded — so renaming `baseTable` or a rollup `.name` (which would make 082
-  // create a different-named VIEW) breaks this guard instead of silently leaving 083 pointing at a
+  // create a different-named VIEW) breaks this guard instead of silently leaving 097 pointing at a
   // stale/missing relation.
   const alias = PLAN_READ_MODEL_BASE_ALIAS;
-  assert(sql.includes(`FROM ${planReadModel.decl.baseTable} ${alias}`), `083's FROM must be the declaration's baseTable "${planReadModel.decl.baseTable}" (aliased ${alias})`);
+  assert(sql.includes(`FROM ${planReadModel.decl.baseTable} ${alias}`), `097's FROM must be the declaration's baseTable "${planReadModel.decl.baseTable}" (aliased ${alias})`);
   for (const lk of planReadModel.decl.lookups) {
     const rollupName = lk.rollup.decl.name;
     const on = lk.on.map((k) => `${alias}.${k.base} = ${lk.as}.${k.rollup}`).join(" AND ");
     const join = `LEFT JOIN ${rollupName} ${lk.as} ON ${on}`;
-    assert(sql.includes(join), `083 must LEFT JOIN the declaration's "${rollupName}" lookup exactly as "${join}"`);
+    assert(sql.includes(join), `097 must LEFT JOIN the declaration's "${rollupName}" lookup exactly as "${join}"`);
   }
 });
 
@@ -352,18 +352,28 @@ test("the migration 083 VIEW IGNORES stale STORED list_bucket / ack_open columns
   assertEquals(row.ack_open, 0, "already acknowledged ⇒ no open Dismiss");
 });
 
-test("RED/GREEN #503: a DERIVE-ONLY terminated epic (base status frozen 'dispatched', derived_status='abandoned') drops out of Active with no worker write", () => {
+test("RED/GREEN #503 (+#641): a DERIVE-ONLY terminated epic (base status frozen 'dispatched', derived_status='abandoned') is classified off derived_status — Active+dismissable until acknowledged, then History", () => {
   // ADR-0065: cancel/terminate is DERIVE-ONLY — `plans__tracking.derived_status` recomputes `abandoned`
-  // on READ while the base `plans.status` stays frozen at its last transient. 083 classifies the bucket
-  // off `derived_status`, so a terminated epic renders History (not wedged Active) with no poller pass.
+  // on READ while the base `plans.status` stays frozen at its last transient. The bucket classifies off
+  // `derived_status`, so a terminated epic is handled on engine truth with no poller pass. Under #641
+  // (uniform acknowledge-to-dismiss) a terminated epic now STAYS Active with a Dismiss affordance until
+  // an operator ticks it off — mirroring features/PRs/DGs — rather than dropping straight to History.
   const db = viewDb();
   addPlan(db, "o/r#term", { status: "dispatched", stored: { list_bucket: "active" } });
   assertEquals(readModel(db, "o/r#term").list_bucket, "active", "precondition: a live dispatched epic is Active");
 
   db.prepare("UPDATE plans SET derived_status_override = 'abandoned' WHERE plan_key = ?").run("o/r#term");
   const row = readModel(db, "o/r#term");
-  assertEquals(row.list_bucket, "history", "a derive-only terminated epic is History (the #503 phantom fix)");
+  assertEquals(row.list_bucket, "active", "a derive-only terminated (unacknowledged) epic stays Active until dismissed (#641)");
+  assertEquals(row.ack_open, 1, "…and carries the Dismiss affordance");
   assertEquals(row.list_bucket, deriveEpicBucket("abandoned", row.delivery === "converging" ? "converging" : null, null), "list_bucket tracks derived_status via the VIEW");
+
+  // Acknowledging it (the operator tick-off) settles it to History — the derived_status-driven, no-
+  // worker-write resolution the #503 phantom fix guaranteed, now gated on an explicit dismiss.
+  db.prepare("UPDATE plans SET acknowledged_at = '2026-02-02T00:00:00Z' WHERE plan_key = ?").run("o/r#term");
+  const acked = readModel(db, "o/r#term");
+  assertEquals(acked.list_bucket, "history", "a dismissed terminated epic is History (classified off derived_status, no poller pass)");
+  assertEquals(acked.ack_open, 0, "…and its Dismiss affordance is retracted");
 });
 
 test("REGRESSION (Copilot #493): a DERIVE-ONLY terminated slice PR (base status frozen 'converging', derived_status='abandoned') is counted RESOLVED — the VIEW joins pull_requests__tracking.derived_status", () => {

package/app/planReadModel.ts

@@ -29,7 +29,9 @@
 // worker stamps its own BPMN element's phase) with no SQL twin — it is not a per-row function of the
 // plan row, so it stays hand-authored and out of this declaration.
 
-import { and, caseWhen, col, defineReadModel, type Expr, eq, gt, isNull, lit, not, or, type ReadModel, rcol, when } from "@nanobpm/urban";
+import { and, caseWhen, col, defineReadModel, type Expr, eq, gt, lit, not, or, type ReadModel, rcol, when } from "@nanobpm/urban";
+import { deriveAckOpenFromTerminal, deriveListBucketFromTerminal, terminalStatusIn } from "./listBucket.ts";
+import { PLAN_TERMINAL_STATUSES } from "./plan.ts";
 import { planDeliveryCounts, planWaveProgress } from "./planRollups.ts";
 
 /** The base table the read model reads: the auto-provisioned `plans__tracking` derived VIEW (ADR-0065,
@@ -61,7 +63,6 @@ export const EFFECTIVE_STATUS_COLUMN = "derived_status";
  * …)`'s call sites, which pass the base status. */
 const BASE_STATUS_COLUMN = "status";
 
-const ds = col(EFFECTIVE_STATUS_COLUMN);
 const bs = col(BASE_STATUS_COLUMN);
 
 /** The derived epic `delivery` signal — the byte-for-byte twin of the retired `plan_delivery` VIEW's
@@ -82,32 +83,37 @@ const delivery: Expr = caseWhen(
   lit(null),
 );
 
-/** The Active/History partition (`deriveEpicBucket`, app/delivery.ts) — the byte-for-byte twin of the
- * `plan_read_model` VIEW's bucket CASE (074/080). `active` while the epic is LIVE (planning/dispatched)
- * OR `done`-but-still-`converging` (genuinely working) OR `done`-but-unacknowledged (stay actionable
- * until dismissed); `history` once truly resolved (a `done` epic the operator acknowledged, or a
- * terminal non-`done` status). Classifies the status arms on the terminal-folded `derived_status` so a
- * cancelled epic falls to History; the `converging` arm reuses the {@link delivery} sub-expression
- * (base-status-derived) so the two columns can't disagree. */
-const listBucket: Expr = caseWhen(
-  [
-    when(or(eq(ds, lit("planning")), eq(ds, lit("dispatched"))), lit("active")),
-    when(and(eq(ds, lit("done")), eq(delivery, lit("converging"))), lit("active")),
-    when(and(eq(ds, lit("done")), isNull(col("acknowledged_at"))), lit("active")),
-    when(eq(ds, lit("done")), lit("history")),
-  ],
-  lit("history"),
+/** The epic's "dismissable-terminal" predicate — terminal AND actually tick-off-able: the epic's
+ * terminal-folded `derived_status` is in {@link PLAN_TERMINAL_STATUSES} (`done`/`failed`/`abandoned`)
+ * AND its fan-out is NOT still `converging`. This is the epic-specific refinement the shared oracle
+ * (app/listBucket.ts) takes: a `done`-but-still-`converging` epic is terminal by status yet must NOT be
+ * dismissable mid-flight (a stray/premature ack must not drag it to History) — PRs/Delivery-Graphs have
+ * no such mid-flight terminal, so their predicate is just "terminal". `not(eq(delivery, 'converging'))`
+ * is the null-safe `delivery IS NOT 'converging'` (a NULL/`landed` delivery ⇒ resolved ⇒ dismissable)
+ * under the shared "NULL → false" rule. */
+const dismissableTerminal: Expr = and(
+  terminalStatusIn(EFFECTIVE_STATUS_COLUMN, PLAN_TERMINAL_STATUSES),
+  not(eq(delivery, lit("converging"))),
 );
 
-/** The operator "Dismiss" (acknowledge) affordance flag (`epicIsAcknowledgeable` ∧ unacknowledged) —
- * the byte-for-byte twin of the `plan_read_model` VIEW's `ack_open` CASE (074/080): `1` iff the epic is
- * `done`, its fan-out has RESOLVED (`delivery` is not `converging`), and it is not yet acknowledged;
- * else `0`. `not(eq(delivery, 'converging'))` matches the VIEW's null-safe `d.delivery IS NOT
- * 'converging'` (a NULL delivery ⇒ resolved ⇒ acknowledgeable) under the shared "NULL → false" rule. */
-const ackOpen: Expr = caseWhen(
-  [when(and(eq(ds, lit("done")), not(eq(delivery, lit("converging"))), isNull(col("acknowledged_at"))), lit(1))],
-  lit(0),
-);
+/** The Active/History partition (`deriveEpicBucket`, app/delivery.ts) — the ONE shared oracle
+ * (app/listBucket.ts, issue #641) over the epic's {@link dismissableTerminal} predicate, so every
+ * "Active …" grid partitions with the identical acknowledge-to-dismiss rule: `history` IFF the epic is
+ * dismissable-terminal AND acknowledged; otherwise `active` (live `planning`/`dispatched` epics, a
+ * `done`-but-still-`converging` epic — terminal but not dismissable mid-flight, so it stays active — and
+ * the #641 gap this closes: a terminal-non-`done` `failed`/`abandoned` epic that is UNACKNOWLEDGED,
+ * which before fell straight to History skipping the tick-off). Classifies on the terminal-folded
+ * `derived_status` so a cancelled epic is handled on engine truth. */
+const listBucket: Expr = deriveListBucketFromTerminal(dismissableTerminal);
+
+/** The operator "Dismiss" (acknowledge) affordance flag (`epicIsAcknowledgeable` ∧ unacknowledged):
+ * `1` iff the epic is {@link dismissableTerminal} and not yet acknowledged; else `0`. Shares the exact
+ * predicate with {@link listBucket} (a row is dismissable precisely while it would still be `active` on
+ * the terminal branch). Extended from `done`-only to the full terminal set for #641: a `failed`/
+ * `abandoned` epic (whose `delivery` is always non-`converging`) is now dismissable too, so the
+ * terminal-non-`done` arm of {@link listBucket} has a Dismiss affordance to move it to History —
+ * mirroring features/PRs/DGs. */
+const ackOpen: Expr = deriveAckOpenFromTerminal(dismissableTerminal);
 
 /** The wave frontier columns — bare pass-throughs of the `plan_wave_progress` rollup lookup (a
  * taskless plan has no rollup row, so the LEFT-JOIN miss reads NULL, matching the workers' behaviour).

package/app/pullRequestReadModel.test.ts

@@ -0,0 +1,208 @@
+// Read-model coverage for the Convergence (PRs) Active/History projection — the declared `list_bucket`
+// (active/history) + `ack_open` (the Dismiss affordance flag) that give the PR surfaces the SAME
+// acknowledge-to-dismiss behaviour Features/Epics/Delivery-Graphs already have, authored via Urban's
+// ADR-0065 declare-once primitive (app/pullRequestReadModel.ts). Issue #641; the exemplars are
+// app/featureReadModel.test.ts and app/deliveryGraphReadModel.test.ts.
+//
+// Guards:
+//   1. DRIFT GUARD — migration 094 embeds each derived column VERBATIM from
+//      `pullRequestReadModel.sqlSelectFor(...)` and passes EVERY base column through, so the checked-in
+//      VIEW cannot drift from the declaration.
+//   2. FRAMEWORK PARITY GUARD — `assertReadModelParity` proves the SQL and TS lowerings the ONE
+//      declaration compiles to agree over the status × acknowledged matrix.
+//   3. END-TO-END BEHAVIOUR on the REAL migration VIEW (094 applied to an in-memory DB): a live PR is
+//      active with no Dismiss; a terminal-but-unacknowledged PR STAYS active and offers Dismiss; once
+//      acknowledged it drops to History; an out-of-band-terminated PR classifies on engine truth.
+//   4. PAGE BINDINGS — the Convergence surfaces (overview + home) bind the derived VIEW and bucket on
+//      the derived `list_bucket`, not a base-`status` allowlist over the raw `pull_requests` table.
+
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertReadModelParity, type ParityDb, type ParitySample } from "@nanobpm/urban";
+import { assert, assertEquals } from "#test-assert";
+import { applyMigrationSet, readMigrationSetFromDisk } from "../test/migrations.ts";
+import {
+  PR_TERMINAL_STATUSES,
+  PULL_REQUEST_READ_MODEL_BASE_ALIAS,
+  PULL_REQUEST_READ_MODEL_DERIVED,
+  pullRequestReadModel,
+} from "./pullRequestReadModel.ts";
+
+const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
+const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
+
+const READ_MODEL_MIGRATION = "094_pull_requests_read_model.sql";
+
+// The real base `pull_requests` columns, in schema order — DERIVED from the migration chain (not a
+// hand-kept list that could silently omit one), used by both the drift guard and the e2e stand-in.
+function baseColumns(): string[] {
+  const db = new DatabaseSync(":memory:");
+  applyMigrationSet(db, readMigrationSetFromDisk());
+  const cols = (db.prepare("PRAGMA table_info(pull_requests)").all() as { name: string }[]).map((r) => r.name);
+  db.close();
+  return cols;
+}
+
+// A minimal in-memory DB carrying the base `pull_requests` shape the VIEW reads, plus a stand-in for
+// the managed `pull_requests__tracking` derived VIEW urban provisions at mount (re-exporting `pr.*`
+// plus the terminal-folded `derived_status`). `derived_status_override` models the reconciler's
+// `onTerminated` edge (a terminated instance ⇒ `abandoned` while base `status` stays frozen). Then
+// migration 094 (the read model VIEW) is applied on top.
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  const cols = baseColumns().filter((c) => c !== "pr_key");
+  db.exec(
+    `CREATE TABLE pull_requests (
+       pr_key TEXT PRIMARY KEY,
+       ${cols.map((c) => `${c} TEXT`).join(",\n       ")},
+       derived_status_override TEXT);
+     CREATE VIEW pull_requests__tracking AS
+       SELECT p.*, COALESCE(p.derived_status_override, p.status) AS derived_status FROM pull_requests p;`,
+  );
+  db.exec(MIG(READ_MODEL_MIGRATION));
+  return db;
+}
+
+function addPr(
+  db: DatabaseSync,
+  pr_key: string,
+  opts: { status: string; acknowledged_at?: string | null; derived_status_override?: string | null },
+): void {
+  db.prepare(
+    "INSERT INTO pull_requests (pr_key, status, acknowledged_at, derived_status_override) VALUES (?, ?, ?, ?)",
+  ).run(pr_key, opts.status, opts.acknowledged_at ?? null, opts.derived_status_override ?? null);
+}
+
+function bucket(db: DatabaseSync, pr_key: string): { list_bucket: string; ack_open: number; status: string } {
+  const r = db
+    .prepare("SELECT list_bucket, ack_open, status FROM pull_requests_read_model WHERE pr_key = ?")
+    .get(pr_key) as { list_bucket: string; ack_open: number; status: string };
+  return { list_bucket: r.list_bucket, ack_open: r.ack_open, status: r.status };
+}
+
+function parityDb(db: DatabaseSync): ParityDb {
+  return {
+    exec: (sql) => db.exec(sql),
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) => db.prepare(sql).all(...(params as never[])) as T[],
+    run: (sql, params: unknown[] = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+  };
+}
+
+// ── 1. DRIFT GUARD ────────────────────────────────────────────────────────────────────────────────
+
+test("DRIFT GUARD: migration 094 embeds each derived column VERBATIM from pullRequestReadModel.sqlSelectFor (the VIEW cannot drift from the declaration)", () => {
+  const sql = MIG(READ_MODEL_MIGRATION);
+  const alias = PULL_REQUEST_READ_MODEL_BASE_ALIAS;
+  for (const c of PULL_REQUEST_READ_MODEL_DERIVED) {
+    const emitted = pullRequestReadModel.sqlSelectFor(c, { baseAlias: alias });
+    assert(
+      sql.includes(`${emitted} AS ${c}`),
+      `migration ${READ_MODEL_MIGRATION} no longer embeds the declaration's SQL for "${c}" — regenerate it from ` +
+        `app/pullRequestReadModel.ts. Expected to contain:\n  ${emitted} AS ${c}`,
+    );
+  }
+  assert(/DROP VIEW IF EXISTS pull_requests_read_model;/.test(sql), "094 must DROP the VIEW first");
+  assert(/CREATE VIEW pull_requests_read_model AS/.test(sql), "094 must (re)create pull_requests_read_model");
+  // Base identity pass-throughs — DERIVED from the REAL `pull_requests` schema, NOT a hand-kept list:
+  // the VIEW must re-export EVERY base column so the static pages↔schema contract guard sees them (and a
+  // future regeneration can't drop one without failing here). `status` is the one exception — exposed as
+  // the effective COALESCE below, not a bare pass-through — so it is asserted separately.
+  const cols = baseColumns();
+  assert(cols.length > 0, "the migration chain must create the pull_requests base table");
+  for (const base of cols) {
+    if (base === "status") continue;
+    assert(sql.includes(`pr.${base} AS ${base}`), `094 must pass base column "${base}" through the VIEW (derived from the real pull_requests schema)`);
+  }
+  assert(sql.includes("COALESCE(pr.derived_status, pr.status) AS status"), "094 must expose the effective status so the pages' Status cell + any status reader track a terminated PR");
+  assert(sql.includes(`FROM ${pullRequestReadModel.decl.baseTable} ${alias}`), `094's FROM must be the declaration's baseTable "${pullRequestReadModel.decl.baseTable}"`);
+});
+
+// ── 2. FRAMEWORK PARITY GUARD ──────────────────────────────────────────────────────────────────────
+
+test("FRAMEWORK PARITY GUARD: pullRequestReadModel's SQL and TS lowerings agree over the status × acknowledged matrix (assertReadModelParity)", () => {
+  const samples: ParitySample[] = [];
+  for (const status of ["waiting_review", "converging", "merged", "converged", "abandoned", "closed", "failed"]) {
+    for (const derived_status of [status, "abandoned"]) {
+      for (const acknowledged_at of [null, "2026-02-02T00:00:00Z"]) {
+        samples.push({ baseRow: { pr_key: "self", status, derived_status, acknowledged_at }, lookups: {} });
+      }
+    }
+  }
+  const db = new DatabaseSync(":memory:");
+  assertReadModelParity(pullRequestReadModel, parityDb(db), samples, { sql: { baseAlias: PULL_REQUEST_READ_MODEL_BASE_ALIAS } });
+  db.close();
+});
+
+// ── 3. END-TO-END BEHAVIOUR on the real migration VIEW ────────────────────────────────────────────
+
+test("ACKNOWLEDGE-TO-DISMISS: a live PR is active with no Dismiss; a terminal-but-unacknowledged PR STAYS active + offers Dismiss; once acknowledged it drops to history", () => {
+  const db = viewDb();
+  // Live (in-flight convergence states) — active, no dismiss.
+  addPr(db, "live-review", { status: "waiting_review" });
+  addPr(db, "live-conv", { status: "converging" });
+  // Terminal, not yet dismissed — the uniform rule keeps each ACTIVE (not History) with the Dismiss flag.
+  for (const s of PR_TERMINAL_STATUSES) addPr(db, `term-${s}`, { status: s });
+  // Terminal AND acknowledged — dropped to History, Dismiss retracted.
+  addPr(db, "merged-ack", { status: "merged", acknowledged_at: "2026-03-03T00:00:00Z" });
+  // Derive-only terminated (base frozen at an in-flight status, engine truth 'abandoned'), unacknowledged.
+  addPr(db, "derive-term", { status: "converging", derived_status_override: "abandoned" });
+  // A stray ack on a still-live PR must NOT drag it to History (ack only bites once terminal).
+  addPr(db, "live-stray-ack", { status: "converging", acknowledged_at: "2026-03-03T00:00:00Z" });
+
+  assertEquals(bucket(db, "live-review"), { list_bucket: "active", ack_open: 0, status: "waiting_review" });
+  assertEquals(bucket(db, "live-conv"), { list_bucket: "active", ack_open: 0, status: "converging" });
+  for (const s of PR_TERMINAL_STATUSES) {
+    assertEquals(bucket(db, `term-${s}`), { list_bucket: "active", ack_open: 1, status: s });
+  }
+  assertEquals(bucket(db, "merged-ack"), { list_bucket: "history", ack_open: 0, status: "merged" });
+  assertEquals(bucket(db, "derive-term"), { list_bucket: "active", ack_open: 1, status: "abandoned" });
+  assertEquals(bucket(db, "live-stray-ack"), { list_bucket: "active", ack_open: 0, status: "converging" });
+  db.close();
+});
+
+// ── 4. PAGE BINDINGS ──────────────────────────────────────────────────────────────────────────────
+
+function grids(page: unknown): Array<Record<string, unknown>> {
+  const out: Array<Record<string, unknown>> = [];
+  const walk = (node: unknown): void => {
+    if (Array.isArray(node)) return node.forEach(walk);
+    if (node && typeof node === "object") {
+      const o = node as Record<string, unknown>;
+      if (o.type === "dataGrid") out.push(o);
+      for (const v of Object.values(o)) walk(v);
+    }
+  };
+  walk(page);
+  return out;
+}
+
+for (const { pageName, title } of [
+  { pageName: "overview.page.json", title: "Active PR convergences" },
+  { pageName: "home.page.json", title: "Pull requests" },
+]) {
+  test(`${pageName} '${title}' grid binds the derived pull_requests_read_model VIEW and buckets on list_bucket (not a base-status allowlist over the raw table)`, () => {
+    const page = PAGE(pageName);
+    const grid = grids(page).find((g) => (g.props as Record<string, unknown>)?.title === title);
+    assert(grid, `${pageName} must carry the "${title}" grid`);
+    const props = grid.props as Record<string, unknown>;
+    const data = props.data as Record<string, unknown>;
+    assertEquals(data.table, "pull_requests_read_model");
+
+    // Every activeness filter (main + tabs) buckets on `list_bucket`; none re-encodes a base-status allowlist.
+    const tabs = (Array.isArray(props.tabs) ? props.tabs : []) as Array<Record<string, unknown>>;
+    const filters = [data.filter, ...tabs.map((t) => t.filter)].filter(Array.isArray) as Array<Array<Record<string, unknown>>>;
+    let sawListBucket = false;
+    for (const f of filters) {
+      for (const pred of f) {
+        assert(pred.field !== "status", `${pageName} "${title}" must not filter a base-status allowlist — bucket on list_bucket`);
+        if (pred.field === "list_bucket") sawListBucket = true;
+      }
+    }
+    assert(sawListBucket, `${pageName} "${title}" must filter the derived list_bucket`);
+  });
+}

package/app/pullRequestReadModel.ts

@@ -0,0 +1,76 @@
+// The `pull_requests_read_model` derived read model — DECLARED ONCE and compiled to BOTH backends via
+// Urban's ADR-0065 reconciling-read-model primitive (`defineReadModel`, `@nanobpm/urban`). The
+// exemplars are app/featureReadModel.ts / app/deliveryGraphReadModel.ts; this is the Convergence-PR
+// twin (issue #641).
+//
+// WHY IT EXISTS. Before #641 the Convergence (PRs) surfaces — Overview's "Active PR convergences" and
+// home's "Pull requests" — filtered the RAW `pull_requests` table on a hand-synced base-`status`
+// allowlist (the 7 in-flight convergence states), so a PR dropped out of Active the instant its
+// `status` reached a terminal state, with NO operator dismiss. That is the last-but-one base-`status`
+// allowlist #637 set out to retire. This model gives PRs the SAME acknowledge-to-dismiss behaviour as
+// Features/Epics/Delivery-Graphs: a terminal PR STAYS in Active until an operator dismisses it
+// (`acknowledgePr` stamps `acknowledged_at`), then drops to History — the derived `list_bucket`
+// (app/listBucket.ts, the ONE shared oracle) is the single activeness predicate every "Active …" grid
+// now filters.
+//
+// BASE TABLE. Reads the auto-provisioned `pull_requests__tracking` derived VIEW (ADR-0065), NOT the raw
+// `pull_requests` table: it re-exports `pull_requests.*` plus a terminal-folded `derived_status` (the
+// `instanceTracking` reconciler's `onTerminated → abandoned` edge, recomputed on read), so a
+// terminated PR classifies on ENGINE TRUTH — exactly as `feature_read_model` reads
+// `feature_runs__tracking`.
+
+import { defineReadModel, type Expr, type ReadModel } from "@nanobpm/urban";
+import { deriveAckOpenExpr, deriveListBucketExpr } from "./listBucket.ts";
+
+/** The base table the read model reads: the auto-provisioned `pull_requests__tracking` derived VIEW
+ * (ADR-0065), NOT the raw `pull_requests` table — so the status-classifying derivations read the
+ * terminal-folded `derived_status` and a terminated PR drops to History with no worker write. */
+export const PULL_REQUEST_READ_MODEL_BASE_TABLE = "pull_requests__tracking";
+
+/** The base alias the managed VIEW gives `pull_requests__tracking` — pinned so the emitted derived-
+ * column SQL (`pr."col"`) matches the migration exactly (the drift guard compares against this alias). */
+export const PULL_REQUEST_READ_MODEL_BASE_ALIAS = "pr";
+
+/** The effective (terminal-folded) status column the bucket/ack derivations classify on — the tracking
+ * VIEW's `derived_status`. Single source of truth for the name so the derivations can't drift from it. */
+export const EFFECTIVE_STATUS_COLUMN = "derived_status";
+
+/** The PR statuses that are TERMINAL for the Active/History partition (issue #641). A PR in any of
+ * these has finished its convergence/merge lifecycle: `merged` (landed), `converged` (review-only
+ * consensus, no auto-merge), `abandoned` (cancelled / out-of-band terminated — the reconciler's
+ * `onTerminated` edge), `closed` (the PR was closed on GitHub without merging), `failed` (a terminal
+ * merge/convergence failure). Distinct from `deliveryStatuses.ts`'s `TERMINAL_STATUSES` (the epic-
+ * delivery in-flight fold, which counts `converged`/`merged`/`abandoned` only): this is the FULL PR
+ * terminal tier the acknowledge-to-dismiss rule folds to History. */
+export const PR_TERMINAL_STATUSES: readonly string[] = ["merged", "converged", "abandoned", "closed", "failed"];
+
+/** The Active/History partition — `history` IFF the PR is terminal AND acknowledged, else `active`
+ * (live PRs + terminal-but-UNACKNOWLEDGED PRs that stay actionable until dismissed). The ONE shared
+ * oracle (app/listBucket.ts) parameterised by {@link PR_TERMINAL_STATUSES}. */
+const listBucket: Expr = deriveListBucketExpr(EFFECTIVE_STATUS_COLUMN, PR_TERMINAL_STATUSES);
+
+/** The operator "Dismiss" affordance flag — `1` IFF the PR is terminal AND not yet acknowledged (so the
+ * page's `showWhenField` Dismiss button renders only for a terminal-but-unacknowledged PR), else `0`. */
+const ackOpen: Expr = deriveAckOpenExpr(EFFECTIVE_STATUS_COLUMN, PR_TERMINAL_STATUSES);
+
+/** The keys of {@link pullRequestReadModel}'s DERIVED columns, in the order the migration emits them.
+ * Base columns are identity pass-throughs (not derivations) and are listed in the migration directly. */
+export const PULL_REQUEST_READ_MODEL_DERIVED = ["list_bucket", "ack_open"] as const;
+export type PullRequestReadModelDerivedColumn = (typeof PULL_REQUEST_READ_MODEL_DERIVED)[number];
+
+/**
+ * The declare-once `pull_requests_read_model` derived columns. `selectBaseColumns: false` because the
+ * base columns are plain identity pass-throughs enumerated in the migration (so the static
+ * pages↔schema contract guard, which reads a VIEW's columns off an aliased select-list, sees them).
+ * Both the migration VIEW (`sqlSelectFor`, drift-guarded) and the runtime TS oracle (`fnFor`) are
+ * generated from THIS single declaration.
+ */
+export const pullRequestReadModel: ReadModel = defineReadModel({
+  name: "pull_requests_read_model",
+  baseTable: PULL_REQUEST_READ_MODEL_BASE_TABLE,
+  selectBaseColumns: false,
+  derive: {
+    list_bucket: listBucket,
+    ack_open: ackOpen,
+  },
+});

package/db/migrations/093_pull_requests_acknowledged_at.sql

@@ -0,0 +1,30 @@
+-- Convergence (PRs): add the `acknowledged_at` dismissal stamp + backfill currently-terminal rows
+-- (issue #641). This is the PR half of making all four "Active …" grids behave uniformly — a row STAYS
+-- in Active until an operator dismisses it (acknowledge-to-dismiss), then drops to History — completing
+-- the direction set in #637 by retiring the last two base-`status` allowlists (Convergence + Delivery
+-- Graphs). The twin stamp already exists on `feature_runs` (073) and `plans` (074).
+--
+-- BACKFILL IS MANDATORY (the highest-risk item). Merlin carries hundreds of already-terminal PRs (~411
+-- merged + 35 abandoned + 5 converged at authoring). Without the backfill, repointing the Active grids
+-- at the derived `list_bucket` (094) — which folds an UNACKNOWLEDGED terminal PR into `active` — would
+-- dump every one of those historical PRs into Active on the next boot. So we stamp `acknowledged_at` on
+-- every CURRENTLY-terminal row here: they load in History from day one, and only PRs that reach a
+-- terminal state AFTER this migration require an operator dismiss (their `acknowledged_at` stays NULL
+-- until `acknowledgePr`). Stamp = COALESCE(merged_at, converged_at, updated_at): the best available
+-- "when it settled" timestamp, and `updated_at` is NOT NULL so the stamp is never NULL for a matched
+-- row.
+--
+-- Terminal set = the PR terminal tier {merged, converged, abandoned, closed, failed}
+-- (app/pullRequestReadModel.ts `PR_TERMINAL_STATUSES`). Classified on the base `status` (the stored
+-- ground truth at migration time; the reconciler's `derived_status` is a read-time projection). The
+-- `acknowledged_at IS NULL` guard keeps the backfill idempotent — re-running never re-stamps a row an
+-- operator later dismissed with a different timestamp.
+--
+-- The runner wraps each file in its own transaction — no BEGIN/COMMIT here. Numbered after 092.
+
+ALTER TABLE pull_requests ADD COLUMN acknowledged_at TEXT;
+
+UPDATE pull_requests
+   SET acknowledged_at = COALESCE(merged_at, converged_at, updated_at)
+ WHERE acknowledged_at IS NULL
+   AND status IN ('merged', 'converged', 'abandoned', 'closed', 'failed');

package/db/migrations/094_pull_requests_read_model.sql

@@ -0,0 +1,65 @@
+-- Convergence (PRs) read model: DECLARE ONCE, compile to BOTH backends (ADR-0065, nano-ide#452) — the
+-- `pull_requests_read_model` VIEW that gives the Convergence surfaces the SAME acknowledge-to-dismiss
+-- Active/History partition Features/Epics/Delivery-Graphs already have (issue #641).
+--
+-- Before #641 the Overview "Active PR convergences" and home "Pull requests" grids filtered the RAW
+-- `pull_requests` table on a hand-synced base-`status` allowlist (the 7 in-flight convergence states),
+-- so a PR dropped out of Active the instant its `status` reached terminal, with NO operator dismiss —
+-- the last-but-one base-`status` allowlist #637 set out to retire. This VIEW introduces a declared
+-- `list_bucket` (active/history) + `ack_open` (the Dismiss affordance flag) derived from the ONE shared
+-- oracle (app/listBucket.ts): a terminal PR STAYS in `active` until `acknowledged_at` is stamped
+-- (`acknowledgePr`), then folds to `history`.
+--
+-- Every DERIVED column below is emitted VERBATIM from the ONE declaration in
+-- app/pullRequestReadModel.ts (`pullRequestReadModel.sqlSelectFor(col, { baseAlias: "pr" })`), which
+-- ALSO drives the runtime TS via `fnFor` — the two lowerings fall out of the same closed-DSL AST and
+-- cannot diverge. A drift guard (app/pullRequestReadModel.test.ts) fails if this file stops matching the
+-- declaration, and `assertReadModelParity` proves the SQL and TS lowerings agree.
+--
+-- SEMANTICS. The status-classifying `list_bucket`/`ack_open` read the terminal-folded `derived_status`
+-- off the auto-provisioned `pull_requests__tracking` derived VIEW (ADR-0065), so an out-of-band-
+-- terminated PR classifies on ENGINE TRUTH (`abandoned`) rather than a frozen base `status`. Base
+-- columns stay aliased identity pass-throughs (so the static pages↔schema contract guard sees the
+-- VIEW's columns), sourced off `pull_requests__tracking`'s re-export of the base `pull_requests.*`;
+-- `status` is exposed as the effective `COALESCE(derived_status, status)` so the pages' Status cell and
+-- any status reader track a terminated PR. `acknowledged_at` (093) passes through so the read model can
+-- classify on it.
+--
+-- Forward-only VIEW definition (DROP then CREATE). `pull_requests__tracking` is the managed VIEW urban
+-- provisions at mount; SQLite does not validate a view body at CREATE time, so this migration (which
+-- runs before that mount) is created fine and resolves once the managed VIEW exists. The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after 093.
+
+DROP VIEW IF EXISTS pull_requests_read_model;
+
+CREATE VIEW pull_requests_read_model AS
+SELECT
+  pr.pr_key AS pr_key,
+  pr.repo AS repo,
+  pr.number AS number,
+  pr.url AS url,
+  pr.title AS title,
+  COALESCE(pr.derived_status, pr.status) AS status,
+  pr.current_round AS current_round,
+  pr.process_key AS process_key,
+  pr.waiting_since AS waiting_since,
+  pr.last_review_id AS last_review_id,
+  pr.outcome AS outcome,
+  pr.created_at AS created_at,
+  pr.updated_at AS updated_at,
+  pr.converged_at AS converged_at,
+  pr.merged_at AS merged_at,
+  pr.active_worker AS active_worker,
+  pr.lease_until AS lease_until,
+  pr.last_nudge_at AS last_nudge_at,
+  pr.fresh_head_run_head AS fresh_head_run_head,
+  pr.abandon_token AS abandon_token,
+  pr.incident_key AS incident_key,
+  pr.incident_message AS incident_message,
+  pr.last_round_head AS last_round_head,
+  pr.root_request_key AS root_request_key,
+  pr.epic_phase_label AS epic_phase_label,
+  pr.acknowledged_at AS acknowledged_at,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND (NOT COALESCE(COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM pull_requests__tracking pr;

package/db/migrations/095_delivery_graph_acknowledged_at.sql

@@ -0,0 +1,24 @@
+-- Delivery Graphs: add the `acknowledged_at` dismissal stamp + backfill currently-terminal runs (issue
+-- #641). The Delivery-Graph half of the uniform acknowledge-to-dismiss behaviour (see 093 for the PR
+-- half and the rationale): a terminal run STAYS in Active until an operator dismisses it, then drops to
+-- History — retiring the `status IN ('awaiting-approval','running')` allowlist the pages filtered.
+--
+-- BACKFILL (mandatory, same risk as 093). Repointing the Active grids at the derived `list_bucket`
+-- (096) folds an UNACKNOWLEDGED terminal run into `active`, so without a backfill every historical
+-- terminal run would flood Active on boot. Stamp `acknowledged_at = updated_at` (a delivery-graph run
+-- has no merged/converged timestamp; `updated_at` is its last-touch and is NOT NULL) on every currently-
+-- terminal run so they load in History, and only runs that reach terminal AFTER this migration require
+-- an operator dismiss.
+--
+-- Terminal set = {done, failed, abandoned} (app/deliveryGraphRun.ts `DELIVERY_GRAPH_TERMINAL_STATUSES`).
+-- Classified on the base `status` (the stored ground truth at migration time). The `acknowledged_at IS
+-- NULL` guard keeps the backfill idempotent.
+--
+-- The runner wraps each file in its own transaction — no BEGIN/COMMIT here. Numbered after 094.
+
+ALTER TABLE delivery_graph_runs ADD COLUMN acknowledged_at TEXT;
+
+UPDATE delivery_graph_runs
+   SET acknowledged_at = updated_at
+ WHERE acknowledged_at IS NULL
+   AND status IN ('done', 'failed', 'abandoned');