@nanobpm/nano-workforce 0.168.2 → 0.170.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.170.0](https://github.com/nanobpm/nano-workforce/compare/v0.169.0...v0.170.0) (2026-08-31)
+
+### Features
+
+* **api:** add listEscalations read tool + structured openEscalation ([#672](https://github.com/nanobpm/nano-workforce/issues/672)) ([893d39a](https://github.com/nanobpm/nano-workforce/commit/893d39a644cd18102422186b4baddc6779b3510d)), closes [#666](https://github.com/nanobpm/nano-workforce/issues/666) [#666](https://github.com/nanobpm/nano-workforce/issues/666) [#358](https://github.com/nanobpm/nano-workforce/issues/358) [owner/repo#N](https://github.com/owner/repo/issues/N)
+
+## [0.169.0](https://github.com/nanobpm/nano-workforce/compare/v0.168.2...v0.169.0) (2026-08-31)
+
+### Features
+
+* add getPrHistory read tool for PR escalation/round history ([#670](https://github.com/nanobpm/nano-workforce/issues/670)) ([22bd6f9](https://github.com/nanobpm/nano-workforce/commit/22bd6f9d28b891a2b4c157d21bad94cb11af1eb4)), closes [#668](https://github.com/nanobpm/nano-workforce/issues/668)
+
 ## [0.168.2](https://github.com/nanobpm/nano-workforce/compare/v0.168.1...v0.168.2) (2026-08-31)
 
 ### Bug Fixes

package/app/mcpExclusions.test.ts

@@ -46,6 +46,7 @@ const EXPECTED_EXPOSED = [
   "previewDeliveryGraph",
   "listStagedProposals",
   "listActivePrs",
+  "listEscalations",
   "getAgentInstructions",
   "getVersion",
 ];

package/app/prHistory.ts

@@ -0,0 +1,117 @@
+// PR round + escalation history read model (issue #668, N4 of epic #664).
+//
+// "Why did this PR escalate?" / "what happened in prior rounds?" lives in the `rounds` and
+// `escalations` tables — the SAME two tables the Convergence page (`pages/home.page.json`, the PR
+// detail's "Rounds" and "Escalations" child grids) reads directly. Until now the only way to answer
+// those questions off the UI was to ssh into the instance and query the DB by hand. This module is
+// the ONE canonical reader over those tables so an MCP read tool (`getPrHistory`) can surface the
+// same history without DB access.
+//
+// Derivation over duplication (AGENTS.md): this does NOT introduce a new projection table or a
+// second source of truth. The Convergence page's "query" is declarative datasource JSON over the
+// `rounds`/`escalations` tables (ordered rounds-by-round_no, escalations-by-id); this function reads
+// those exact tables with the exact same orderings, so the tool and the page cannot drift onto
+// different data.
+import type { DataLayer } from "@nanobpm/urban";
+
+/** A `rounds` row — the per-round convergence record the Convergence page's "Rounds" grid reads. */
+interface RoundRow {
+  id: number;
+  pr_key: string;
+  round_no: number;
+  status: string | null;
+  summary: string | null;
+  worker: string | null;
+  started_at: string;
+  ended_at: string | null;
+}
+
+/** An `escalations` row — the escalation record the Convergence page's "Escalations" grid reads. */
+interface EscalationRow {
+  id: number;
+  pr_key: string;
+  round_no: number;
+  kind: string;
+  question: string;
+  answer: string | null;
+  status: string;
+  worker: string | null;
+  asked_at: string;
+  answered_at: string | null;
+}
+
+/** The subset of a `pull_requests` row this module needs to resolve a processKey → prKey. */
+interface PrKeyRow {
+  pr_key: string;
+  process_key: string | null;
+}
+
+/** One round in a PR's timeline: its status transition/outcome, owning worker, and timestamps. */
+export interface PrHistoryRound {
+  roundNo: number;
+  status: string | null;
+  worker: string | null;
+  summary: string | null;
+  startedAt: string;
+  endedAt: string | null;
+}
+
+/** One escalation in a PR's history: its kind, question/answer, status, and timestamps. */
+export interface PrHistoryEscalation {
+  roundNo: number;
+  kind: string;
+  worker: string | null;
+  question: string;
+  answer: string | null;
+  status: string;
+  askedAt: string;
+  answeredAt: string | null;
+}
+
+/** A PR's full escalation + round history, as surfaced by the Convergence page's PR detail. */
+export interface PrHistory {
+  prKey: string;
+  rounds: PrHistoryRound[];
+  escalations: PrHistoryEscalation[];
+}
+
+const rounds = (data: DataLayer) => data.table<RoundRow>("rounds", "id");
+const escs = (data: DataLayer) => data.table<EscalationRow>("escalations", "id");
+const prs = (data: DataLayer) => data.table<PrKeyRow>("pull_requests", "pr_key");
+
+/** Resolve an engine process-instance key to the PR it drives (unique per instance), or null. */
+export async function prKeyForProcess(data: DataLayer, processKey: string): Promise<string | null> {
+  const matches = await prs(data).find({ process_key: processKey });
+  return matches[0]?.pr_key ?? null;
+}
+
+/** The canonical PR history read: rounds (round_no asc) + escalations (id asc, i.e. asked order) for
+ * one PR, projected to the wire shape. An unknown `prKey` yields an empty history (no throw), so a
+ * caller can distinguish "no history yet" from an error without a 404 round-trip. */
+export async function prHistory(data: DataLayer, prKey: string): Promise<PrHistory> {
+  const roundRows = (await rounds(data).find({ pr_key: prKey })).sort(
+    (a, b) => a.round_no - b.round_no || a.id - b.id,
+  );
+  const escRows = (await escs(data).find({ pr_key: prKey })).sort((a, b) => a.id - b.id);
+  return {
+    prKey,
+    rounds: roundRows.map((r) => ({
+      roundNo: r.round_no,
+      status: r.status ?? null,
+      worker: r.worker ?? null,
+      summary: r.summary ?? null,
+      startedAt: r.started_at,
+      endedAt: r.ended_at ?? null,
+    })),
+    escalations: escRows.map((e) => ({
+      roundNo: e.round_no,
+      kind: e.kind,
+      worker: e.worker ?? null,
+      question: e.question,
+      answer: e.answer ?? null,
+      status: e.status,
+      askedAt: e.asked_at,
+      answeredAt: e.answered_at ?? null,
+    })),
+  };
+}

package/app/prParse.ts

@@ -0,0 +1,34 @@
+// Canonical PR-key parser (extracted from app/service.ts so leaf modules can reuse the ONE
+// implementation of the `owner/repo#N` shape without importing the heavy service module — which
+// imports them, so a back-import would cycle). `app/service.ts` re-exports `parsePr`/`ParsedPr`
+// from here, so every existing `import { parsePr } from "./service.ts"` keeps resolving. This is
+// the single source of truth for "is this string a PR key?" — do not add a second shape regex.
+export interface ParsedPr {
+  repo: string;
+  number: number;
+  url: string;
+  prKey: string;
+}
+
+/** Parse "owner/repo#123" or a canonical PR URL into its parts, or `null` when the input is not a
+ *  PR key/URL. */
+export function parsePr(input: unknown): ParsedPr | null {
+  // Total on any input: a process-variable regression (or an older in-flight instance) can carry a
+  // non-string prKey, and `.trim()` on a non-string throws — turning a should-fail-open caller into
+  // a retrying job. Fail closed to `null` here so every caller resolves safely instead of throwing.
+  if (typeof input !== "string") return null;
+  const s = input.trim();
+  let m = s.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/i);
+  if (m) {
+    const repo = `${m[1]}/${m[2]}`;
+    const number = Number(m[3]);
+    return { repo, number, url: `https://github.com/${repo}/pull/${number}`, prKey: `${repo}#${number}` };
+  }
+  m = s.match(/^([^/]+\/[^#]+)#(\d+)$/);
+  if (m) {
+    const repo = m[1];
+    const number = Number(m[2]);
+    return { repo, number, url: `https://github.com/${repo}/pull/${number}`, prKey: `${repo}#${number}` };
+  }
+  return null;
+}

package/app/service.ts

@@ -75,6 +75,7 @@ import {
   planTasks,
 } from "./plan.ts";
 import { derivePromotionState, isEpicIntegrationBranch, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
+import { type ParsedPr, parsePr } from "./prParse.ts";
 import {
   defaultProbeExec,
   type ProbeExec,
@@ -93,12 +94,14 @@ import {
   latestOpenEscalationQuestion,
   latestPlanReviewFindings,
   latestTrialMergeQuestion,
+  type OpenEscalation,
   PLAN_REVIEW_ELEMENT,
   PR_WAIT_ANSWER_ELEMENT,
   PR_WAIT_MERGE_ANSWER_ELEMENT,
   prEscalations,
   reconcileUserTasks,
   TRIAL_MERGE_ELEMENT,
+  toOpenEscalation,
   type UserTaskContext,
   type UserTaskRow,
   userTaskKindLabel,
@@ -314,13 +317,6 @@ const prsTracking = (data: DataLayer) =>
 const escs = (data: DataLayer) => data.table<Escalation>("escalations", "id");
 const deps = (data: DataLayer) => data.table<PrDependency>("pr_dependencies", "pr_key");
 
-export interface ParsedPr {
-  repo: string;
-  number: number;
-  url: string;
-  prKey: string;
-}
-
 /** Canonical GitHub PR URL for a repo + number. Matches the `url` `parsePr` derives, so a
  * reconstructed row is indistinguishable from one registered at submit time. */
 export function canonicalPrUrl(repo: string, number: number): string {
@@ -379,27 +375,10 @@ export async function ensurePr(
   }
 }
 
-/** Parse "owner/repo#123" or a canonical PR URL into its parts. */
-export function parsePr(input: unknown): ParsedPr | null {
-  // Total on any input: a process-variable regression (or an older in-flight instance) can carry a
-  // non-string prKey, and `.trim()` on a non-string throws — turning a should-fail-open caller into
-  // a retrying job. Fail closed to `null` here so every caller resolves safely instead of throwing.
-  if (typeof input !== "string") return null;
-  const s = input.trim();
-  let m = s.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/i);
-  if (m) {
-    const repo = `${m[1]}/${m[2]}`;
-    const number = Number(m[3]);
-    return { repo, number, url: `https://github.com/${repo}/pull/${number}`, prKey: `${repo}#${number}` };
-  }
-  m = s.match(/^([^/]+\/[^#]+)#(\d+)$/);
-  if (m) {
-    const repo = m[1];
-    const number = Number(m[2]);
-    return { repo, number, url: `https://github.com/${repo}/pull/${number}`, prKey: `${repo}#${number}` };
-  }
-  return null;
-}
+/** Parse "owner/repo#123" or a canonical PR URL into its parts. Canonical implementation lives in
+ *  `./prParse.ts` (a leaf module other leaf modules can reuse without cycling through this one); re-exported
+ *  here so existing `import { parsePr } from "./service.ts"` call sites keep resolving. */
+export { type ParsedPr, parsePr };
 
 /** Extract `Depends-on: owner/repo#N[, owner/repo#N …]` (or PR URLs) from a PR body. Multiple
  * `Depends-on:` lines accumulate; each line may list several comma/space-separated refs. Returns
@@ -785,7 +764,7 @@ export interface ActivePr {
   round: number;
   processKey: string | null;
   waitingSince: string | null;
-  openEscalation: string | null;
+  openEscalation: OpenEscalation | null;
   updatedAt: string;
   /** Leasing worker while an agent is actively working the review round; null when queued
    * (job created, not yet activated) or not at the review-round task. */
@@ -796,15 +775,15 @@ export interface ActivePr {
 
 /** Every tracked PR not in a terminal state (converged/abandoned), newest-updated first. Backs
  * the GET status endpoint so an operator or an external harness can see what is in flight
- * without reading the datasource directly. The open-escalation question is derived from the
- * canonical `escalations` audit row — the single source of truth (no denormalised PR-row
- * pointer). A PR reads `status="escalated"` only while a token is parked awaiting a human answer,
- * and the row it raised carries `status="open"` until that answer is recorded — by the
- * `pr.answer-escalation` step on the `wait-answer` (review loop) or `wait-merge-answer` (merge loop)
- * user-task completion. Both loops now park on a native user task answered through the one canonical
- * `completeUserTask` door (#256), so deriving from the row (not a per-loop wait mechanism) surfaces
- * BOTH loops' escalations uniformly. Once answered the row leaves `open`, so `openEscalation`
- * derives back to null. */
+ * without reading the datasource directly. The structured `openEscalation` pointer (issue #666:
+ * `{ userTaskKey, kind, summary }`) is derived from the canonical `user_tasks` read model — the SAME
+ * user-task surface `listEscalations` and the Convergence/Tasks page consume, so `/status` carries the
+ * completable `userTaskKey` without a denormalised PR-row pointer or a second source of truth. A
+ * `user_tasks` row for a PR subject exists iff its review/merge-loop escalation task is currently OPEN
+ * (parked awaiting a human answer) — the same live-escalation signal a `status="escalated"` PR carries.
+ * Both loops park on a native user task answered through the one canonical `completeUserTask` door
+ * (#256), so deriving from the read model surfaces BOTH loops' escalations uniformly. Once the task is
+ * completed its row is removed, so `openEscalation` derives back to null. */
 export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
   const all = await prsTracking(data).all();
   const active = all
@@ -818,15 +797,20 @@ export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
     // `derived_status === status`.
     .filter((p) => !TERMINAL_STATUSES.includes(p.derived_status))
     .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
-  // Only an `escalated` PR is parked awaiting a human answer (either loop). Surface the question
-  // from its latest still-open `escalations` row; a resubmit retires stale rows and finalize/merge
-  // move the PR off `escalated`, so an open row on an escalated PR is a genuinely live escalation.
-  // Fetch every open row in one query (avoids an N+1 over escalated PRs), then keep the newest per PR.
-  const openEscByPr = new Map<string, string>();
-  const escalatedPrs = new Set(active.filter((p) => p.status === "escalated").map((p) => p.pr_key));
-  for (const e of (await escs(data).find({ status: "open" })).sort((a, b) => b.id - a.id)) {
-    if (!escalatedPrs.has(e.pr_key) || openEscByPr.has(e.pr_key)) continue;
-    if (e.question) openEscByPr.set(e.pr_key, e.question);
+  // Derive the STRUCTURED open-escalation pointer from the ONE `user_tasks` read model (issue #666) —
+  // the same user-task surface `listEscalations` and the Convergence/Tasks page consume — so `/status`
+  // carries the completable `userTaskKey` (plus the escalation `kind` and a one-line `summary`) without
+  // a second source of truth. A `user_tasks` row for a PR subject exists iff its review/merge-loop
+  // escalation task is currently OPEN (parked awaiting a human answer), so its presence is exactly the
+  // live-escalation signal the old `escalations`-table derivation computed — now unified across BOTH
+  // loops. Keep the newest per PR (a PR parks on at most one such task at a time; order by recency for
+  // determinism).
+  const openEscByPr = new Map<string, OpenEscalation>();
+  for (const t of (await userTasks(data).find({ subject_type: "pr" })).sort((a, b) =>
+    a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0,
+  )) {
+    if (openEscByPr.has(t.subject_key)) continue;
+    openEscByPr.set(t.subject_key, toOpenEscalation(t));
   }
   return active.map((p) => ({
     prKey: p.pr_key,

package/app/userTasks.test.ts

@@ -19,6 +19,7 @@ import {
   latestTrialMergeQuestion,
   type PrEscalationRow,
   reconcileUserTasks,
+  toEscalationView,
   TRIAL_MERGE_ELEMENT,
   userTaskKindLabel,
   type UserTaskRow,
@@ -337,3 +338,38 @@ test("latestFeatureEscalationQuestion: picks the newest audit row (highest id),
 test("latestFeatureEscalationQuestion: null when the feature has no recorded escalation", () => {
   assertEquals(latestFeatureEscalationQuestion([]), null);
 });
+
+// toEscalationView.prKey must be a genuine PR key (owner/repo#N), never a subject key that fell back
+// to a non-PR value. `buildUserTaskRow` coalesces a blank subjectKey to `processKey`/`userTaskKey`
+// for an orphaned/untracked instance (#358); for a PR-subject task that yields `subject_key` = a
+// numeric engine key, which must NOT be emitted as `prKey` (OpenAPI: prKey is the PR key only when
+// known). Copilot review suppressed advisory app/userTasks.ts:136.
+const escRow = (over: Partial<UserTaskRow>): UserTaskRow => ({
+  user_task_key: "ut-1",
+  element_id: PR_WAIT_ANSWER_ELEMENT,
+  kind_label: "PR review",
+  subject_type: "pr",
+  subject_key: "o/r#7",
+  subject_title: "o/r#7",
+  subject_url: null,
+  question: null,
+  process_key: null,
+  form_key: null,
+  created_at: AT,
+  updated_at: AT,
+  ...over,
+});
+
+test("toEscalationView: PR-subject row with a PR-shaped subject key emits it as prKey", () => {
+  assertEquals(toEscalationView(escRow({ subject_key: "o/r#7" })).prKey, "o/r#7");
+});
+
+test("toEscalationView: PR-subject row whose subject key fell back to a non-PR value yields prKey null (still correlatable via subjectKey)", () => {
+  const view = toEscalationView(escRow({ subject_key: "19153" }));
+  assertEquals(view.prKey, null);
+  assertEquals(view.subjectKey, "19153");
+});
+
+test("toEscalationView: non-PR subject always yields prKey null", () => {
+  assertEquals(toEscalationView(escRow({ subject_type: "plan", subject_key: "o/r#7" })).prKey, null);
+});

package/app/userTasks.ts

@@ -22,6 +22,7 @@ import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, type FeatureEscalationRow } from "./feature.ts";
 import type { PlanReview } from "./plan.ts";
+import { parsePr } from "./prParse.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
 
 const now = () => new Date().toISOString();
@@ -98,6 +99,80 @@ export interface UserTaskRow {
 
 export const userTasks = (data: DataLayer) => data.table<UserTaskRow>("user_tasks", "user_task_key");
 
+/** The read-tool projection of ONE open escalation user task (issue #666, epic #664 — retire the
+ *  `/tasks/api/tasks` inbox curl). Sourced from the SAME `user_tasks` read model the Tasks inbox and
+ *  Convergence page consume — NOT a second source of truth. It carries the completable `userTaskKey`
+ *  an agent answers via `completeUserTask` / `agentCompleteEscalation`, the escalation `kind` (the
+ *  BPMN `elementId`), the denormalised decision text (`question` — the question / findings / task the
+ *  loop or agent raised, uniform across all four kinds), and the deployed-form context so a tool-aware
+ *  agent can discover and answer an escalation without curling the un-projected task inbox. */
+export interface EscalationView {
+  userTaskKey: string;
+  kind: string;
+  kindLabel: string;
+  /** The PR key when this escalation belongs to a PR (review/merge loop): the subject key, but ONLY
+   *  when it is actually PR-key-shaped (`owner/repo#N`). Null for feature / plan / delivery / agent
+   *  subjects — and also null for a PR-subject task whose subject key fell back to a non-PR value
+   *  (`processKey`/`userTaskKey`) for an orphaned/untracked instance (see `buildUserTaskRow`), so
+   *  `prKey` never emits a non-PR key. Use `subjectKey` for raw correlation in that case. */
+  prKey: string | null;
+  subjectType: string;
+  subjectKey: string;
+  subjectTitle: string;
+  subjectUrl: string | null;
+  question: string | null;
+  formKey: string | null;
+  processKey: string | null;
+  /** The denormalised decision/form context the Tasks inbox renders for this task (the same
+   *  `question` + subject the deployed `.form` is seeded with). The typed answer fields an agent
+   *  submits depend on `kind` (e.g. a PR `{ answer }`, a plan-review `{ directive, notes }`). */
+  formVariables: Record<string, unknown>;
+}
+
+/** Pure: project one open `user_tasks` row into its `listEscalations` read-tool entry. Reuses the
+ *  read model verbatim (no new query / source of truth). `prKey` is the subject key only when the
+ *  subject is a PR AND the subject key is genuinely PR-key-shaped (`owner/repo#N`, validated by the
+ *  canonical `parsePr`) — an orphaned PR-loop instance whose subject key fell back to a numeric
+ *  `processKey`/`userTaskKey` (see `buildUserTaskRow`) yields `prKey: null`, not a non-PR key that
+ *  would contradict the OpenAPI contract. `subjectKey` still carries the raw value for correlation. */
+export function toEscalationView(row: UserTaskRow): EscalationView {
+  return {
+    userTaskKey: row.user_task_key,
+    kind: row.element_id,
+    kindLabel: row.kind_label,
+    prKey: row.subject_type === "pr" && parsePr(row.subject_key) ? row.subject_key : null,
+    subjectType: row.subject_type,
+    subjectKey: row.subject_key,
+    subjectTitle: row.subject_title,
+    subjectUrl: row.subject_url,
+    question: row.question,
+    formKey: row.form_key,
+    processKey: row.process_key,
+    formVariables: {
+      question: row.question,
+      subjectTitle: row.subject_title,
+      subjectUrl: row.subject_url,
+      formKey: row.form_key,
+    },
+  };
+}
+
+/** The structured open-escalation pointer surfaced on each active PR by `/status` (issue #666): the
+ *  completable `userTaskKey`, the escalation `kind` (BPMN `elementId`), and a one-line `summary` (the
+ *  raised question / findings). Derived from the SAME `user_tasks` read model as `listEscalations`
+ *  (no denormalised PR-row pointer, no second source of truth); the field is null when the PR is not
+ *  parked on an open escalation. */
+export interface OpenEscalation {
+  userTaskKey: string;
+  kind: string;
+  summary: string | null;
+}
+
+/** Pure: the structured `/status` open-escalation pointer for one open PR user-task row. */
+export function toOpenEscalation(row: UserTaskRow): OpenEscalation {
+  return { userTaskKey: row.user_task_key, kind: row.element_id, summary: row.question };
+}
+
 /** Human-readable label per escalation element. The set of keys is the closed set of user-task
  *  elements the Tasks inbox surfaces — an element absent from here is not an escalation and is
  *  ignored by `buildUserTaskRow`, so an arbitrary internal user task can never leak into the inbox. */

package/e2e/convergence-escalation.e2e.ts

@@ -28,6 +28,8 @@ import { dirname, join, resolve } from "node:path";
 import { after, before, describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { pollUserTasks } from "../app/service.ts";
+import { asEngineClient } from "./support/engine-client.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const DB_DIR = mkdtempSync(join(tmpdir(), "nwf-u4-"));
@@ -49,7 +51,11 @@ interface InboxTask {
 }
 
 interface StatusBody {
-  prs: Array<{ prKey: string; status: string; openEscalation: string | null }>;
+  prs: Array<{
+    prKey: string;
+    status: string;
+    openEscalation: { userTaskKey: string; kind: string; summary: string | null } | null;
+  }>;
 }
 
 interface TakenFlow {
@@ -149,17 +155,20 @@ describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
     assert.equal(task.elementId, "wait-answer", "the open task is the review-loop escalation userTask");
     assert.ok(task.userTaskKey, "the task carries a completable userTaskKey");
 
-    // The open escalation is DERIVED from the durable `escalations` audit row on the status
-    // endpoint — no denormalised `open_escalation_*` pointer is written or read.
+    // The open escalation is DERIVED from the `user_tasks` read model on the status endpoint — no
+    // denormalised `open_escalation_*` pointer is written or read. That read model is projected by
+    // `pollUserTasks` (part of the imperative main.ts poll loop the testkit does not run), so drive it
+    // explicitly (mirrors feature-run.e2e.ts) to project the parked `wait-answer` task first.
+    await pollUserTasks(app.db, asEngineClient(app.engine));
     const status = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
     assert.equal(status.status, 200, "the status endpoint responds");
     const statusRow = status.body.prs.find((p) => p.prKey === prKey);
     assert.ok(statusRow, "the escalated PR is listed as active");
     assert.equal(statusRow?.status, "escalated", "the PR reads as escalated");
     assert.equal(
-      statusRow?.openEscalation,
+      statusRow?.openEscalation?.summary,
       "Which retry cap?",
-      "the open escalation question is derived from the open escalations row",
+      "the open escalation question is derived from the user_tasks read model",
     );
 
     // Complete the escalation through the taskInbox completion route with the typed `answer`.
@@ -185,8 +194,11 @@ describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
     assert.equal(reviewCalls, 2, "the review agent ran a second round after the answer");
     assert.equal(capturedAnswer, answer, "the typed answer reached the resumed review round");
 
-    // The escalations row was retired to `answered` (the single source of truth the status endpoint
-    // derives from), so no open escalation lingers on the status endpoint once answered + resumed.
+    // The escalations row was retired to `answered` and the completed task's `user_tasks` row
+    // reconciles away, so no open escalation lingers on the status endpoint once answered + resumed.
+    // Re-run the projection (as the durable poller would) so the closed task's read-model row is
+    // deleted before re-reading /status.
+    await pollUserTasks(app.db, asEngineClient(app.engine));
     const afterStatus = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
     const afterRow = afterStatus.body.prs.find((p) => p.prKey === prKey);
     if (afterRow) {

package/e2e/retire-escalation-subsystem.e2e.ts

@@ -25,6 +25,8 @@ import { dirname, join, resolve } from "node:path";
 import { after, before, describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { pollUserTasks } from "../app/service.ts";
+import { asEngineClient } from "./support/engine-client.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const DB_DIR = mkdtempSync(join(tmpdir(), "nwf-u7-"));
@@ -46,7 +48,11 @@ interface InboxTask {
 }
 
 interface StatusBody {
-  prs: Array<{ prKey: string; status: string; openEscalation: string | null }>;
+  prs: Array<{
+    prKey: string;
+    status: string;
+    openEscalation: { userTaskKey: string; kind: string; summary: string | null } | null;
+  }>;
 }
 
 interface TableInfoRow {
@@ -227,14 +233,18 @@ describe("retire escalation subsystem (U7 — destructive contract phase)", () =
     assert.equal(task.elementId, "wait-answer", "the open task is the review-loop escalation userTask");
     assert.ok(task.userTaskKey, "the task carries a completable userTaskKey");
 
-    // The open escalation is DERIVED from the durable audit row — no denormalised pointer is written.
+    // The open escalation is DERIVED from the `user_tasks` read model — no denormalised pointer is
+    // written. That read model is projected by `pollUserTasks` (part of the imperative main.ts poll
+    // loop the testkit does not run), so drive it explicitly (mirrors feature-run.e2e.ts) to project
+    // the parked `wait-answer` task before reading /status.
+    await pollUserTasks(app.db, asEngineClient(app.engine));
     const status = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
     const statusRow = status.body.prs.find((p) => p.prKey === prKey);
     assert.equal(statusRow?.status, "escalated", "the PR reads as escalated");
     assert.equal(
-      statusRow?.openEscalation,
+      statusRow?.openEscalation?.summary,
       "Which retry cap?",
-      "the open escalation question is derived from the escalations audit row",
+      "the open escalation question is derived from the user_tasks read model",
     );
 
     // Answer through the inbox completion route with the typed `answer` (the re-issued-new path).
@@ -252,7 +262,10 @@ describe("retire escalation subsystem (U7 — destructive contract phase)", () =
     assert.equal(reviewCalls, 2, "the review agent ran a second round after the answer");
     assert.equal(capturedAnswer, answer, "the typed answer reached the resumed review round");
 
-    // No addressed escalation lingers — the audit row is the single source of truth.
+    // No addressed escalation lingers — the completed task's `user_tasks` row reconciles away. Re-run
+    // the projection (as the durable poller would) so the closed task's read-model row is deleted
+    // before re-reading /status.
+    await pollUserTasks(app.db, asEngineClient(app.engine));
     const afterStatus = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
     const afterRow = afterStatus.body.prs.find((p) => p.prKey === prKey);
     if (afterRow) {