@nanobpm/nano-workforce 0.166.0 → 0.167.1

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/pollUserTasks.test.ts

@@ -675,3 +675,168 @@ test("pollUserTasks (typed-seam fallback): denormalises the engine form_key from
   const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
   assertEquals(byKey["ut-plan"].form_key, "form-77");
 });
+
+test("pollUserTasks (engine-first): self-heals an escalated run stranded off its parked task, sparing a genuinely parked one (issue #642)", async () => {
+  // `status="escalated"` must hold ONLY while a `feature-escalation` task is open (parity with the PR
+  // contract). A run whose instance the engine no longer reports parked (its escalation was answered,
+  // or it predates the write-side reset — the #632 tear) is reconciled to `running`; a run whose task
+  // IS still open is left escalated. The engine's open set is the authority, not the raw status column.
+  const { data, stores } = memData({
+    feature_runs: [
+      { feature_key: "o/r#632", status: "escalated", process_key: "fp-632", issue_url: null, title: "stranded", delivery_label: null },
+      { feature_key: "o/r#77", status: "escalated", process_key: "fp-77", issue_url: null, title: "still parked", delivery_label: null },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    // Only fp-77 is genuinely parked; the engine reports NO open task on fp-632.
+    { userTaskKey: "ut-parked", elementId: "feature-escalation", processInstanceKey: "fp-77", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({ "fp-77": [{ userTaskKey: "ut-parked", elementId: "feature-escalation" }] }), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.feature_runs ?? []).map((r) => [r.feature_key, r]));
+  assertEquals(byKey["o/r#632"].status, "running", "the stranded escalated run is healed to running");
+  assertEquals(byKey["o/r#77"].status, "escalated", "the genuinely parked run stays escalated");
+});
+
+test("pollUserTasks (engine-first): skips the per-instance open-task RPC for an escalated run already seen parked in this pass's sweep (issue #642)", async () => {
+  // Presence in THIS pass's swept `desired` set is POSITIVE evidence the run is genuinely parked — the
+  // best-effort sweep may truncate (drop tasks) but never invents one. Re-confirming such a run with a
+  // per-instance `openUserTasks` RPC is a redundant N+1 query on every poll tick; the self-heal must skip
+  // it. Only a run NOT confirmed parked by the sweep still needs the per-instance check (unchanged).
+  const { data, stores } = memData({
+    feature_runs: [
+      { feature_key: "o/r#parked", status: "escalated", process_key: "fp-parked", issue_url: null, title: "parked", delivery_label: null },
+      { feature_key: "o/r#stranded", status: "escalated", process_key: "fp-stranded", issue_url: null, title: "stranded", delivery_label: null },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-parked", elementId: "feature-escalation", processInstanceKey: "fp-parked", state: "CREATED" },
+  ]);
+  const openUserTasksCalls: string[] = [];
+  const engine = {
+    searchUserTasks: () => Promise.resolve([]),
+    openUserTasks: (filter?: { processInstanceKey?: string }) => {
+      if (filter?.processInstanceKey) openUserTasksCalls.push(filter.processInstanceKey);
+      return Promise.resolve([]); // no instance reports an open escalation via the per-instance seam
+    },
+  } as unknown as EngineClient;
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.feature_runs ?? []).map((r) => [r.feature_key, r]));
+  assertEquals(byKey["o/r#parked"].status, "escalated", "the swept-parked run stays escalated without a per-instance query");
+  assertEquals(byKey["o/r#stranded"].status, "running", "the run absent from the sweep is still confirmed per-instance and healed");
+  assertEquals(openUserTasksCalls.includes("fp-parked"), false, "no redundant per-instance RPC for the already-parked run");
+  assertEquals(openUserTasksCalls.includes("fp-stranded"), true, "the unconfirmed run still needs the per-instance RPC");
+});
+
+test("pollUserTasks (engine-first): a TRUNCATED best-effort sweep never heals a genuinely-parked escalated run (issue #642)", async () => {
+  // `sweepOpenEscalationTasks` is explicitly best-effort — it BREAKS early on a paging/transport error
+  // and projects only what it had gathered. Healing `escalated -> running` on ABSENCE from that partial
+  // set is mutating durable state on negative evidence: a genuinely-parked human escalation whose task
+  // lived on an unreached page would be silently stolen. The self-heal must confirm per-instance against
+  // the engine's authoritative open set, NOT the (possibly truncated) global sweep.
+  const { data, stores } = memData({
+    feature_runs: [
+      { feature_key: "o/r#parked", status: "escalated", process_key: "fp-parked", issue_url: null, title: "genuinely parked", delivery_label: null },
+      { feature_key: "o/r#stranded", status: "escalated", process_key: "fp-stranded", issue_url: null, title: "stranded", delivery_label: null },
+    ],
+  });
+  // Page 1 fills the limit (forcing a second page) with unrelated open escalations; page 2 — which WOULD
+  // carry fp-parked's escalation — errors, so the sweep truncates and `desired` never sees fp-parked.
+  const page1: RawTask[] = Array.from({ length: 100 }, (_, i) => ({
+    userTaskKey: `other-${i}`,
+    elementId: "feature-escalation",
+    processInstanceKey: `other-${i}`,
+    state: "CREATED",
+  }));
+  const orig = globalThis.fetch;
+  // biome-ignore lint/suspicious/noExplicitAny: minimal fetch double for the raw-REST search surface
+  globalThis.fetch = (async (url: string | URL, init?: any) => {
+    if (!String(url).endsWith("/user-tasks/search")) return new Response("not found", { status: 404 });
+    const from: number = JSON.parse(init?.body ?? "{}")?.page?.from ?? 0;
+    if (from === 0) {
+      return new Response(JSON.stringify({ items: page1 }), { status: 200, headers: { "content-type": "application/json" } });
+    }
+    return new Response("boom", { status: 500 }); // page 2 transport error -> sweep truncates here
+  }) as typeof fetch;
+  // The engine's authoritative per-instance open set: fp-parked IS parked; fp-stranded is not.
+  const engine = fakeEngine({ "fp-parked": [{ userTaskKey: "ut-parked", elementId: "feature-escalation" }] });
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    globalThis.fetch = orig;
+  }
+  const byKey = Object.fromEntries((stores.feature_runs ?? []).map((r) => [r.feature_key, r]));
+  assertEquals(byKey["o/r#parked"].status, "escalated", "a genuinely-parked run survives a truncated sweep");
+  assertEquals(byKey["o/r#stranded"].status, "running", "a truly stranded run is still healed");
+});
+
+test("pollUserTasks (engine-first): does NOT heal an escalated run when the per-instance open-task query errors (issue #642)", async () => {
+  // A per-instance query error is not proof the run is unparked — mutating on that negative evidence would
+  // again steal a parked escalation. On query error the run must be left `escalated` for a later pass.
+  const { data, stores } = memData({
+    feature_runs: [{ feature_key: "o/r#err", status: "escalated", process_key: "fp-err", issue_url: null, title: "query errors", delivery_label: null }],
+  });
+  const restore = stubUserTaskSearch([]); // empty sweep -> old code would heal on absence
+  const engine = {
+    searchUserTasks: () => Promise.resolve([]),
+    openUserTasks: (filter?: { processInstanceKey?: string }) =>
+      filter?.processInstanceKey === "fp-err" ? Promise.reject(new Error("engine down")) : Promise.resolve([]),
+  } as unknown as EngineClient;
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.feature_runs ?? []).map((r) => [r.feature_key, r]));
+  assertEquals(byKey["o/r#err"].status, "escalated", "a failed per-instance query leaves the run escalated");
+});
+
+test("pollUserTasks (engine-first): does NOT heal a JUST-escalated run inside the grace window before its user task exists (issue #642)", async () => {
+  // `record-feature-escalation` writes `status="escalated"` (stamping `updated_at`) on the `escalated`
+  // arm IMMEDIATELY BEFORE the engine creates the `feature-escalation` user task. A poll landing in that
+  // window sees `openUserTasks` return none and would wrongly flip the fresh escalation back to `running`,
+  // making the just-raised escalation invisible. A short grace window on `updated_at` spares a just-written
+  // escalation while still healing genuinely-stranded (old) rows.
+  const fresh = new Date().toISOString();
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString(); // an hour ago — comfortably past grace
+  const { data, stores } = memData({
+    feature_runs: [
+      { feature_key: "o/r#fresh", status: "escalated", process_key: "fp-fresh", updated_at: fresh, issue_url: null, title: "just escalated", delivery_label: null },
+      { feature_key: "o/r#old", status: "escalated", process_key: "fp-old", updated_at: stale, issue_url: null, title: "genuinely stranded", delivery_label: null },
+    ],
+  });
+  const restore = stubUserTaskSearch([]); // engine reports no open escalation task for either instance
+  const engine = fakeEngine({}); // openUserTasks returns [] for every instance (task not yet created / gone)
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.feature_runs ?? []).map((r) => [r.feature_key, r]));
+  assertEquals(byKey["o/r#fresh"].status, "escalated", "a just-escalated run inside the grace window is spared the heal");
+  assertEquals(byKey["o/r#old"].status, "running", "a genuinely-stranded (old) run is still healed");
+});
+
+test("pollUserTasks (typed-seam fallback): self-heals an escalated run with no open feature-escalation task (issue #642)", async () => {
+  // The reduced-capability path scans FEATURE_ACTIVE_STATUSES instances (incl. `escalated`) directly,
+  // so the per-instance open-task read is just as authoritative for the self-heal.
+  const { data, stores } = memData({
+    feature_runs: [
+      { feature_key: "o/r#632", status: "escalated", process_key: "fp-632", issue_url: null, title: "stranded", delivery_label: null },
+    ],
+  });
+  const engine = fakeEngine({ "fp-632": [] }); // instance active at implement-task, no open user task
+
+  await pollUserTasks(data, engine); // no engineRest → typed-seam fallback
+
+  const byKey = Object.fromEntries((stores.feature_runs ?? []).map((r) => [r.feature_key, r]));
+  assertEquals(byKey["o/r#632"].status, "running", "the stranded escalated run is healed to running");
+});

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`);
+  });
+}