@nanobpm/nano-workforce 0.64.0 → 0.65.0

package/openapi.yaml

@@ -925,6 +925,58 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /actions/answer-escalation:
+    post:
+      operationId: answerFeatureEscalation
+      summary: "Answer a native feature-run escalation (issue #210). Completes the parked
+        `feature-escalation` user task with the operator's typed form variables (resolution=answer/abandon
+        + guidance), driving the canonical attributed completer (completeUserTaskAttributed) — the same
+        resume path the task inbox uses, recording who answered. The poller then reconciles the run off
+        `escalated`. This is the nwf UI's answer affordance for a feature run parked on a human decision."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - userTaskKey
+                - resolution
+              properties:
+                userTaskKey:
+                  type: string
+                  minLength: 1
+                  description: The parked `feature-escalation` user-task key (feature_runs.escalation_user_task_key).
+                resolution:
+                  type: string
+                  enum: [answer, abandon]
+                  description: answer ⇒ re-dispatch the implement task with the guidance; abandon ⇒ give up on the task.
+                answer:
+                  type: string
+                  description: Guidance for the implementation agent. Required (non-blank) when resolution is answer.
+                operator:
+                  type: string
+                  description: Optional operator handle recorded in the attribution ledger; defaults to "operator".
+      responses:
+        "200":
+          description: The escalation user task was completed and the process resumed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field was missing/invalid, or the target is not an escalation task.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No open escalation user task matches the userTaskKey.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /hooks/agent-complete:
     post:
       operationId: agentCompleteEscalation

package/operations/answerFeatureEscalation.ts

@@ -0,0 +1,68 @@
+// POST /app/api/actions/answer-escalation → operationId `answerFeatureEscalation` (issue #210).
+// The nwf UI's answer affordance for a native feature-run escalation: an operator answers the parked
+// `feature-escalation` user task (resolution=answer/abandon + optional guidance) directly from the
+// Feature / Overview pages, instead of only from the generic task inbox.
+//
+// It routes through the ONE canonical attributed completer (`completeEscalationAsHuman` →
+// `completeUserTaskAttributed`), so the completion uses the exact same typed `.form` variables and
+// engine resume path a human drives from the task inbox — no parallel completion — while recording
+// WHO answered in the `task_completions` ledger. The poller then reconciles the run off `escalated`
+// (pollFeatureEscalations) once the task is gone.
+//
+// The runtime validates the body against openapi.yaml (`userTaskKey` + `resolution` required); this
+// delegate narrows the validated shape, enforces the answer/abandon contract, and builds the typed
+// completion variables the `feature-escalation` form + the `w_gw_answer` gateway expect.
+
+import { completeEscalationAsHuman } from "../app/agentCompletion.ts";
+import { featureRuns } from "../app/feature.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("answerFeatureEscalation", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("answer-escalation rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "userTaskKey and resolution are required" } };
+  }
+
+  const userTaskKey = str(body.userTaskKey);
+  if (!userTaskKey) return { status: 400, body: { ok: false, error: "userTaskKey is required" } };
+
+  const resolution = str(body.resolution);
+  if (resolution !== "answer" && resolution !== "abandon") {
+    return { status: 400, body: { ok: false, error: "resolution must be 'answer' or 'abandon'" } };
+  }
+
+  // The `feature-escalation` form completes with `{ resolution, answer }`; the `w_gw_answer` gateway
+  // re-dispatches implement-task with `answer` when resolution=answer, else routes to record-feature.
+  // Guidance is required for an answer (an empty answer re-dispatches the agent with nothing new).
+  const answer = str(body.answer);
+  if (resolution === "answer" && !answer) {
+    return { status: 400, body: { ok: false, error: "answer (guidance) is required when resolution is 'answer'" } };
+  }
+  const variables: Record<string, unknown> = resolution === "answer" ? { resolution, answer } : { resolution };
+
+  // The completing operator, for the attribution ledger. Optional — the UI has no per-operator auth,
+  // so default to a generic handle rather than blocking the answer.
+  const operatorId = str(body.operator) || "operator";
+
+  const r = await completeEscalationAsHuman(app.data, app.engine, { userTaskKey, operatorId, variables });
+  if (r.ok) {
+    // Reconcile this operation's OWN action immediately: clear the denormalised escalation pointer +
+    // question so the pages stop offering an answer affordance for a task that is now completed. Leave
+    // `status` to the poller (escalated → running on the answer loop) / record-feature (terminal on
+    // abandon), so we never overwrite a status the resumed run has already advanced to.
+    for (const run of await featureRuns(app.data).find({ escalation_user_task_key: userTaskKey })) {
+      await featureRuns(app.data).update(run.feature_key, {
+        escalation_question: null,
+        escalation_user_task_key: null,
+        updated_at: new Date().toISOString(),
+      });
+    }
+    app.log.info("operator answered feature escalation", { userTaskKey, resolution, elementId: r.elementId });
+    return { status: 200, body: { ok: true, completionId: r.completionId, elementId: r.elementId } };
+  }
+  const status = r.reason === "no open escalation task" ? 404 : 400;
+  app.log.warn("answer-escalation: not completed", { userTaskKey, reason: r.reason });
+  return { status, body: { ok: false, error: r.reason } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.64.0",
+  "version": "0.65.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",

package/pages/feature.page.json

@@ -60,16 +60,17 @@
           "source": "app",
           "table": "feature_runs",
           "orderBy": { "field": "updated_at", "dir": "desc" },
-          "filter": [{ "field": "status", "in": ["running", "awaiting_operator"] }]
+          "filter": [{ "field": "status", "in": ["running", "escalated", "awaiting_operator"] }]
         },
         "tabs": [
-          { "label": "Active", "filter": [{ "field": "status", "in": ["running", "awaiting_operator"] }] },
+          { "label": "Active", "filter": [{ "field": "status", "in": ["running", "escalated", "awaiting_operator"] }] },
           { "label": "History", "filter": [{ "field": "status", "in": ["opened", "converging", "merged", "converged", "blocked", "skipped", "failed", "abandoned"] }] },
           { "label": "All", "filter": [] }
         ],
         "columns": [
           { "field": "feature_key", "header": "Feature", "linkField": "issue_url" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "escalation_question", "header": "Escalation" },
           { "field": "base_branch", "header": "Base branch" },
           { "field": "pr_key", "header": "PR", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
           { "field": "delivery_label", "header": "Delivery" },
@@ -77,7 +78,42 @@
           { "field": "auto_merge", "header": "Auto-merge" },
           { "field": "outcome", "header": "Outcome" },
           { "field": "updated_at", "header": "Updated" }
-        ]
+        ],
+        "rowActions": [
+          {
+            "label": "Abandon",
+            "confirm": "Abandon this escalated task? The run gives up on it (no PR).",
+            "showWhenField": "escalation_user_task_key",
+            "action": {
+              "path": "/app/api/actions/answer-escalation",
+              "body": { "userTaskKey": "{{row.escalation_user_task_key}}", "resolution": "abandon" }
+            }
+          }
+        ],
+        "detail": {
+          "fields": [
+            { "field": "escalation_question", "label": "Escalation question" },
+            { "field": "outcome", "label": "Outcome" },
+            { "field": "delivery_label", "label": "Delivery" }
+          ],
+          "form": {
+            "showWhenField": "escalation_user_task_key",
+            "title": "Answer escalation",
+            "promptField": "escalation_question",
+            "inputKey": "answer",
+            "inputLabel": "Guidance for the implementation agent",
+            "submitLabel": "Answer & re-dispatch",
+            "action": {
+              "path": "/app/api/actions/answer-escalation",
+              "successLabel": "Answered — the agent will resume",
+              "body": {
+                "userTaskKey": "{{row.escalation_user_task_key}}",
+                "resolution": "answer",
+                "answer": "{{form.answer}}"
+              }
+            }
+          }
+        }
       }
     }
   ]

package/pages/overview.page.json

@@ -119,18 +119,53 @@
           "source": "app",
           "table": "feature_runs",
           "orderBy": { "field": "updated_at", "dir": "desc" },
-          "filter": [{ "field": "status", "in": ["running", "awaiting_operator"] }]
+          "filter": [{ "field": "status", "in": ["running", "escalated", "awaiting_operator"] }]
         },
         "columns": [
           { "field": "feature_key", "header": "Feature", "link": { "kind": "page", "page": "feature", "keyField": "feature_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "escalation_question", "header": "Escalation" },
           { "field": "base_branch", "header": "Base branch" },
           { "field": "pr_key", "header": "PR", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
           { "field": "converge", "header": "Converge" },
           { "field": "auto_merge", "header": "Auto-merge" },
           { "field": "outcome", "header": "Outcome" },
           { "field": "updated_at", "header": "Updated" }
-        ]
+        ],
+        "rowActions": [
+          {
+            "label": "Abandon",
+            "confirm": "Abandon this escalated task? The run gives up on it (no PR).",
+            "showWhenField": "escalation_user_task_key",
+            "action": {
+              "path": "/app/api/actions/answer-escalation",
+              "body": { "userTaskKey": "{{row.escalation_user_task_key}}", "resolution": "abandon" }
+            }
+          }
+        ],
+        "detail": {
+          "fields": [
+            { "field": "escalation_question", "label": "Escalation question" },
+            { "field": "outcome", "label": "Outcome" }
+          ],
+          "form": {
+            "showWhenField": "escalation_user_task_key",
+            "title": "Answer escalation",
+            "promptField": "escalation_question",
+            "inputKey": "answer",
+            "inputLabel": "Guidance for the implementation agent",
+            "submitLabel": "Answer & re-dispatch",
+            "action": {
+              "path": "/app/api/actions/answer-escalation",
+              "successLabel": "Answered — the agent will resume",
+              "body": {
+                "userTaskKey": "{{row.escalation_user_task_key}}",
+                "resolution": "answer",
+                "answer": "{{form.answer}}"
+              }
+            }
+          }
+        }
       }
     }
   ]

package/resources/processes/feature.bpmn

@@ -9,6 +9,10 @@
           <nano:extend name="pr" type="string" optional="true" />
           <nano:extend name="summary" type="string" optional="true" />
         </nano:shape>
+        <nano:shape id="RecordFeatureEscalationIn" name="Record feature escalation — input">
+          <nano:extend name="featureKey" type="string" />
+          <nano:extend name="question" type="string" optional="true" />
+        </nano:shape>
         <nano:shape id="ConvergeFeatureIn" name="Converge feature PR — input">
           <nano:extend name="featureKey" type="string" />
           <nano:extend name="prKey" type="string" optional="true" />
@@ -54,13 +58,23 @@
       <bpmn:outgoing>w_escalate</bpmn:outgoing>
       <bpmn:outgoing>w_done</bpmn:outgoing>
     </bpmn:exclusiveGateway>
+    <bpmn:serviceTask id="record-feature-escalation" name="Record escalation">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.record-feature-escalation" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordFeatureEscalationIn" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+      <bpmn:incoming>w_escalate</bpmn:incoming>
+      <bpmn:outgoing>w_toEscalationTask</bpmn:outgoing>
+    </bpmn:serviceTask>
     <bpmn:userTask id="feature-escalation" name="Task escalation (human)">
       <bpmn:extensionElements>
         <zeebe:formDefinition formId="feature-escalation" />
         <zeebe:userTask />
-        <zeebe:assignmentDefinition candidateGroups="operators" assignee="=escalationAssignee" />
+        <zeebe:assignmentDefinition candidateGroups="operators" assignee="=if (is defined(escalationAssignee) and escalationAssignee != null and trim(string(escalationAssignee)) != &#34;&#34;) then escalationAssignee else null" />
       </bpmn:extensionElements>
-      <bpmn:incoming>w_escalate</bpmn:incoming>
+      <bpmn:incoming>w_toEscalationTask</bpmn:incoming>
       <bpmn:outgoing>w_toAnswerGw</bpmn:outgoing>
     </bpmn:userTask>
     <bpmn:boundaryEvent id="be_feature_sla" name="SLA elapsed" attachedToRef="feature-escalation">
@@ -134,9 +148,10 @@
     <bpmn:sequenceFlow id="f_toEnsureBase" sourceRef="Start" targetRef="ensure-base-branch" />
     <bpmn:sequenceFlow id="f_toImplement" sourceRef="ensure-base-branch" targetRef="implement-task" />
     <bpmn:sequenceFlow id="w_toGw" sourceRef="implement-task" targetRef="w_gw" />
-    <bpmn:sequenceFlow id="w_escalate" name="escalated" sourceRef="w_gw" targetRef="feature-escalation">
+    <bpmn:sequenceFlow id="w_escalate" name="escalated" sourceRef="w_gw" targetRef="record-feature-escalation">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "escalated" and question != null and trim(question) != ""</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="w_toEscalationTask" sourceRef="record-feature-escalation" targetRef="feature-escalation" />
     <bpmn:sequenceFlow id="w_done" name="done" sourceRef="w_gw" targetRef="record-feature" />
     <bpmn:sequenceFlow id="w_toAnswerGw" sourceRef="feature-escalation" targetRef="w_gw_answer" />
     <bpmn:sequenceFlow id="w_answerLoop" name="answer" sourceRef="w_gw_answer" targetRef="implement-task">
@@ -177,49 +192,52 @@
           <dc:Bounds x="604" y="76" width="74" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
-      <bpmndi:BPMNShape id="BPMNShape_feature-escalation" bpmnElement="feature-escalation">
+      <bpmndi:BPMNShape id="BPMNShape_record-feature-escalation" bpmnElement="record-feature-escalation">
         <dc:Bounds x="766" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_feature-escalation" bpmnElement="feature-escalation">
+        <dc:Bounds x="966" y="240" width="100" height="80" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_w_gw_answer" bpmnElement="w_gw_answer" isMarkerVisible="true">
-        <dc:Bounds x="966" y="255" width="50" height="50" />
+        <dc:Bounds x="1166" y="255" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="963" y="236" width="56" height="14" />
+          <dc:Bounds x="1163" y="236" width="56" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-feature" bpmnElement="record-feature">
-        <dc:Bounds x="1116" y="80" width="100" height="80" />
+        <dc:Bounds x="1316" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-blocked" bpmnElement="gw-blocked" isMarkerVisible="true">
-        <dc:Bounds x="1316" y="95" width="50" height="50" />
+        <dc:Bounds x="1516" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1311" y="76" width="60" height="14" />
+          <dc:Bounds x="1511" y="76" width="60" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_feature-blocked" bpmnElement="feature-blocked">
-        <dc:Bounds x="1466" y="400" width="100" height="80" />
+        <dc:Bounds x="1666" y="400" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-blocked-ack" bpmnElement="record-blocked-ack">
-        <dc:Bounds x="1666" y="400" width="100" height="80" />
+        <dc:Bounds x="1866" y="400" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-converge" bpmnElement="gw-converge" isMarkerVisible="true">
-        <dc:Bounds x="1491" y="95" width="50" height="50" />
+        <dc:Bounds x="1691" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1483" y="76" width="67" height="14" />
+          <dc:Bounds x="1683" y="76" width="67" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_converge" bpmnElement="converge">
-        <dc:Bounds x="1666" y="240" width="100" height="80" />
+        <dc:Bounds x="1866" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_End" bpmnElement="End">
-        <dc:Bounds x="1866" y="102" width="36" height="36" />
+        <dc:Bounds x="2066" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1867" y="83" width="34" height="14" />
+          <dc:Bounds x="2067" y="83" width="34" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_be_feature_sla" bpmnElement="be_feature_sla">
-        <dc:Bounds x="798" y="302" width="36" height="36" />
+        <dc:Bounds x="998" y="302" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="774" y="383" width="84" height="14" />
+          <dc:Bounds x="974" y="383" width="84" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toEnsureBase" bpmnElement="f_toEnsureBase">
@@ -236,35 +254,35 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_w_done" bpmnElement="w_done">
         <di:waypoint x="666" y="120" />
-        <di:waypoint x="1116" y="120" />
+        <di:waypoint x="1316" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="875" y="98" width="32" height="14" />
+          <dc:Bounds x="975" y="98" width="32" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toBlockedGw" bpmnElement="f_toBlockedGw">
-        <di:waypoint x="1216" y="120" />
-        <di:waypoint x="1316" y="120" />
+        <di:waypoint x="1416" y="120" />
+        <di:waypoint x="1516" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_notBlocked" bpmnElement="f_notBlocked">
-        <di:waypoint x="1366" y="120" />
-        <di:waypoint x="1491" y="120" />
+        <di:waypoint x="1566" y="120" />
+        <di:waypoint x="1691" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1390" y="98" width="78" height="14" />
+          <dc:Bounds x="1590" y="98" width="78" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_noConverge" bpmnElement="f_noConverge">
-        <di:waypoint x="1541" y="120" />
-        <di:waypoint x="1866" y="120" />
+        <di:waypoint x="1741" y="120" />
+        <di:waypoint x="2066" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1668" y="98" width="71" height="14" />
+          <dc:Bounds x="1868" y="98" width="71" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_w_abandon" bpmnElement="w_abandon">
-        <di:waypoint x="1016" y="280" />
-        <di:waypoint x="1166" y="280" />
-        <di:waypoint x="1166" y="160" />
+        <di:waypoint x="1216" y="280" />
+        <di:waypoint x="1366" y="280" />
+        <di:waypoint x="1366" y="160" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1065" y="258" width="53" height="14" />
+          <dc:Bounds x="1265" y="258" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_w_escalate" bpmnElement="w_escalate">
@@ -276,55 +294,59 @@
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_blocked" bpmnElement="f_blocked">
-        <di:waypoint x="1341" y="145" />
-        <di:waypoint x="1341" y="440" />
-        <di:waypoint x="1466" y="440" />
+        <di:waypoint x="1541" y="145" />
+        <di:waypoint x="1541" y="440" />
+        <di:waypoint x="1666" y="440" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1346" y="286" width="53" height="14" />
+          <dc:Bounds x="1546" y="286" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_converge" bpmnElement="f_converge">
-        <di:waypoint x="1516" y="145" />
-        <di:waypoint x="1516" y="280" />
-        <di:waypoint x="1666" y="280" />
+        <di:waypoint x="1716" y="145" />
+        <di:waypoint x="1716" y="280" />
+        <di:waypoint x="1866" y="280" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1521" y="206" width="60" height="14" />
+          <dc:Bounds x="1721" y="206" width="60" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_w_toAnswerGw" bpmnElement="w_toAnswerGw">
+      <bpmndi:BPMNEdge id="BPMNEdge_w_toEscalationTask" bpmnElement="w_toEscalationTask">
         <di:waypoint x="866" y="280" />
         <di:waypoint x="966" y="280" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_w_toAnswerGw" bpmnElement="w_toAnswerGw">
+        <di:waypoint x="1066" y="280" />
+        <di:waypoint x="1166" y="280" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toBlockedAck" bpmnElement="f_toBlockedAck">
-        <di:waypoint x="1566" y="440" />
-        <di:waypoint x="1666" y="440" />
+        <di:waypoint x="1766" y="440" />
+        <di:waypoint x="1866" y="440" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_blockedEnd" bpmnElement="f_blockedEnd">
-        <di:waypoint x="1766" y="440" />
-        <di:waypoint x="1884" y="440" />
-        <di:waypoint x="1884" y="138" />
+        <di:waypoint x="1966" y="440" />
+        <di:waypoint x="2084" y="440" />
+        <di:waypoint x="2084" y="138" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toEndConverged" bpmnElement="f_toEndConverged">
-        <di:waypoint x="1766" y="280" />
-        <di:waypoint x="1884" y="280" />
-        <di:waypoint x="1884" y="138" />
+        <di:waypoint x="1966" y="280" />
+        <di:waypoint x="2084" y="280" />
+        <di:waypoint x="2084" y="138" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_w_sla" bpmnElement="w_sla">
-        <di:waypoint x="816" y="338" />
-        <di:waypoint x="816" y="358" />
-        <di:waypoint x="1166" y="358" />
-        <di:waypoint x="1166" y="160" />
+        <di:waypoint x="1016" y="338" />
+        <di:waypoint x="1016" y="358" />
+        <di:waypoint x="1366" y="358" />
+        <di:waypoint x="1366" y="160" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1007" y="325" width="88" height="28" />
+          <dc:Bounds x="1207" y="325" width="88" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_w_answerLoop" bpmnElement="w_answerLoop">
-        <di:waypoint x="991" y="305" />
-        <di:waypoint x="991" y="360" />
+        <di:waypoint x="1191" y="305" />
+        <di:waypoint x="1191" y="360" />
         <di:waypoint x="466" y="360" />
         <di:waypoint x="466" y="160" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="704" y="338" width="49" height="14" />
+          <dc:Bounds x="804" y="338" width="49" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
     </bpmndi:BPMNPlane>

package/scripts/pages-contract.test.ts

@@ -267,7 +267,7 @@ test("issue #205: overview is the landing page and first nav item", async () =>
       "merging",
     ],
     plans: ["planning", "dispatched"],
-    feature_runs: ["running", "awaiting_operator"],
+    feature_runs: ["running", "escalated", "awaiting_operator"],
   };
   const grids = (overview.nodes ?? []).filter((n: Json) => n.type === "dataGrid");
   for (const [table, statuses] of Object.entries(expected)) {

package/workers/record-feature/worker.ts

@@ -54,6 +54,12 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     status: rowStatus,
     pr_key: prKey,
     outcome: summary ?? null,
+    // The run has left the `feature-escalation` wait (answered → abandon, SLA auto-abandon, or the
+    // agent finished without escalating), so clear the denormalised escalation pointer the pages gate
+    // on. pollFeatureEscalations only sweeps `running`/`escalated` runs, so a terminal-ward transition
+    // through here must clear it itself or the stale question would linger on the row.
+    escalation_question: null,
+    escalation_user_task_key: null,
     updated_at: ts,
   });
   app.log.info("record-feature", { featureKey, featureStatus, rowStatus, prKey });

package/workers/record-feature-escalation/worker.test.ts

@@ -0,0 +1,74 @@
+// Unit coverage for pr.record-feature-escalation — a feature run parked on the native
+// `feature-escalation` user task (issue #210). Runs on the `escalated` arm, before the user task
+// exists, and must flip the row to the non-terminal `escalated` status and persist the agent's
+// `question` so the nwf UI can surface it (the poller can't read task-local vars, so this is the
+// question's source of truth). It clears the completable-task pointer to NULL (the task does not
+// exist yet, so any non-null value is stale); the poller fills the real key once it is observable.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory app double, mirrors record-blocked-ack.worker.test
+function fakeApp(rows: Record<string, unknown>[]): any {
+  const stores: Record<string, Record<string, unknown>[]> = { feature_runs: rows };
+  return {
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  };
+}
+
+test("record-feature-escalation: flips the run to escalated and persists the question", async () => {
+  const rows = [{ feature_key: "owner/repo#7", status: "running", escalation_question: null, escalation_user_task_key: null }];
+  const app = fakeApp(rows);
+  const out = await handler(
+    { variables: { featureKey: "owner/repo#7", question: "Which API should I use?" } } as never,
+    app,
+  );
+  assertEquals(out, {});
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, "Which API should I use?");
+  // The user task does not exist yet — the pointer is cleared to NULL here (poller fills the real key).
+  assertEquals(rows[0].escalation_user_task_key, null);
+});
+
+test("record-feature-escalation: clears a stale completable-task pointer at escalation entry", async () => {
+  // The task does not exist yet here, so a non-null key can only be stale (a prior escalation's key
+  // left behind, a manual DB repair, etc). Leaving it would bind the pages' answer/abandon affordance
+  // to the wrong task until the poller overwrites it; clear it so the row reads "key unknown here".
+  const rows = [{ feature_key: "owner/repo#9", status: "running", escalation_question: null, escalation_user_task_key: "stale-ut" }];
+  const app = fakeApp(rows);
+  await handler({ variables: { featureKey: "owner/repo#9", question: "Q?" } } as never, app);
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, "Q?");
+  assertEquals(rows[0].escalation_user_task_key, null);
+});
+
+test("record-feature-escalation: a blank/absent question is persisted as NULL (badge/affordance stay off)", async () => {
+  const rows = [{ feature_key: "owner/repo#8", status: "running", escalation_question: null }];
+  const app = fakeApp(rows);
+  await handler({ variables: { featureKey: "owner/repo#8", question: "   " } } as never, app);
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, null);
+});