@nanobpm/nano-workforce 0.169.0 → 0.170.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

package/app/mcpExclusions.test.ts

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

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) {

package/openapi.yaml

@@ -108,8 +108,31 @@ components:
           type: string
           nullable: true
         openEscalation:
-          type: string
+          type: object
           nullable: true
+          additionalProperties: false
+          description: >-
+            The structured pointer to this PR's OPEN escalation when it is parked awaiting a human/agent
+            answer (issue #666), else null. Derived from the same `user_tasks` read model as
+            `listEscalations`, so `userTaskKey` is the completable key an agent answers via
+            `completeUserTask` / `agentCompleteEscalation` (no `/tasks/api/tasks` curl needed). `kind`
+            is the BPMN escalation elementId (e.g. `wait-answer`, `wait-merge-answer`); `summary` is the
+            raised question/findings (null when none was recorded).
+          required:
+            - userTaskKey
+            - kind
+            - summary
+          properties:
+            userTaskKey:
+              type: string
+              description: The completable engine user-task key (answer via completeUserTask / agentCompleteEscalation).
+            kind:
+              type: string
+              description: The BPMN escalation elementId (the escalation kind).
+            summary:
+              type: string
+              nullable: true
+              description: The raised question / findings, denormalised for display; null when none.
         updatedAt:
           type: string
         activeWorker:
@@ -130,6 +153,85 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ActivePr"
+    Escalation:
+      type: object
+      description: >-
+        One OPEN native user-task escalation awaiting a human/agent decision (issue #666), projected
+        from the `user_tasks` read model. `userTaskKey` is the completable key an agent answers via
+        `completeUserTask` / `agentCompleteEscalation`; `kind` is the BPMN escalation elementId.
+      additionalProperties: false
+      required:
+        - userTaskKey
+        - kind
+        - kindLabel
+        - prKey
+        - subjectType
+        - subjectKey
+        - subjectTitle
+        - subjectUrl
+        - question
+        - formKey
+        - processKey
+        - formVariables
+      properties:
+        userTaskKey:
+          type: string
+          description: The completable engine user-task key (answer via completeUserTask / agentCompleteEscalation).
+        kind:
+          type: string
+          description: The BPMN escalation elementId (e.g. wait-answer, wait-merge-answer, plan-review-decision, trial-merge-decision, feature-escalation).
+        kindLabel:
+          type: string
+          description: Human-readable kind label (e.g. "PR review", "Plan review", "Trial merge").
+        prKey:
+          type: string
+          nullable: true
+          description: The PR key when this escalation belongs to a PR (review/merge loop); null for feature / plan / delivery / agent subjects.
+        subjectType:
+          type: string
+          description: The domain subject kind — feature | plan | pr | delivery | agent.
+        subjectKey:
+          type: string
+          description: The subject aggregate key (feature_key / plan_key / pr_key).
+        subjectTitle:
+          type: string
+          description: The subject's human-readable title (coalesced to subjectKey when unknown).
+        subjectUrl:
+          type: string
+          nullable: true
+          description: An optional external link (the issue/PR URL); null when none.
+        question:
+          type: string
+          nullable: true
+          description: The raised question / findings / task text the loop or agent recorded; null when none.
+        formKey:
+          type: string
+          nullable: true
+          description: The deployed `.form` key of the parked user task, for rendering/answering; null when unresolved.
+        processKey:
+          type: string
+          nullable: true
+          description: The owning engine process-instance key; null when unknown.
+        formVariables:
+          type: object
+          additionalProperties: true
+          description: >-
+            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 }`).
+    EscalationList:
+      type: object
+      additionalProperties: false
+      required:
+        - count
+        - escalations
+      properties:
+        count:
+          type: integer
+        escalations:
+          type: array
+          items:
+            $ref: "#/components/schemas/Escalation"
     LineagePrView:
       type: object
       description: A member PR of a lineage thread (issue #245).
@@ -3057,6 +3159,36 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /escalations:
+    get:
+      operationId: listEscalations
+      summary: List every OPEN escalation awaiting a human/agent decision, with the completable userTaskKey.
+      description: >-
+        Discovery for the escalation-answer path (epic #664, issue #666): across every surfaced
+        escalation kind (PR review/merge loop, plan-review, empty-plan, trial-merge,
+        conformance-review, delivery human-step, feature/blocked, agent-permission and the shared
+        human-escalation cell), list each currently-open native user-task escalation with the
+        completable `userTaskKey` an agent then answers via `completeUserTask` /
+        `agentCompleteEscalation` — so a tool-aware agent never has to curl the un-projected
+        `/tasks/api/tasks` inbox to find keys. Read-only projection over the ONE `user_tasks` read
+        model the Tasks inbox and Convergence page consume (no second source of truth); a row is
+        present iff its task is open, so the list reflects live pending work.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The open escalations.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EscalationList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /lineage:
     get:
       operationId: getLineage

package/operations/listActivePrs.test.ts

@@ -8,14 +8,15 @@ import { noopLog } from "../test/log.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
 import handler from "./listActivePrs.ts";
 
-function memApp(rows: any[], escalations: any[] = []): AppApi {
+function memApp(rows: any[], userTaskRows: any[] = []): AppApi {
   const table = (name: string) => {
-    if (name === "escalations") {
+    if (name === "user_tasks") {
       return {
+        async all() {
+          return userTaskRows;
+        },
         async find(where: Record<string, unknown>) {
-          return escalations.filter((e) =>
-            Object.entries(where).every(([k, v]) => e[k] === v)
-          );
+          return userTaskRows.filter((t) => Object.entries(where).every(([k, v]) => t[k] === v));
         },
       };
     }
@@ -58,25 +59,42 @@ test("returns 200 with a count + projected active PRs", async () => {
   assertEquals(r.body.prs[0].processKey, "9");
 });
 
-test("surfaces openEscalation for an escalated PR from its open escalations row (both loops)", async () => {
-  // Regression: a merge-loop escalation parks on a message catch (no user task), so deriving
-  // openEscalation from a user-task probe hid it. Deriving from the canonical `escalations` row
-  // surfaces it. Two escalated PRs — one with an open row (visible), one already answered (null).
+test("surfaces the structured openEscalation from the user_tasks read model (both loops)", async () => {
+  // Issue #666: openEscalation is derived from the ONE `user_tasks` read model (the same surface
+  // `listEscalations` and the Convergence page consume), so `/status` carries the completable
+  // userTaskKey. A `user_tasks` row for a PR subject exists iff its review/merge-loop escalation task
+  // is currently open; a PR with no such row derives null. Cover a review-loop and a merge-loop PR.
   const app = memApp(
     [
       { pr_key: "o/r#10", repo: "o/r", number: 10, url: "u10", title: "merge blocked", status: "escalated", current_round: 3, process_key: "m1", updated_at: "2026-02-02" },
-      { pr_key: "o/r#11", repo: "o/r", number: 11, url: "u11", title: "answered", status: "escalated", current_round: 4, process_key: "m2", updated_at: "2026-02-01" },
+      { pr_key: "o/r#11", repo: "o/r", number: 11, url: "u11", title: "no open task", status: "escalated", current_round: 4, process_key: "m2", updated_at: "2026-02-01" },
     ],
     [
-      { id: 1, pr_key: "o/r#10", status: "open", question: "Resolve the conflict on the branch, then retry?" },
-      { id: 2, pr_key: "o/r#11", status: "answered", question: "old question" },
+      {
+        user_task_key: "ut-10",
+        element_id: "wait-merge-answer",
+        kind_label: "PR merge",
+        subject_type: "pr",
+        subject_key: "o/r#10",
+        subject_title: "merge blocked",
+        subject_url: null,
+        question: "Resolve the conflict on the branch, then retry?",
+        process_key: "m1",
+        form_key: null,
+        created_at: "2026-02-02",
+        updated_at: "2026-02-02",
+      },
     ],
   );
   const res = (await handler(input(), app)) as any;
   assertEquals(res.status, 200);
   const p10 = res.body.prs.find((p: any) => p.prKey === "o/r#10");
   const p11 = res.body.prs.find((p: any) => p.prKey === "o/r#11");
-  assertEquals(p10.openEscalation, "Resolve the conflict on the branch, then retry?");
+  assertEquals(p10.openEscalation, {
+    userTaskKey: "ut-10",
+    kind: "wait-merge-answer",
+    summary: "Resolve the conflict on the branch, then retry?",
+  });
   assertEquals(p11.openEscalation, null);
 });
 

package/operations/listEscalations.test.ts

@@ -0,0 +1,215 @@
+// Tests for GET /app/api/escalations operation `listEscalations` (epic #664, issue #666).
+//
+// The read tool that lists EVERY open native user-task escalation with its completable `userTaskKey`,
+// so a tool-aware agent discovers keys on-tool instead of curling the un-projected `/tasks/api/tasks`
+// inbox. It projects the ONE `user_tasks` read model (the same surface the Tasks inbox / Convergence
+// page consume) via the pure `toEscalationView` derivation — no second source of truth.
+//
+// The headline round-trip test proves the acceptance criterion: an open escalation is listed by
+// `listEscalations` with the EXACT `userTaskKey` that `completeUserTask` then resolves.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import completeHandler from "./completeUserTask.ts";
+import listHandler from "./listEscalations.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: in-memory doubles, mirrors sibling op tests
+function memApp(
+  seedUserTasks: Record<string, unknown>[],
+  openTasks: { userTaskKey: string; elementId?: string }[],
+): {
+  app: AppApi;
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  stores: Record<string, any[]>;
+  completed: { userTaskKey: string; variables: Record<string, unknown> }[];
+} {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  const stores: Record<string, any[]> = { user_tasks: [...seedUserTasks] };
+  const completed: { userTaskKey: string; variables: Record<string, unknown> }[] = [];
+  function tbl(name: string, pk: string) {
+    // biome-ignore lint/suspicious/noExplicitAny: see above
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async insert(row: any) {
+        rows.push({ ...row });
+        return rows.length;
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async all() {
+        return [...rows];
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async find(where: any = {}) {
+        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async delete(id: any) {
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const engine = {
+    openUserTasks: async () => openTasks,
+    searchUserTasks: async () => openTasks,
+    completeUserTask: async (userTaskKey: string, variables: Record<string, unknown>) => {
+      completed.push({ userTaskKey, variables });
+    },
+  };
+  const app = {
+    data: { table: (n: string, pk: string) => tbl(n, pk) },
+    engine,
+    log: noopLog(),
+    // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  } as any as AppApi;
+  return { app, stores, completed };
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+async function callList(app: AppApi): Promise<any> {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  return (await listHandler({ req: { headers: new Headers() } as any, params: {}, query: {}, body: undefined } as any, app)) as any;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+async function callComplete(app: AppApi, body: unknown): Promise<any> {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  return (await completeHandler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+function utRow(over: Record<string, unknown>): Record<string, unknown> {
+  return {
+    user_task_key: "ut-x",
+    element_id: "wait-answer",
+    kind_label: "PR review",
+    subject_type: "pr",
+    subject_key: "acme/repo#7",
+    subject_title: "Add widget",
+    subject_url: "https://github.com/acme/repo/pull/7",
+    question: "Which API version?",
+    process_key: "pi-1",
+    form_key: "form-pr",
+    created_at: "2026-01-01T00:00:00.000Z",
+    updated_at: "2026-01-01T00:00:00.000Z",
+    ...over,
+  };
+}
+
+test("listEscalations: round-trip — the listed userTaskKey is exactly what completeUserTask resolves", async () => {
+  const { app, stores, completed } = memApp(
+    [utRow({ user_task_key: "ut-answer", element_id: "wait-answer" })],
+    [{ userTaskKey: "ut-answer", elementId: "wait-answer" }],
+  );
+
+  const listed = await callList(app);
+  assertEquals(listed.status, 200);
+  assertEquals(listed.body.count, 1);
+  const esc = listed.body.escalations[0];
+  assertEquals(esc.userTaskKey, "ut-answer");
+  assertEquals(esc.kind, "wait-answer");
+  assertEquals(esc.prKey, "acme/repo#7");
+  assertEquals(esc.question, "Which API version?");
+  assertEquals(esc.formKey, "form-pr");
+
+  // Answer the exact key the list handed back — it resolves via the canonical completer.
+  const done = await callComplete(app, { userTaskKey: esc.userTaskKey, variables: { answer: "v2" } });
+  assertEquals(done.status, 200);
+  assertEquals(done.body.ok, true);
+  assertEquals(done.body.elementId, "wait-answer");
+  assertEquals(completed, [{ userTaskKey: "ut-answer", variables: { answer: "v2" } }]);
+  // The answered task's read-model row is dropped, so a re-list no longer shows it.
+  assertEquals(stores.user_tasks, []);
+  const reListed = await callList(app);
+  assertEquals(reListed.body.count, 0);
+});
+
+test("listEscalations: lists across all four escalation kinds, newest-updated first", async () => {
+  const { app } = memApp(
+    [
+      utRow({ user_task_key: "ut-pr", element_id: "wait-answer", updated_at: "2026-01-04T00:00:00.000Z" }),
+      utRow({
+        user_task_key: "ut-plan",
+        element_id: "plan-review-decision",
+        kind_label: "Plan review",
+        subject_type: "plan",
+        subject_key: "acme/repo#99",
+        updated_at: "2026-01-03T00:00:00.000Z",
+      }),
+      utRow({
+        user_task_key: "ut-trial",
+        element_id: "trial-merge-decision",
+        kind_label: "Trial merge",
+        subject_type: "plan",
+        subject_key: "acme/repo#99",
+        updated_at: "2026-01-02T00:00:00.000Z",
+      }),
+      utRow({
+        user_task_key: "ut-feat",
+        element_id: "feature-escalation",
+        kind_label: "Feature escalation",
+        subject_type: "feature",
+        subject_key: "acme/repo#42",
+        updated_at: "2026-01-01T00:00:00.000Z",
+      }),
+    ],
+    [],
+  );
+
+  const res = await callList(app);
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 4);
+  assertEquals(
+    res.body.escalations.map((e: { userTaskKey: string }) => e.userTaskKey),
+    ["ut-pr", "ut-plan", "ut-trial", "ut-feat"],
+  );
+  // Non-PR subjects carry a null prKey; the PR subject carries the pr key.
+  const byKey = Object.fromEntries(res.body.escalations.map((e: { userTaskKey: string }) => [e.userTaskKey, e]));
+  assertEquals(byKey["ut-pr"].prKey, "acme/repo#7");
+  assertEquals(byKey["ut-plan"].prKey, null);
+  assertEquals(byKey["ut-feat"].subjectType, "feature");
+});
+
+test("listEscalations: empty when no open escalations", async () => {
+  const { app } = memApp([], []);
+  const res = await callList(app);
+  assertEquals(res.status, 200);
+  assertEquals(res.body, { count: 0, escalations: [] });
+});
+
+// The optional shared-secret guard is captured at module load from NANO_PR_WEBHOOK_SECRET, so
+// cache-bust re-import the handler with the env set to exercise both the rejected (401, missing
+// header) and authorized (200, correct header) paths deterministically — mirrors the read-door
+// guard tests on sibling ops (listActivePrs, listLibrary).
+test("listEscalations: shared-secret guard — 401 without x-hook-secret, 200 with it", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./listEscalations.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof listHandler;
+    const { app } = memApp([], []);
+    // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+    const bad = (await guarded({ req: { headers: new Headers() } as any, params: {}, query: {}, body: undefined } as any, app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(
+      // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+      { req: { headers: new Headers({ "x-hook-secret": "s3cr3t" }) } as any, params: {}, query: {}, body: undefined } as any,
+      app,
+      // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+    )) as any;
+    assertEquals(ok.status, 200);
+    assert("count" in ok.body);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/listEscalations.ts

@@ -0,0 +1,32 @@
+// GET /app/api/escalations → operationId `listEscalations` (epic #664, issue #666). Discovery for the
+// escalation-answer path: list EVERY currently-open native user-task escalation — across every
+// surfaced kind (PR review/merge loop, plan-review, empty-plan, trial-merge, conformance-review,
+// delivery human-step, feature/blocked, agent-permission and the shared human-escalation cell) —
+// with the completable `userTaskKey` an agent then answers via
+// `completeUserTask` / `agentCompleteEscalation`. This closes the fallback where an agent had to curl
+// the un-projected `/tasks/api/tasks` inbox to find keys before answering.
+//
+// Read-only projection over the ONE `user_tasks` read model the Tasks inbox and Convergence page
+// consume (`userTasks` + the pure `toEscalationView` derivation in app/userTasks.ts) — NOT a second
+// source of truth. A row exists iff its task is open, so the list reflects live pending work.
+//
+// The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`):
+// when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset →
+// open (unchanged default), mirroring `listActivePrs`.
+import { toEscalationView, userTasks } from "../app/userTasks.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("listEscalations", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listEscalations rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const rows = await userTasks(app.data).all();
+  const escalations = rows
+    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0))
+    .map(toEscalationView);
+  return { status: 200, body: { count: escalations.length, escalations } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.169.0",
+  "version": "0.170.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",