@nanobpm/nano-workforce 0.169.0 → 0.170.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.170.1](https://github.com/nanobpm/nano-workforce/compare/v0.170.0...v0.170.1) (2026-08-31)
+
+### Documentation
+
+* **agent-guide:** make the operator guide tool-aware + tool↔curl crosswalk (N1) ([#669](https://github.com/nanobpm/nano-workforce/issues/669)) ([44c5937](https://github.com/nanobpm/nano-workforce/commit/44c5937fb3a1cdaa5a106d67ed16225c35d614f6)), closes [#664](https://github.com/nanobpm/nano-workforce/issues/664) [#666](https://github.com/nanobpm/nano-workforce/issues/666) [#667](https://github.com/nanobpm/nano-workforce/issues/667) [#665](https://github.com/nanobpm/nano-workforce/issues/665) [666/#667](https://github.com/666/nano-workforce/issues/667) [#666](https://github.com/nanobpm/nano-workforce/issues/666) [#667](https://github.com/nanobpm/nano-workforce/issues/667) [#665](https://github.com/nanobpm/nano-workforce/issues/665)
+
+## [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/agentGuide.ts

@@ -106,6 +106,7 @@ export const GUIDE_SECTIONS: readonly GuideSectionMeta[] = [
   { id: "unstick", summary: "Unstick a wedged process — publish a correlating message, cancel, or otherwise recover a stalled instance." },
   { id: "raise-issue", summary: "Raise an issue or open a PR against the nano-workforce repository itself." },
   { id: "delivery-graphs", summary: "Author, preview, compile/stage and run an agent-authored delivery graph (ADR 0005): node/wait/connector vocabulary." },
+  { id: "tool-crosswalk", summary: "Tool↔curl crosswalk: map every guide action to its projected MCP tool (status, version, urban_debug_* engine reads, escalation answer, cancel) with the curl no-MCP fallback." },
 ] as const;
 
 /** A parsed section: its stable id + summary (from the registry), the derived heading `title` (the

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. */