@nanobpm/nano-workforce 0.166.0 → 0.167.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.167.0](https://github.com/nanobpm/nano-workforce/compare/v0.166.0...v0.167.0) (2026-08-31)
+
+### Features
+
+* **active-lists:** uniform active-until-dismissed for PRs, delivery graphs & epics ([#649](https://github.com/nanobpm/nano-workforce/issues/649)) ([9ac7135](https://github.com/nanobpm/nano-workforce/commit/9ac71353335d0c09e9959826d71d5c796e364da1)), closes [#637](https://github.com/nanobpm/nano-workforce/issues/637)
+
 ## [0.166.0](https://github.com/nanobpm/nano-workforce/compare/v0.165.0...v0.166.0) (2026-08-31)
 
 ### Features

package/app/backfillAcknowledgedAt.test.ts

@@ -0,0 +1,121 @@
+// Backfill coverage for the acknowledge-to-dismiss migrations (issue #641). The HIGHEST-RISK item:
+// repointing the four "Active …" grids at the derived `list_bucket` — which folds an UNACKNOWLEDGED
+// terminal row into `active` — would flood every historical terminal PR / delivery-graph run into
+// Active on the next boot. Migrations 093 (PRs) and 095 (delivery graphs) prevent that by stamping
+// `acknowledged_at` on every CURRENTLY-terminal row, so they load in History from day one, while rows
+// that reach terminal AFTER the migration stay in Active until an operator dismisses them.
+//
+// This test reproduces the real upgrade path: apply the migration chain UP TO (but not including) the
+// `acknowledged_at` additions, seed pre-existing rows the way a live DB carries them (terminal + live,
+// NO acknowledged_at column yet), then apply the remaining migrations (093/094/095/096/097 …) and read
+// the derived read-model VIEWs to prove the resulting Active/History partition.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { applyMigrationSet, readMigrationSetFromDisk } from "../test/migrations.ts";
+
+// The pre-`acknowledged_at` schema slice (everything numbered below 093, lexically) — the base
+// `pull_requests` (001) and `delivery_graph_runs` (058) tables exist here, WITHOUT the dismissal stamp.
+function migrationsBefore093() {
+  return readMigrationSetFromDisk().filter((f) => f.name < "093");
+}
+
+function backfillDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  const files = readMigrationSetFromDisk();
+  // Phase 1: schema as it stood before the dismissal stamp.
+  applyMigrationSet(db, migrationsBefore093());
+
+  // Seed pre-existing rows exactly as a live DB carries them — no acknowledged_at column yet.
+  const insPr = (pr_key: string, status: string) =>
+    db
+      .prepare(
+        "INSERT INTO pull_requests (pr_key, repo, number, url, status, created_at, updated_at, merged_at) VALUES (?, 'o/r', 1, 'https://x', ?, '2025-01-01T00:00:00Z', '2025-06-01T00:00:00Z', ?)",
+      )
+      .run(pr_key, status, status === "merged" ? "2025-06-01T00:00:00Z" : null);
+  // Terminal (must backfill → History) + live (must stay Active).
+  for (const s of ["merged", "converged", "abandoned", "closed", "failed"]) insPr(`pre-${s}`, s);
+  insPr("pre-live", "converging");
+
+  const insDg = (run_key: string, status: string) =>
+    db
+      .prepare(
+        "INSERT INTO delivery_graph_runs (run_key, digest, status, created_at, updated_at) VALUES (?, 'dig', ?, '2025-01-01T00:00:00Z', '2025-06-01T00:00:00Z')",
+      )
+      .run(run_key, status);
+  for (const s of ["done", "failed", "abandoned"]) insDg(`pre-${s}`, s);
+  insDg("pre-live", "running");
+
+  // Phase 2: apply the remaining migrations — 093/095 add the column + backfill the pre-existing
+  // terminal rows, 094/096 (re)create the read-model VIEWs. applyMigrationSet skips the already-applied.
+  applyMigrationSet(db, files);
+
+  // Stand-ins for the managed `<table>__tracking` derived VIEWs urban provisions at mount (pass-through
+  // `derived_status := base.status`, modelling settled rows) — the read-model VIEWs read these.
+  db.exec(
+    `CREATE VIEW pull_requests__tracking AS SELECT p.*, p.status AS derived_status FROM pull_requests p;
+     CREATE VIEW delivery_graph_runs__tracking AS SELECT d.*, d.status AS derived_status FROM delivery_graph_runs d;`,
+  );
+
+  // A row that reaches terminal AFTER the migration — acknowledged_at stays NULL, so it must stay Active.
+  db.prepare(
+    "INSERT INTO pull_requests (pr_key, repo, number, url, status, created_at, updated_at) VALUES ('post-merged', 'o/r', 2, 'https://y', 'merged', '2026-01-01T00:00:00Z', '2026-01-01T00:00:00Z')",
+  ).run();
+  db.prepare(
+    "INSERT INTO delivery_graph_runs (run_key, digest, status, created_at, updated_at) VALUES ('post-done', 'dig', 'done', '2026-01-01T00:00:00Z', '2026-01-01T00:00:00Z')",
+  ).run();
+  return db;
+}
+
+function prBucket(db: DatabaseSync, pr_key: string) {
+  return db.prepare("SELECT list_bucket, ack_open, acknowledged_at FROM pull_requests_read_model WHERE pr_key = ?").get(pr_key) as {
+    list_bucket: string;
+    ack_open: number;
+    acknowledged_at: string | null;
+  };
+}
+function dgBucket(db: DatabaseSync, run_key: string) {
+  return db.prepare("SELECT list_bucket, ack_open, acknowledged_at FROM delivery_graph_read_model WHERE run_key = ?").get(run_key) as {
+    list_bucket: string;
+    ack_open: number;
+    acknowledged_at: string | null;
+  };
+}
+
+test("migration 093 backfill: every pre-existing terminal PR loads in History (acknowledged_at stamped); a live PR stays Active; a post-migration terminal PR stays Active until dismissed", () => {
+  const db = backfillDb();
+  for (const s of ["merged", "converged", "abandoned", "closed", "failed"]) {
+    const b = prBucket(db, `pre-${s}`);
+    assert(b.acknowledged_at !== null, `pre-existing terminal PR (${s}) must be backfilled with acknowledged_at`);
+    assertEquals(b.list_bucket, "history", `pre-existing terminal PR (${s}) must load in History`);
+    assertEquals(b.ack_open, 0);
+  }
+  // A live PR was never terminal → not backfilled → Active, no Dismiss.
+  const live = prBucket(db, "pre-live");
+  assertEquals(live.acknowledged_at, null);
+  assertEquals(live.list_bucket, "active");
+  // A PR that settled AFTER the migration is NOT auto-dismissed — stays Active with the Dismiss flag.
+  const post = prBucket(db, "post-merged");
+  assertEquals(post.acknowledged_at, null);
+  assertEquals(post.list_bucket, "active");
+  assertEquals(post.ack_open, 1);
+  db.close();
+});
+
+test("migration 095 backfill: every pre-existing terminal delivery-graph run loads in History; a live run stays Active; a post-migration terminal run stays Active until dismissed", () => {
+  const db = backfillDb();
+  for (const s of ["done", "failed", "abandoned"]) {
+    const b = dgBucket(db, `pre-${s}`);
+    assert(b.acknowledged_at !== null, `pre-existing terminal run (${s}) must be backfilled with acknowledged_at`);
+    assertEquals(b.list_bucket, "history", `pre-existing terminal run (${s}) must load in History`);
+    assertEquals(b.ack_open, 0);
+  }
+  const live = dgBucket(db, "pre-live");
+  assertEquals(live.acknowledged_at, null);
+  assertEquals(live.list_bucket, "active");
+  const post = dgBucket(db, "post-done");
+  assertEquals(post.acknowledged_at, null);
+  assertEquals(post.list_bucket, "active");
+  assertEquals(post.ack_open, 1);
+  db.close();
+});

package/app/delivery.ts

@@ -121,10 +121,11 @@ export const EPIC_LIVE_STATUSES = ["planning", "dispatched"] as const;
  *     Dismiss affordance stays closed (see {@link epicIsAcknowledgeable}) so it is never ticked off
  *     mid-flight.
  *
- * It falls to `history` only once truly resolved: a `done` epic the operator has acknowledged, or a
- * terminal non-`done` status (`failed`/`abandoned`, which carry their own incident signal and need no
- * tick-off). Pure and read-only; projected at write time by the `plans` gateway (app/plan.ts) onto
- * `plans.list_bucket`. */
+ * It falls to `history` only once truly resolved AND acknowledged: any TERMINAL epic — `done`,
+ * `failed`, or `abandoned` — that the operator has dismissed (issue #641 made this uniform; before it,
+ * a `failed`/`abandoned` epic dropped straight to History with no tick-off). An unacknowledged terminal
+ * epic of ANY terminal status stays Active until dismissed. Pure and read-only; projected at write time
+ * by the `plans` gateway (app/plan.ts) onto `plans.list_bucket`. */
 export function deriveEpicBucket(
   status: string,
   delivery: string | null | undefined,
@@ -134,15 +135,16 @@ export function deriveEpicBucket(
   return raw === "active" ? "active" : "history";
 }
 
-/** True iff an epic carries the operator "Dismiss" (acknowledge) affordance — a `done` epic whose
- * fan-out has RESOLVED (it is no longer `converging`): every slice PR has reached a terminal state,
- * whether all merged (`delivery = landed` — promote to main, then dismiss) or resolved-not-landed
- * (`delivery = null` — some abandoned/converged). This is the set of Active epics a tick-off may move
- * to History. A live (`planning`/`dispatched`) or still-`converging` epic is genuinely working —
- * nothing to tick off — so its Dismiss stays closed; a `failed`/`abandoned` epic is already in
- * History. The `acknowledgeEpic` operation guards on this (409 otherwise) and the gateway projects it
- * to `plans.ack_open` (1/0) so the page's `showWhenField` Dismiss button renders only for a resolved-
- * but-unacknowledged epic. */
+/** True iff an epic carries the operator "Dismiss" (acknowledge) affordance — a TERMINAL epic whose
+ * fan-out has RESOLVED (it is no longer `converging`): a `done` epic whose every slice PR reached a
+ * terminal state (all merged, `delivery = landed` — promote to main, then dismiss; or resolved-not-
+ * landed, `delivery = null` — some abandoned/converged), OR a `failed`/`abandoned` epic (whose
+ * `delivery` is inherently non-`converging`, so it is dismissable outright — issue #641). This is the
+ * set of Active epics a tick-off may move to History. A live (`planning`/`dispatched`) or still-
+ * `converging` epic is genuinely working — nothing to tick off — so its Dismiss stays closed. The
+ * `acknowledgeEpic` operation guards on this (409 otherwise) and the gateway projects it to
+ * `plans.ack_open` (1/0) so the page's `showWhenField` Dismiss button renders only for a resolved-but-
+ * unacknowledged epic. */
 export function epicIsAcknowledgeable(
   status: string,
   delivery: string | null | undefined,

package/app/deliveryGraphReadModel.test.ts

@@ -39,7 +39,7 @@ import { applyMigrationSet, readMigrationSetFromDisk } from "../test/migrations.
 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 = "087_delivery_graph_read_model.sql";
+const READ_MODEL_MIGRATION = "096_delivery_graph_read_model_list_bucket.sql";
 
 // A minimal in-memory DB carrying the base `delivery_graph_runs` / `pull_requests` shapes the VIEW
 // reads, plus stand-ins for the managed `<table>__tracking` derived VIEWs urban provisions at mount
@@ -53,7 +53,7 @@ function viewDb(): DatabaseSync {
        run_key TEXT PRIMARY KEY, process_key TEXT, process_definition_id TEXT, digest TEXT,
        status TEXT, side_effecting INTEGER, node_count INTEGER, human_node_count INTEGER,
        side_effect_count INTEGER, title TEXT, phase TEXT, phase_node_id TEXT, human_labels TEXT,
-       created_at TEXT, updated_at TEXT, derived_status_override TEXT);
+       created_at TEXT, updated_at TEXT, acknowledged_at TEXT, derived_status_override TEXT);
      CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, root_request_key TEXT, status TEXT,
        derived_status_override TEXT);`,
   );
@@ -72,6 +72,7 @@ interface SampleRun {
   phase?: string | null;
   phase_node_id?: string | null;
   derived_status_override?: string | null;
+  acknowledged_at?: string | null;
 }
 
 function addRun(db: DatabaseSync, run_key: string, run: SampleRun): void {
@@ -79,8 +80,8 @@ function addRun(db: DatabaseSync, run_key: string, run: SampleRun): void {
     `INSERT INTO delivery_graph_runs
        (run_key, process_key, process_definition_id, digest, status, side_effecting, node_count,
         human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at,
-        updated_at, derived_status_override)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        updated_at, acknowledged_at, derived_status_override)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   ).run(
     run_key,
     `pk-${run_key}`,
@@ -97,6 +98,7 @@ function addRun(db: DatabaseSync, run_key: string, run: SampleRun): void {
     null,
     "2026-01-01T00:00:00Z",
     "2026-01-01T00:00:00Z",
+    run.acknowledged_at ?? null,
     run.derived_status_override ?? null,
   );
 }
@@ -210,10 +212,12 @@ test("FRAMEWORK PARITY GUARD: deliveryGraphReadModel's SQL and TS lowerings agre
   for (const status of ["awaiting-approval", "running", "done", "failed", "abandoned"]) {
     for (const derived_status of [status, "failed"]) {
       for (const prs_in_flight of [0, 1, 3]) {
-        samples.push({
-          baseRow: { run_key: "self", status, derived_status },
-          lookups: { [PR_COUNTS_LOOKUP]: [{ root_request_key: "self", prs_in_flight }] },
-        });
+        for (const acknowledged_at of [null, "2026-02-02T00:00:00Z"]) {
+          samples.push({
+            baseRow: { run_key: "self", status, derived_status, acknowledged_at },
+            lookups: { [PR_COUNTS_LOOKUP]: [{ root_request_key: "self", prs_in_flight }] },
+          });
+        }
       }
     }
   }
@@ -292,6 +296,38 @@ test("park_label carries the actionable 'Parked on human node: <label>' text (on
   db.close();
 });
 
+// ── 3b. ACKNOWLEDGE-TO-DISMISS: list_bucket / ack_open (issue #641) ────────────────────────────────
+
+function bucket(db: DatabaseSync, run_key: string): { list_bucket: string; ack_open: number } {
+  const r = db.prepare("SELECT list_bucket, ack_open FROM delivery_graph_read_model WHERE run_key = ?").get(run_key) as {
+    list_bucket: string;
+    ack_open: number;
+  };
+  return { list_bucket: r.list_bucket, ack_open: r.ack_open };
+}
+
+test("a live run is active with no Dismiss; a terminal-but-unacknowledged run STAYS active and offers Dismiss; once acknowledged it drops to history", () => {
+  const db = viewDb();
+  // Live (running) — active, no dismiss.
+  addRun(db, "live", { status: "running", phase: "Running" });
+  // Terminal, not yet dismissed — the uniform rule keeps it ACTIVE (not History) with the Dismiss flag.
+  addRun(db, "done-open", { status: "done", phase: "Completed" });
+  addRun(db, "failed-open", { status: "failed", phase: "Failed" });
+  addRun(db, "aband-open", { status: "abandoned", phase: "Failed" });
+  // Terminal AND acknowledged — dropped to History, Dismiss retracted.
+  addRun(db, "done-ack", { status: "done", phase: "Completed", acknowledged_at: "2026-03-03T00:00:00Z" });
+  // Derive-only terminated (base frozen 'running', derived 'failed'), unacknowledged — still active/dismissable.
+  addRun(db, "derive-term", { status: "running", phase: "Running", derived_status_override: "failed" });
+
+  assertEquals(bucket(db, "live"), { list_bucket: "active", ack_open: 0 });
+  assertEquals(bucket(db, "done-open"), { list_bucket: "active", ack_open: 1 });
+  assertEquals(bucket(db, "failed-open"), { list_bucket: "active", ack_open: 1 });
+  assertEquals(bucket(db, "aband-open"), { list_bucket: "active", ack_open: 1 });
+  assertEquals(bucket(db, "done-ack"), { list_bucket: "history", ack_open: 0 });
+  assertEquals(bucket(db, "derive-term"), { list_bucket: "active", ack_open: 1 });
+  db.close();
+});
+
 // ── 4. PARITY vs TODAY'S PHASE (the acceptance parity) ────────────────────────────────────────────
 
 test("the derived stepper matches TODAY's plain `phase` text (deriveDeliveryPhase) for representative runs, retaining the actionable park label", () => {

package/app/deliveryGraphReadModel.ts

@@ -40,7 +40,9 @@
 // single-step graph both reduce trivially to their one branch.
 
 import { and, caseWhen, col, countWhere, defineReadModel, defineRollup, type Expr, eq, fromTable, gt, isNotNull, lit, not, or, type ReadModel, type Rollup, rcol, when } from "@nanobpm/urban";
+import { DELIVERY_GRAPH_TERMINAL_STATUSES } from "./deliveryGraphRun.ts";
 import { TERMINAL_STATUSES } from "./deliveryStatuses.ts";
+import { deriveAckOpenExpr, deriveListBucketExpr } from "./listBucket.ts";
 import { PR_TRACKING_RELATION } from "./planRollups.ts";
 
 /** The slice-PR relation the member-PR rollup folds over: the auto-provisioned
@@ -136,10 +138,23 @@ const stageState: Expr = caseWhen(
 
 /** The keys of {@link deliveryGraphReadModel}'s DERIVED columns, in the order the migration emits them.
  * Base columns are identity pass-throughs (listed in the migration directly); `park_label` is a
- * hand-authored display column over the base `phase`/`phase_node_id` (no TS twin). */
-export const DELIVERY_GRAPH_READ_MODEL_DERIVED = ["stage", "stage_state"] as const;
+ * hand-authored display column over the base `phase`/`phase_node_id` (no TS twin). `list_bucket`/
+ * `ack_open` are the acknowledge-to-dismiss partition + Dismiss-affordance flag (issue #641). */
+export const DELIVERY_GRAPH_READ_MODEL_DERIVED = ["stage", "stage_state", "list_bucket", "ack_open"] as const;
 export type DeliveryGraphReadModelDerivedColumn = (typeof DELIVERY_GRAPH_READ_MODEL_DERIVED)[number];
 
+/** The Active/History partition — `history` IFF the run is terminal AND acknowledged, else `active`
+ * (live runs + terminal-but-UNACKNOWLEDGED runs that stay actionable until dismissed). The ONE shared
+ * oracle (app/listBucket.ts, issue #641) parameterised by {@link DELIVERY_GRAPH_TERMINAL_STATUSES}, so
+ * this grid's activeness predicate is byte-for-byte the same rule Features/Epics/PRs use — retiring the
+ * `status IN ('awaiting-approval','running')` allowlist the pages filtered before. */
+const listBucket: Expr = deriveListBucketExpr(EFFECTIVE_STATUS_COLUMN, DELIVERY_GRAPH_TERMINAL_STATUSES);
+
+/** The operator "Dismiss" affordance flag — `1` IFF the run is terminal AND not yet acknowledged (so
+ * the page's `showWhenField` Dismiss button renders only for a terminal-but-unacknowledged run), else
+ * `0`. */
+const ackOpen: Expr = deriveAckOpenExpr(EFFECTIVE_STATUS_COLUMN, DELIVERY_GRAPH_TERMINAL_STATUSES);
+
 /**
  * The declare-once `delivery_graph_read_model` derived columns. `selectBaseColumns: false` because the
  * base columns are plain identity pass-throughs enumerated in the migration (so the static pages↔schema
@@ -162,5 +177,7 @@ export const deliveryGraphReadModel: ReadModel = defineReadModel({
   derive: {
     stage,
     stage_state: stageState,
+    list_bucket: listBucket,
+    ack_open: ackOpen,
   },
 });

package/app/deliveryGraphRun.ts

@@ -47,6 +47,10 @@ export interface DeliveryGraphRun {
   human_labels: string | null;
   created_at: string;
   updated_at: string;
+  /** The operator-dismissal stamp (issue #641). Set by `acknowledgeDeliveryGraph` on a TERMINAL run so
+   *  the `delivery_graph_read_model` VIEW folds its `list_bucket` to 'history'; NULL while the run is
+   *  live or terminal-but-undismissed (it stays in Active until an operator ticks it off). */
+  acknowledged_at: string | null;
 }
 
 /** The run lifecycle. `awaiting-approval` is RESERVED but no longer produced (issue #460 moved dispatch
@@ -264,5 +268,6 @@ export function buildDeliveryGraphRunRow(input: {
     human_labels: input.humanLabels ? JSON.stringify(input.humanLabels) : null,
     created_at: input.createdAt ?? at,
     updated_at: at,
+    acknowledged_at: null,
   };
 }

package/app/epicBucket.test.ts

@@ -43,10 +43,16 @@ test("done + delivery=null (poller-pending / resolved-not-landed) -> Active, ack
   assertEquals(deriveEpicBucket("done", null, "2024-01-01T00:00:00Z"), "history");
 });
 
-test("terminal non-done statuses (failed/abandoned) -> History, not acknowledgeable", () => {
+// Issue #641 (uniform acknowledge-to-dismiss): a terminal-non-`done` epic (`failed`/`abandoned` —
+// cancelled) now ALSO stays Active until the operator dismisses it, instead of dropping straight to
+// History. Its `delivery` is always non-`converging`, so it is immediately acknowledgeable, and a
+// dismiss stamp settles it to History — uniform with `done` epics and the PR / delivery-graph grids.
+test("terminal non-done statuses (failed/abandoned) + unacknowledged -> Active, acknowledgeable (issue #641)", () => {
   for (const status of ["failed", "abandoned"]) {
-    assertEquals(deriveEpicBucket(status, null, null), "history", `status=${status}`);
-    assert(!epicIsAcknowledgeable(status, null), `status=${status}`);
+    assertEquals(deriveEpicBucket(status, null, null), "active", `status=${status}`);
+    assert(epicIsAcknowledgeable(status, null), `status=${status}`);
+    // A dismiss stamp settles it to History, like every other terminal surface.
+    assertEquals(deriveEpicBucket(status, null, "2024-01-01T00:00:00Z"), "history", `status=${status} acknowledged`);
   }
 });
 

package/app/featureReadModel.ts

@@ -31,6 +31,7 @@
 // LATER ADR-0065 rollout steps (3/4), deliberately out of scope here.
 
 import { and, caseWhen, col, defineReadModel, type Expr, eq, exists, lit, neq, not, or, pcol, type ReadModel, when } from "@nanobpm/urban";
+import { deriveListBucketExpr } from "./listBucket.ts";
 
 /** The 6 TRULY-terminal statuses that map to the `Done` stage — the single source of truth for the
  * terminal tier of BOTH the pipeline `stage`/`stage_state` derivations and the `list_bucket` history
@@ -128,18 +129,13 @@ const attention: Expr = caseWhen(
   lit(null),
 );
 
-/** `<col> IS NOT NULL` in the closed DSL, which has no dedicated null-test operator: a SELF-equality.
- * `eq` collapses a nullish operand to false in BOTH backends (`COALESCE(x = x, 0)` in SQL, the nullish
- * guard in `compareValues` for TS), and any NON-null value equals itself, so this is true IFF the column
- * is non-NULL — faithful to 073/075's `acknowledged_at IS NOT NULL` and free of the SQLite string→number
- * truthiness coercion a bare `col(...)` boolean predicate would otherwise rely on (e.g. `''`/`'abc'`). */
-const isNotNull = (name: string): Expr => eq(col(name), col(name));
-
 /** The Active/History partition: `history` IFF the row is in a truly-terminal status AND has been
- * acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). `acknowledged_at IS
- * NOT NULL` is expressed via {@link isNotNull} so it stays byte-equivalent to 073/075's VIEW and does
- * not depend on string→number coercion in either backend. */
-const listBucket: Expr = caseWhen([when(and(isDone, isNotNull("acknowledged_at")), lit("history"))], lit("active"));
+ * acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). Delegates to the ONE
+ * shared `deriveListBucketExpr` oracle (app/listBucket.ts, issue #641) parameterised by the feature
+ * terminal set ({@link STAGE_DONE_STATUSES}) so all four "Active …" grids share the identical AST — the
+ * emitted SQL stays byte-equivalent to migration 081's already-merged VIEW body (the shared oracle
+ * reproduces this model's `isDone`/`isNotNull` forms exactly). */
+const listBucket: Expr = deriveListBucketExpr(EFFECTIVE_STATUS_COLUMN, STAGE_DONE_STATUSES);
 
 /** The keys of {@link featureReadModel}'s DERIVED columns, in the order migration 076 emits them.
  * Base columns are identity pass-throughs (not derivations) and are listed in the migration directly. */

package/app/listBucket.ts

@@ -0,0 +1,86 @@
+// The ONE Active/History `list_bucket` derivation, shared byte-for-byte by every "Active …" grid's
+// read model (issue #641). All four dispatch surfaces — Features, Epics, Convergence (PRs) and
+// Delivery Graphs — partition their rows into Active/History with the SAME acknowledge-to-dismiss rule:
+// a row STAYS in Active until an operator dismisses it (stamps `acknowledged_at`), then drops to
+// History. This module is that rule expressed ONCE in Urban's closed expression DSL, parameterised by
+// each model's own terminal-status set, so the four read models cannot drift from one another (the
+// last two base-`status` allowlists — Convergence + Delivery Graphs — are retired by consuming it).
+//
+// THE RULE (uniform across the four surfaces):
+//   terminal & acknowledged NULL -> active   (stay until dismissed)
+//   terminal                     -> history  (dismissed)
+//   else (still live)            -> active
+//
+// which is exactly `history` IFF the row is in a truly-terminal status AND has been acknowledged; else
+// `active`. Feature runs (app/featureReadModel.ts, migration 081) already encode this shape; this is
+// its extraction so PRs / Delivery Graphs / Epics share the identical AST rather than re-authoring it.
+//
+// `acknowledged_at IS NOT NULL` is expressed via {@link isAckStamped} as a SELF-equality (`eq(col,
+// col)`), NOT a bare `col(...)` boolean or a dedicated null-test: `eq` collapses a nullish operand to
+// false in BOTH lowerings (`COALESCE(x = x, 0)` in SQL, the nullish guard in `compareValues` for TS),
+// and any non-null value equals itself, so it is true IFF the column is non-NULL — free of the SQLite
+// string→number truthiness coercion a bare column predicate would rely on, and byte-equivalent to the
+// feature model's own `isNotNull` (app/featureReadModel.ts) so the shared oracle stays identical to
+// migration 081's already-merged VIEW body.
+
+import { and, caseWhen, col, type Expr, eq, lit, not, or, when } from "@nanobpm/urban";
+
+/** `<effectiveStatusCol> IN (…terminal)` as a closed-DSL predicate: an OR of equalities over the
+ * tracking VIEW's terminal-folded effective status. The single "is this row terminal?" test the
+ * bucket/ack derivations share. */
+export const terminalStatusIn = (effectiveStatusCol: string, terminalStatuses: readonly string[]): Expr =>
+  or(...terminalStatuses.map((s) => eq(col(effectiveStatusCol), lit(s))));
+
+/** `<ackCol> IS NOT NULL` in the closed DSL (which has no dedicated null-test operator): a SELF-equality
+ * that collapses a nullish operand to false in both lowerings, so it is true IFF the column is
+ * non-NULL. See the module header for why this exact form (not a bare `col`) is used. */
+export const isAckStamped = (ackCol: string): Expr => eq(col(ackCol), col(ackCol));
+
+/**
+ * The Active/History partition over an arbitrary "dismissable-terminal" PREDICATE: `history` IFF the
+ * predicate holds AND the row has been acknowledged; otherwise `active`. The predicate captures each
+ * model's notion of a row that is BOTH terminal AND actually tick-off-able — for PRs/Delivery-Graphs/
+ * features that is simply "terminal" ({@link deriveListBucketExpr}); for EPICS it additionally excludes
+ * a still-`converging` done epic (which is terminal by `status` but must NOT be dismissable mid-flight),
+ * so a stray/premature ack never drags it to History. Shared by all four surfaces so they cannot drift.
+ */
+export const deriveListBucketFromTerminal = (terminalPredicate: Expr, ackCol = "acknowledged_at"): Expr =>
+  caseWhen([when(and(terminalPredicate, isAckStamped(ackCol)), lit("history"))], lit("active"));
+
+/**
+ * The operator "Dismiss" affordance flag over an arbitrary "dismissable-terminal" PREDICATE: `1` IFF
+ * the predicate holds AND the row is not yet acknowledged, else `0`. The twin of {@link
+ * deriveListBucketFromTerminal} (same predicate) — a row is dismissable exactly while it would still be
+ * `active` on the terminal branch, i.e. terminal-and-unacknowledged (and, for epics, non-`converging`).
+ */
+export const deriveAckOpenFromTerminal = (terminalPredicate: Expr, ackCol = "acknowledged_at"): Expr =>
+  caseWhen([when(and(terminalPredicate, not(isAckStamped(ackCol))), lit(1))], lit(0));
+
+/**
+ * The Active/History partition, parameterised by the model's terminal-status set: `history` IFF the
+ * row's terminal-folded effective status is terminal AND it has been acknowledged; otherwise `active`
+ * (live rows + terminal-but-UNACKNOWLEDGED rows that stay actionable until dismissed).
+ *
+ * @param effectiveStatusCol the terminal-folded status column the model classifies on (`derived_status`).
+ * @param terminalStatuses   the model's terminal set (features' Done statuses, the PR terminal set, …).
+ * @param ackCol             the acknowledgement column (defaults to `acknowledged_at`).
+ */
+export const deriveListBucketExpr = (
+  effectiveStatusCol: string,
+  terminalStatuses: readonly string[],
+  ackCol = "acknowledged_at",
+): Expr => deriveListBucketFromTerminal(terminalStatusIn(effectiveStatusCol, terminalStatuses), ackCol);
+
+/**
+ * The operator "Dismiss" (acknowledge) affordance flag: `1` IFF the row is terminal AND not yet
+ * acknowledged (so the page's `showWhenField` Dismiss button renders only for a terminal-but-
+ * unacknowledged row — never a still-live one, and never a re-dismiss of an already-filed row), else
+ * `0`. The PR / Delivery-Graph twin of the epic's `ack_open` (app/planReadModel.ts), which additionally
+ * gates on its `converging` sub-state; PRs and Delivery Graphs have no such mid-flight terminal, so
+ * "terminal ∧ unacknowledged" is the whole predicate.
+ */
+export const deriveAckOpenExpr = (
+  effectiveStatusCol: string,
+  terminalStatuses: readonly string[],
+  ackCol = "acknowledged_at",
+): Expr => deriveAckOpenFromTerminal(terminalStatusIn(effectiveStatusCol, terminalStatuses), ackCol);

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", () => {