@nanobpm/nano-workforce 0.63.0 → 0.65.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.65.0](https://github.com/nanobpm/nano-workforce/compare/v0.64.0...v0.65.0) (2026-08-13)
+
+
+### Features
+
+* surface native feature-run escalations in the nwf UI ([#213](https://github.com/nanobpm/nano-workforce/issues/213)) ([cf14724](https://github.com/nanobpm/nano-workforce/commit/cf1472419e2c68be4902a1fce2dabfcf39f2ae54)), closes [#210](https://github.com/nanobpm/nano-workforce/issues/210) [#210](https://github.com/nanobpm/nano-workforce/issues/210)
+
+# [0.64.0](https://github.com/nanobpm/nano-workforce/compare/v0.63.0...v0.64.0) (2026-08-13)
+
+
+### Features
+
+* type workers off the generated data envelope ([#201](https://github.com/nanobpm/nano-workforce/issues/201)) ([#208](https://github.com/nanobpm/nano-workforce/issues/208)) ([792083f](https://github.com/nanobpm/nano-workforce/commit/792083f153050862a11224288b0e27e769ab06ba)), closes [nano-ide#225](https://github.com/nano-ide/issues/225) [#225](https://github.com/nanobpm/nano-workforce/issues/225) [#228](https://github.com/nanobpm/nano-workforce/issues/228) [#211](https://github.com/nanobpm/nano-workforce/issues/211) [#211](https://github.com/nanobpm/nano-workforce/issues/211)
+
 # [0.63.0](https://github.com/nanobpm/nano-workforce/compare/v0.62.0...v0.63.0) (2026-08-13)
 
 

package/app/agentCompletion.test.ts

@@ -16,6 +16,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertRejects } from "#test-assert";
 import {
   completeEscalationAsAgent,
+  completeEscalationAsHuman,
   completeUserTaskAttributed,
   latestCompletion,
   revertAgentCompletion,
@@ -139,6 +140,56 @@ test("agent completer is a no-op for an unknown userTaskKey", async () => {
   assertEquals(completed.length, 0);
 });
 
+test("a HUMAN operator completes a feature escalation via the SAME attributed resume path (issue #210)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-1", elementId: "feature-escalation" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-1",
+    operatorId: "alice",
+    variables: { resolution: "answer", answer: "use v2" },
+  });
+
+  assertEquals(r.ok, true);
+  assertEquals(r.elementId, "feature-escalation");
+
+  // Identical resume path to the agent/task-inbox: completeUserTask with the exact typed variables.
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].variables, { resolution: "answer", answer: "use v2" });
+
+  // Attribution recorded as a HUMAN completion — the authority, so NOT reversible.
+  const row = stores.task_completions.rows[0] as TaskCompletion;
+  assertEquals(row.actor_kind, "human");
+  assertEquals(row.actor_id, "alice");
+  assertEquals(row.reversible, 0, "a human completion is the authority (not reversible)");
+});
+
+test("human completer refuses a non-escalation user task and is a no-op for an unknown key", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-x", elementId: "decide" }]);
+
+  const notEsc = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-x",
+    operatorId: "alice",
+    variables: { resolution: "abandon" },
+  });
+  assertEquals(notEsc.ok, false);
+  assertEquals(notEsc.reason, "not an escalation task");
+
+  const missing = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-missing",
+    operatorId: "alice",
+    variables: { resolution: "abandon" },
+  });
+  assertEquals(missing.ok, false);
+  assertEquals(missing.reason, "no open escalation task");
+
+  assertEquals(completed.length, 0, "neither refusal completes a task");
+  assertEquals(stores.task_completions.rows.length, 0, "and no attribution row is written");
+});
+
 test("a human can revert/override an agent completion (recording who + when + corrective note)", async () => {
   const stores = { task_completions: { rows: [] as any[], key: "id" } };
   const data = memData(stores);

package/app/agentCompletion.ts

@@ -148,6 +148,23 @@ export interface AgentCompleteResult {
   elementId?: string;
 }
 
+/** Resolve a parked escalation user task by key: return its `elementId` if it is one of the migrated
+ *  escalation tasks, or a failure reason otherwise. Shared by the agent and human completers so both
+ *  refuse a non-escalation / missing target the exact same way (a key with no matching open
+ *  escalation task is a 404-style no-op). */
+async function resolveEscalationTask(
+  engine: EngineClient,
+  userTaskKey: string,
+): Promise<{ ok: true; elementId: string } | { ok: false; reason: string }> {
+  const open = await engine.searchUserTasks();
+  const match = open.find((t) => t.userTaskKey === userTaskKey);
+  if (!match) return { ok: false, reason: "no open escalation task" };
+  if (!match.elementId || !ESCALATION_TASK_ELEMENTS.has(match.elementId)) {
+    return { ok: false, reason: "not an escalation task" };
+  }
+  return { ok: true, elementId: match.elementId };
+}
+
 /** Complete an escalation user task AS AN AGENT (ADR 0046). Resolves the parked task by its key,
  *  refuses anything that is not one of the migrated escalation tasks, and routes the typed form
  *  variables through the shared attributed completer with the agent's identity. Reuses the exact
@@ -163,24 +180,45 @@ export async function completeEscalationAsAgent(
   const agentId = input.agentId.trim();
   if (!agentId) return { ok: false, reason: "agentId is required" };
 
-  const open = await engine.searchUserTasks();
-  const match = open.find((t) => t.userTaskKey === userTaskKey);
-  if (!match) return { ok: false, reason: "no open escalation task" };
-  if (!match.elementId || !ESCALATION_TASK_ELEMENTS.has(match.elementId)) {
-    return { ok: false, reason: "not an escalation task" };
-  }
+  const resolved = await resolveEscalationTask(engine, userTaskKey);
+  if (!resolved.ok) return resolved;
 
   const { completionId } = await completeUserTaskAttributed(
     data,
     engine,
-    {
-      userTaskKey,
-      elementId: match.elementId,
-      variables: input.variables,
-    },
+    { userTaskKey, elementId: resolved.elementId, variables: input.variables },
     { kind: "agent", id: agentId },
   );
-  return { ok: true, completionId, userTaskKey, elementId: match.elementId };
+  return { ok: true, completionId, userTaskKey, elementId: resolved.elementId };
+}
+
+/** Complete an escalation user task AS A HUMAN operator (issue #210). The exact twin of
+ *  `completeEscalationAsAgent`, but attributed to a human: it drives the SAME canonical
+ *  `completeUserTaskAttributed` with the operator's typed form variables, so the nwf UI's answer
+ *  affordance resumes the process through the one implementation a human uses from the task inbox —
+ *  no parallel completion path — while recording WHO answered in the `task_completions` ledger. A
+ *  human completion is the authority (not reversible). A key with no matching open escalation task is
+ *  a 404-style no-op. */
+export async function completeEscalationAsHuman(
+  data: DataLayer,
+  engine: EngineClient,
+  input: { userTaskKey: string; variables: Record<string, unknown>; operatorId: string },
+): Promise<AgentCompleteResult> {
+  const userTaskKey = input.userTaskKey.trim();
+  if (!userTaskKey) return { ok: false, reason: "userTaskKey is required" };
+  const operatorId = input.operatorId.trim();
+  if (!operatorId) return { ok: false, reason: "operatorId is required" };
+
+  const resolved = await resolveEscalationTask(engine, userTaskKey);
+  if (!resolved.ok) return resolved;
+
+  const { completionId } = await completeUserTaskAttributed(
+    data,
+    engine,
+    { userTaskKey, elementId: resolved.elementId, variables: input.variables },
+    { kind: "human", id: operatorId },
+  );
+  return { ok: true, completionId, userTaskKey, elementId: resolved.elementId };
 }
 
 export interface RevertResult {

package/app/feature.ts

@@ -45,12 +45,25 @@ export interface FeatureRun {
    * outcome is written to `status` itself; this carries the sub-state / note (e.g. "merged",
    * "waiting_review", or "operator: <note>"). */
   delivery_label: string | null;
+  /** The parked `feature-escalation` user task's `question`, persisted at escalation entry by the
+   * `record-feature-escalation` worker (NOT by `pollFeatureEscalations` while parked, which
+   * deliberately never writes it) so the pages can show what the agent asked. NULL whenever the run
+   * is not parked at an escalation — cleared on the exit paths (`record-feature` / the answer
+   * operation), and, as a self-heal, by `pollFeatureEscalations` when a previously-observed task is
+   * completed out-of-band (see `deriveFeatureEscalationPatch`). */
+  escalation_question: string | null;
+  /** The completable native `feature-escalation` user-task key the answer affordance posts to
+   * (`completeUserTaskAttributed`) and the pages gate the answer controls on (`showWhenField`). Set by
+   * `pollFeatureEscalations` while parked; NULL otherwise. */
+  escalation_user_task_key: string | null;
   created_at: string;
   updated_at: string;
 }
 
 export const FEATURE_RUN_STATUSES = [
-  "running", // the agent is implementing (including while parked at an escalation user task)
+  "running", // the agent is implementing
+  "escalated", // NON-terminal: the run is parked at the `feature-escalation` operator user task,
+  // waiting on a human answer (denormalised from the parked user task by pollFeatureEscalations)
   "opened", // a PR was raised and the run ends here (converge was not requested)
   "converging", // the opened PR was handed to the convergence loop (live state via pr_key → pull_requests)
   "awaiting_operator", // NON-terminal: the run is blocked and parked at the feature-blocked operator user task
@@ -70,7 +83,9 @@ export type FeatureRunStatus = typeof FEATURE_RUN_STATUSES[number];
  * `merged`/`converged`/`abandoned` — those are equally terminal, so redispatch gating is unaffected.
  * `awaiting_operator` is deliberately EXCLUDED (non-terminal): while a blocked run is parked at the
  * feature-blocked operator user task its instance is still alive, so a re-dispatch of the same issue
- * must short-circuit (no orphaned parallel instance) until the operator acknowledges it. */
+ * must short-circuit (no orphaned parallel instance) until the operator acknowledges it. `escalated`
+ * is EXCLUDED for the same reason: a run parked at the `feature-escalation` user task is still alive,
+ * so a re-dispatch must short-circuit until the human answers (or the SLA fires). */
 export const FEATURE_TERMINAL_STATUSES: readonly FeatureRunStatus[] = [
   "opened",
   "converging",
@@ -117,6 +132,65 @@ export function deriveFeatureDelivery(prStatus: string | null): FeatureDeliveryR
   }
 }
 
+/** The `feature-escalation` user-task element id (feature.bpmn) — the native operator wait a run
+ * parks on when the agent escalates. `pollFeatureEscalations` reconciles it onto the read model. */
+export const FEATURE_ESCALATION_ELEMENT = "feature-escalation";
+
+/** The parked `feature-escalation` user task, as `pollFeatureEscalations` observes it via
+ * `searchUserTasks`: the completable user-task key the pages drive an attributed answer against.
+ *
+ * The agent's `question` is NOT read from here — the WASM testkit engine does not surface a user
+ * task's `zeebe:ioMapping`-mapped local variables through `searchUserTasks`, so relying on it would
+ * make the question untestable. Instead the `record-feature-escalation` service task (feature.bpmn)
+ * persists `question` onto the row at escalation entry — see `workers/record-feature-escalation`. */
+export interface FeatureEscalationParked {
+  userTaskKey: string;
+}
+
+/** Pure source of truth for the escalation read-model reconcile (`pollFeatureEscalations`): given a
+ * run and whether it is currently parked at `feature-escalation`, return the minimal `feature_runs`
+ * patch reconciling the run's LIVENESS (status + completable-task pointer) with the observed park
+ * state (or null when nothing changed, so the poller skips the write). Idempotent, and — crucially —
+ * self-healing across the brief window between the `record-feature-escalation` service task and the
+ * user task actually appearing: a premature "not parked" reset to `running` is re-flipped to
+ * `escalated` on the next pass once the task is observed.
+ *
+ * - parked → flip `status` to `escalated` and denormalise the completable `userTaskKey` so the pages
+ *   can drive an attributed answer. It never writes `escalation_question` while parked — that is the
+ *   service task's to own (set) and the exit paths' to clear (record-feature / the answer operation),
+ *   so the poller can never clobber the persisted question during that self-healing window.
+ * - un-parked → clear the completable-task pointer; a run still marked `escalated` has resumed
+ *   (answered / looped back to implement-task), so it returns to `running`. A run already advanced
+ *   past `escalated` by a downstream worker keeps that status — only the pointer is cleared. Once the
+ *   pointer was actually OBSERVED (non-NULL) and the task is now gone, `escalation_question` is also
+ *   cleared here, self-healing a question left populated when the task was completed out-of-band
+ *   (bypassing the answer operation). This is gated on the observed pointer precisely so it cannot
+ *   fire in the pre-observation self-healing window, where the pointer is still NULL. */
+export function deriveFeatureEscalationPatch(
+  run: Pick<FeatureRun, "status" | "escalation_user_task_key">,
+  parked: FeatureEscalationParked | null,
+): Partial<FeatureRun> | null {
+  const patch: Partial<FeatureRun> = {};
+  if (parked) {
+    if (run.status !== "escalated") patch.status = "escalated";
+    if (run.escalation_user_task_key !== parked.userTaskKey) patch.escalation_user_task_key = parked.userTaskKey;
+  } else {
+    if (run.status === "escalated") patch.status = "running";
+    // Un-park cleanup — fires ONLY once the poller has actually OBSERVED the task (pointer non-NULL)
+    // and it is now gone. This self-heals a `question` left populated when the task was completed
+    // out-of-band (e.g. an external task UI, bypassing the answer operation that normally clears it),
+    // which would otherwise keep the UI showing an Escalation on a run that has resumed. Gating on
+    // the pointer being non-NULL is what makes it safe: during the brief self-healing window between
+    // `record-feature-escalation` (which persists the question but leaves the pointer NULL) and the
+    // task appearing, the pointer is NULL, so this never clobbers the freshly-persisted question.
+    if (run.escalation_user_task_key !== null) {
+      patch.escalation_user_task_key = null;
+      patch.escalation_question = null;
+    }
+  }
+  return Object.keys(patch).length > 0 ? patch : null;
+}
+
 export const featureRuns = (data: DataLayer) => data.table<FeatureRun>("feature_runs", "feature_key");
 
 /** The deterministic task id for a single-issue run — the implementation agent branches
@@ -157,6 +231,8 @@ export async function startFeature(
       auto_merge: autoMerge ? 1 : 0,
       outcome: null,
       delivery_label: null,
+      escalation_question: null,
+      escalation_user_task_key: null,
       updated_at: ts,
     });
   } else {
@@ -173,6 +249,8 @@ export async function startFeature(
       auto_merge: autoMerge ? 1 : 0,
       outcome: null,
       delivery_label: null,
+      escalation_question: null,
+      escalation_user_task_key: null,
       created_at: ts,
       updated_at: ts,
     });

package/app/featureEscalation.test.ts

@@ -0,0 +1,180 @@
+// Read-model derivation test for the FEATURE-run escalation reconcile (issue #210 — feature-run
+// escalations were invisible in the nwf UI). When a feature run escalates it parks on the native
+// `feature-escalation` user task; `feature_runs` (which the pages read) stayed `running` with
+// nothing to show. Two collaborators fix that: the `record-feature-escalation` service task persists
+// the `status`-flip's companion `question` at escalation entry (it can read the process variable
+// while it is still in scope), and `deriveFeatureEscalationPatch` — the pure source of truth tested
+// here — reconciles the run's LIVENESS (status + completable-task pointer) that `pollFeatureEscalations`
+// projects onto the row. The poller never touches `escalation_question`, so it can never clobber the
+// service task's write during the self-healing window before the user task is observable.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { deriveFeatureEscalationPatch } from "./feature.ts";
+import { pollFeatureEscalations } from "./service.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory table double, mirrors featureDelivery.test.ts
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    // biome-ignore lint/suspicious/noExplicitAny: see above
+    const rows = (stores[name] ??= [] as any[]);
+    // biome-ignore lint/suspicious/noExplicitAny: see above
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      // 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 data = { table: (n: string, pk?: string) => tbl(n, pk) } as unknown as DataLayer;
+  return { data, stores };
+}
+
+/** A fake engine whose open user tasks are keyed by processInstanceKey (the only field
+ *  pollFeatureEscalations queries on). */
+function fakeEngine(byInstance: Record<string, { userTaskKey: string; elementId?: string }[]>): EngineClient {
+  return {
+    searchUserTasks: (filter?: { processInstanceKey?: string }) =>
+      Promise.resolve(filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : []),
+  } as unknown as EngineClient;
+}
+
+test("deriveFeatureEscalationPatch: a running run parked at feature-escalation flips to escalated + records the key", () => {
+  const patch = deriveFeatureEscalationPatch(
+    { status: "running", escalation_user_task_key: null },
+    { userTaskKey: "ut-9" },
+  );
+  assertEquals(patch, { status: "escalated", escalation_user_task_key: "ut-9" });
+});
+
+test("deriveFeatureEscalationPatch: an already-escalated run with the key recorded yields no patch (idempotent)", () => {
+  const patch = deriveFeatureEscalationPatch(
+    { status: "escalated", escalation_user_task_key: "ut-9" },
+    { userTaskKey: "ut-9" },
+  );
+  assertEquals(patch, null);
+});
+
+test("deriveFeatureEscalationPatch: an escalated run that un-parked resumes to running, pointer + question cleared", () => {
+  const patch = deriveFeatureEscalationPatch({ status: "escalated", escalation_user_task_key: "ut-9" }, null);
+  assertEquals(patch, { status: "running", escalation_user_task_key: null, escalation_question: null });
+});
+
+test("deriveFeatureEscalationPatch: a run past escalated with a stale pointer clears the pointer + question", () => {
+  const patch = deriveFeatureEscalationPatch({ status: "awaiting_operator", escalation_user_task_key: "ut-9" }, null);
+  assertEquals(patch, { escalation_user_task_key: null, escalation_question: null });
+});
+
+// Self-heal: a task completed out-of-band (external UI, bypassing the answer operation) leaves the
+// run un-parked but with the pointer still recording the observed task. The poller clears BOTH the
+// pointer and the now-stale question so the UI stops surfacing an Escalation on a resumed run.
+test("deriveFeatureEscalationPatch: un-park after an out-of-band completion clears the stale question", () => {
+  const patch = deriveFeatureEscalationPatch({ status: "escalated", escalation_user_task_key: "ut-9" }, null);
+  assertEquals(patch?.escalation_question, null);
+});
+
+// The pre-observation self-healing window (record-feature-escalation has persisted the question but
+// the task is not yet visible, so the pointer is still NULL): a premature "not parked" pass must NOT
+// clobber the freshly-persisted question — only reset the transient status, re-flipped next pass.
+test("deriveFeatureEscalationPatch: the pre-observation self-healing window never clears the question", () => {
+  const patch = deriveFeatureEscalationPatch({ status: "escalated", escalation_user_task_key: null }, null);
+  assertEquals(patch, { status: "running" });
+});
+
+test("deriveFeatureEscalationPatch: a clean running run not parked yields no patch", () => {
+  const patch = deriveFeatureEscalationPatch({ status: "running", escalation_user_task_key: null }, null);
+  assertEquals(patch, null);
+});
+
+test("pollFeatureEscalations: a parked run is flipped to escalated with the completable key (question left to the service task)", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#1", status: "running", process_key: "100", escalation_question: null, escalation_user_task_key: null },
+  ];
+  const engine = fakeEngine({ "100": [{ userTaskKey: "ut-1", elementId: "feature-escalation" }] });
+
+  await pollFeatureEscalations(data, engine);
+
+  assertEquals(stores.feature_runs[0].status, "escalated");
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, "ut-1");
+  // The poller does not synthesise the question — that is the record-feature-escalation service task's.
+  assertEquals(stores.feature_runs[0].escalation_question, null);
+});
+
+test("pollFeatureEscalations: an escalated run whose task is gone resumes to running, clears the pointer + stale question", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#2", status: "escalated", process_key: "200", escalation_question: "Q", escalation_user_task_key: "ut-2" },
+  ];
+  const engine = fakeEngine({ "200": [] });
+
+  await pollFeatureEscalations(data, engine);
+
+  assertEquals(stores.feature_runs[0].status, "running");
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, null);
+  // The observed task is gone → self-heal the now-stale question so the UI stops surfacing it.
+  assertEquals(stores.feature_runs[0].escalation_question, null);
+});
+
+test("pollFeatureEscalations: a re-observed parked run keeps its persisted question, only filling the key", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#3", status: "escalated", process_key: "300", escalation_question: "kept", escalation_user_task_key: null },
+  ];
+  const engine = fakeEngine({ "300": [{ userTaskKey: "ut-3", elementId: "feature-escalation" }] });
+
+  await pollFeatureEscalations(data, engine);
+
+  assertEquals(stores.feature_runs[0].status, "escalated");
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, "ut-3");
+  assertEquals(stores.feature_runs[0].escalation_question, "kept");
+});
+
+test("pollFeatureEscalations: only touches running/escalated runs, and never one without a process_key", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#4", status: "opened", process_key: "400", escalation_question: null, escalation_user_task_key: null },
+    { feature_key: "o/r#5", status: "running", process_key: null, escalation_question: null, escalation_user_task_key: null },
+  ];
+  const engine = fakeEngine({ "400": [{ userTaskKey: "ut-4", elementId: "feature-escalation" }] });
+
+  await pollFeatureEscalations(data, engine);
+
+  // opened is terminal → not a candidate; running with no process_key → skipped.
+  assertEquals(stores.feature_runs[0].status, "opened");
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, null);
+  assertEquals(stores.feature_runs[1].status, "running");
+});
+
+test("pollFeatureEscalations: a parked non-escalation task (feature-blocked) does not flip the run", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#6", status: "running", process_key: "600", escalation_question: null, escalation_user_task_key: null },
+  ];
+  const engine = fakeEngine({ "600": [{ userTaskKey: "ut-6", elementId: "feature-blocked" }] });
+
+  await pollFeatureEscalations(data, engine);
+
+  assertEquals(stores.feature_runs[0].status, "running");
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, null);
+});

package/app/service.ts

@@ -9,7 +9,7 @@
 // `Table<T>` surface), not hand-written SQL. Row shapes are declared inline here.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
-import { deriveFeatureDelivery, featureRuns } from "./feature.ts";
+import { deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_ESCALATION_ELEMENT, type FeatureRun, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
   ensureFreshHeadRun,
@@ -1283,6 +1283,49 @@ export async function pollFeatureDelivery(data: DataLayer) {
   }
 }
 
+/** Reconcile each in-flight FEATURE run against its native `feature-escalation` user task (issue
+ * #210 — feature-run escalations were invisible in the nwf UI). When a feature run escalates it parks
+ * on the `feature-escalation` operator user task (an engine wait); no worker runs, so `feature_runs`
+ * — which the schema-driven pages read — stayed `running` with nothing to show. This is the
+ * `feature_runs` twin of `pollFeatureDelivery`: for each run that can be parked at (or resuming from)
+ * the escalation, read its open user tasks and project the parked task onto the row via the pure
+ * `deriveFeatureEscalationPatch` — flipping `status` to `escalated` and denormalising the escalation's
+ * completable `userTaskKey` so the pages can drive an answer, and flipping back to `running` (clearing
+ * the pointer) once it un-parks. It never writes `escalation_question` — that is persisted by the
+ * `record-feature-escalation` worker at escalation entry and cleared on the exit paths, so the poller
+ * can never clobber the source of truth for the question.
+ *
+ * Candidates are only the runs that could be parked here — `running` (may have just escalated) and
+ * `escalated` (may have just resumed) — queried via the `feature_runs(status)` index, so the pass
+ * stays O(in-flight), not O(total runs). Terminal-ward transitions THROUGH `record-feature` (answer
+ * → abandon, SLA auto-abandon, done) clear the pointer in that worker, so a run that has already left
+ * `escalated` never needs sweeping here. Best-effort + idempotent — per-run failures are isolated. */
+export async function pollFeatureEscalations(data: DataLayer, engine: EngineClient) {
+  const seen = new Set<string>();
+  const candidates: FeatureRun[] = [];
+  for (const status of ["running", "escalated"] as const) {
+    for (const run of await featureRuns(data).find({ status })) {
+      if (seen.has(run.feature_key)) continue;
+      seen.add(run.feature_key);
+      candidates.push(run);
+    }
+  }
+  for (const run of candidates) {
+    if (!run.process_key) continue;
+    try {
+      const tasks = await engine.searchUserTasks({ processInstanceKey: run.process_key });
+      const task = tasks.find((t) => t.elementId === FEATURE_ESCALATION_ELEMENT);
+      const parked = task ? { userTaskKey: task.userTaskKey } : null;
+      const patch = deriveFeatureEscalationPatch(run, parked);
+      if (patch) {
+        await featureRuns(data).update(run.feature_key, { ...patch, updated_at: now() });
+      }
+    } catch (err) {
+      console.error(`[poller] feature escalation ${run.feature_key}: ${err}`);
+    }
+  }
+}
+
 /** One full poll pass: advance the review stage, the merge stage, the wave-merge barrier, and
  * (when the engine REST endpoint is supplied) the job-activation visibility pass and the
  * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`. */
@@ -1297,6 +1340,7 @@ export async function pollOnce(
   await pollWaveGates(data, engine, token);
   await pollDelivery(data);
   await pollFeatureDelivery(data);
+  await pollFeatureEscalations(data, engine);
   if (engineRest) {
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);

package/db/migrations/031_feature_escalation_surface.sql

@@ -0,0 +1,28 @@
+-- Surface native feature-run escalations in the nwf UI (issue #210).
+--
+-- When a feature run (`feature.bpmn`) escalates to a human it parks on the native
+-- `feature-escalation` user task (`candidateGroups=operators`). That wait was
+-- invisible in the nwf UI: the schema-driven pages read `feature_runs`, but the
+-- open user task (the actual wait) is engine state, not a row here, so a run could
+-- sit blocked on a human decision indefinitely with no visible signal, and
+-- `feature_runs.status` stayed `running`.
+--
+-- The `record-feature-escalation` service task (feature.bpmn) runs on the
+-- `escalated` arm, before the user task is created, and persists the escalation
+-- onto the row: it flips `status` to `escalated` and denormalises the agent's
+-- `question` here (it reads the process variable while it is still in scope — the
+-- poller can't, as the WASM engine does not surface task-local user-task variables
+-- via `searchUserTasks`). The poller (`pollFeatureEscalations` in app/service.ts)
+-- then fills the parked `userTaskKey` in once the user task is observable, resets
+-- `status` back to `running` when the run un-parks, and `record-feature` / the
+-- answer operation clear both columns again on exit. Both columns are NULL
+-- whenever the run is not parked at `feature-escalation`.
+--
+-- `escalation_user_task_key` is the completable native user-task key the answer
+-- affordance posts to (`completeUserTaskAttributed`); it also gates the answer
+-- controls in the pages (`showWhenField`, which is JS-truthy, so NULL correctly
+-- hides them). Forward-only, additive (expand): both columns are nullable with no
+-- default. Numbered after the current highest prefix (030); the runner wraps each
+-- file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE feature_runs ADD COLUMN escalation_question TEXT;
+ALTER TABLE feature_runs ADD COLUMN escalation_user_task_key TEXT;

package/e2e/feature-run.e2e.ts

@@ -22,6 +22,7 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+import { pollFeatureEscalations } from "../app/service.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -56,6 +57,8 @@ interface FeatureRow {
   status: string;
   pr_key: string | null;
   delivery_label: string | null;
+  escalation_question: string | null;
+  escalation_user_task_key: string | null;
 }
 interface PrRow {
   pr_key: string;
@@ -253,4 +256,59 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
       },
     );
   });
+
+  test("escalate → the poller surfaces it on the read model, and the operator answer resolves it (issue #210)", async () => {
+    let calls = 0;
+    await withApp(
+      {
+        "senior:feature": () => {
+          calls += 1;
+          return calls === 1
+            ? { status: "escalated", question: "Which API should I use?", summary: "parked for a human" }
+            : { status: "opened", pr: "owner/repo#210", summary: "resumed and opened" };
+        },
+      },
+      { baseBranch: "epic/e2e" },
+      async ({ app, featureKey }) => {
+        // The `record-feature-escalation` service task runs on the escalated arm (before the user task),
+        // so the row already carries the flipped status + the agent's question when the run parks — the
+        // read model the pages read is no longer blind to the native user-task wait (the #210 bug).
+        const parked = await featureRow(app, featureKey);
+        assert.equal(parked.status, "escalated", "the escalated status is surfaced on the read model");
+        assert.equal(parked.escalation_question, "Which API should I use?", "the agent's question is surfaced");
+
+        // The poller fills in the completable user-task key (which the service task can't know — the
+        // task doesn't exist yet when it runs) so the UI can drive an attributed answer.
+        await pollFeatureEscalations(app.db, app.engine);
+        const escalated = await featureRow(app, featureKey);
+        assert.ok(escalated.escalation_user_task_key, "the poller denormalised the completable user-task key");
+        assert.equal(escalated.status, "escalated", "the run stays escalated while parked");
+
+        // Answer through the app's OWN operation (the nwf UI's answer affordance) — the attributed
+        // completer resumes the SAME implement task a human would from the task inbox.
+        const answered = await app.api?.call("answerFeatureEscalation", {
+          body: { userTaskKey: escalated.escalation_user_task_key, resolution: "answer", answer: "use v2" },
+        });
+        assert.equal(answered?.status, 200, "the operator answer completed the escalation task");
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("w_gw_answer->implement-task"),
+          `the answer re-dispatched the same implement task (flows: ${flows.join(", ")})`,
+        );
+        assert.equal(calls, 2, "the implementation agent was re-dispatched exactly once after the answer");
+
+        // The run opened its PR; the escalation pointer + question were cleared once resolved.
+        const settled = await featureRow(app, featureKey);
+        assert.equal(settled.status, "opened", "the resumed run opened its PR");
+        assert.equal(settled.escalation_user_task_key, null, "the escalation pointer was cleared once resolved");
+        assert.equal(settled.escalation_question, null, "the surfaced question was cleared once resolved");
+
+        // A further poll pass is an idempotent no-op — a terminal run is not a candidate.
+        await pollFeatureEscalations(app.db, app.engine);
+        assert.equal((await featureRow(app, featureKey)).status, "opened");
+      },
+    );
+  });
 });