@nanobpm/nano-workforce 0.67.0 → 0.68.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.68.0](https://github.com/nanobpm/nano-workforce/compare/v0.67.0...v0.68.0) (2026-08-14)
+
+
+### Features
+
+* **feature:** UI completion affordance for blocked feature runs ([#220](https://github.com/nanobpm/nano-workforce/issues/220)) ([#221](https://github.com/nanobpm/nano-workforce/issues/221)) ([5b68ad4](https://github.com/nanobpm/nano-workforce/commit/5b68ad4871e21d59224d69cde0b95f02247884ae)), closes [#210](https://github.com/nanobpm/nano-workforce/issues/210)
+
 # [0.67.0](https://github.com/nanobpm/nano-workforce/compare/v0.66.0...v0.67.0) (2026-08-14)
 
 

package/app/agentCompletion.ts

@@ -221,6 +221,44 @@ export async function completeEscalationAsHuman(
   return { ok: true, completionId, userTaskKey, elementId: resolved.elementId };
 }
 
+/** The `feature-blocked` operator user-task element id (feature.bpmn). Unlike an escalation this is not
+ *  an agent-answerable task — it is a blocked-run acknowledgement only a human operator retires — so it
+ *  lives outside `ESCALATION_TASK_ELEMENTS` (the agent completer must never touch it) and has its own
+ *  human-only completer below. */
+export const FEATURE_BLOCKED_TASK_ELEMENT = "feature-blocked";
+
+/** Complete the `feature-blocked` operator user task AS A HUMAN (issue #220). The blocked twin of
+ *  `completeEscalationAsHuman`: it resolves the parked task by key, refuses anything that is not the
+ *  `feature-blocked` task, and routes the operator's typed form variables (an optional `note`) through
+ *  the SAME canonical `completeUserTaskAttributed` — so the nwf "Acknowledge blocked" affordance resumes
+ *  the process (→ `pr.record-blocked-ack`, which settles the row to terminal `blocked`) through the one
+ *  completion a human drives from the task inbox, recording WHO acknowledged in the `task_completions`
+ *  ledger. A human completion is the authority (not reversible). A key with no matching open
+ *  `feature-blocked` task is a 404-style no-op. */
+export async function completeBlockedAsHuman(
+  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 open = await engine.searchUserTasks();
+  const match = open.find((t) => t.userTaskKey === userTaskKey);
+  if (!match) return { ok: false, reason: "no open blocked task" };
+  if (match.elementId !== FEATURE_BLOCKED_TASK_ELEMENT) return { ok: false, reason: "not a blocked task" };
+
+  const { completionId } = await completeUserTaskAttributed(
+    data,
+    engine,
+    { userTaskKey, elementId: match.elementId, variables: input.variables },
+    { kind: "human", id: operatorId },
+  );
+  return { ok: true, completionId, userTaskKey, elementId: match.elementId };
+}
+
 export interface RevertResult {
   ok: boolean;
   reason?: string;

package/app/feature.ts

@@ -56,6 +56,14 @@ export interface FeatureRun {
    * (`completeUserTaskAttributed`) and the pages gate the answer controls on (`showWhenField`). Set by
    * `pollFeatureEscalations` while parked; NULL otherwise. */
   escalation_user_task_key: string | null;
+  /** The completable native `feature-blocked` user-task key the "Acknowledge blocked" affordance posts
+   * to (`completeUserTaskAttributed`) and the pages gate the acknowledge control on (`showWhenField`).
+   * Kept DISTINCT from `escalation_user_task_key` so the two human tasks (an escalation answer vs a
+   * blocked-run acknowledgement) are never conflated. Set by `pollFeatureBlocked` while a run is parked
+   * at `feature-blocked` (status `awaiting_operator`); NULL otherwise — cleared on the exit paths
+   * (`record-blocked-ack` / the acknowledge operation) and, as a self-heal, by `pollFeatureBlocked`
+   * when a previously-observed task is completed out-of-band (see `deriveFeatureBlockedPatch`). */
+  blocked_user_task_key: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -191,6 +199,52 @@ export function deriveFeatureEscalationPatch(
   return Object.keys(patch).length > 0 ? patch : null;
 }
 
+/** The `feature-blocked` user-task element id (feature.bpmn) — the native operator wait a run parks on
+ * when the agent reports a `blocked` outcome (it gave up / the escalation was abandoned or timed out).
+ * `pollFeatureBlocked` reconciles it onto the read model. */
+export const FEATURE_BLOCKED_ELEMENT = "feature-blocked";
+
+/** The parked `feature-blocked` user task, as `pollFeatureBlocked` observes it via `searchUserTasks`:
+ * the completable user-task key the pages drive an attributed acknowledgement against. */
+export interface FeatureBlockedParked {
+  userTaskKey: string;
+}
+
+/** Pure source of truth for the blocked read-model reconcile (`pollFeatureBlocked`), the blocked twin
+ * of `deriveFeatureEscalationPatch`: given a run and whether it is currently parked at `feature-blocked`,
+ * return the minimal `feature_runs` patch reconciling the completable-task pointer with the observed park
+ * state (or null when nothing changed, so the poller skips the write). Idempotent and self-healing.
+ *
+ * Unlike the escalation reconcile, the STATUS flip is NOT owned here: `record-feature` already persists
+ * the row as `awaiting_operator` in the same token path before the `feature-blocked` user task is
+ * created, and `record-blocked-ack` settles it to the terminal `blocked` on completion. So this only
+ * reconciles the completable-task POINTER — never the status — so it can never overwrite the terminal
+ * `blocked` the acknowledgement worker has already written.
+ *
+ * - parked → denormalise the completable `userTaskKey` so the pages can drive an attributed acknowledge.
+ * - un-parked → clear the pointer ONLY once it was actually OBSERVED (non-NULL) and the task is now gone.
+ *   Gating on the observed pointer is what makes it safe across the brief self-healing window between
+ *   `record-feature` (which persists `awaiting_operator` but leaves the pointer NULL) and the user task
+ *   appearing: in that window the pointer is NULL, so this never fires, and the next pass fills it in once
+ *   the task is observable. Once observed and then gone (e.g. an out-of-band completion), the stale
+ *   pointer is cleared so the pages stop offering an acknowledge control for a task that no longer exists. */
+export function deriveFeatureBlockedPatch(
+  run: Pick<FeatureRun, "blocked_user_task_key">,
+  parked: FeatureBlockedParked | null,
+): Partial<FeatureRun> | null {
+  const patch: Partial<FeatureRun> = {};
+  if (parked) {
+    if (run.blocked_user_task_key !== parked.userTaskKey) patch.blocked_user_task_key = parked.userTaskKey;
+  } else {
+    // Un-park cleanup — fires ONLY once the poller has actually OBSERVED the task (pointer non-NULL) and
+    // it is now gone. Gating on the pointer being non-NULL is what makes it safe: during the brief
+    // self-healing window between `record-feature` (which persists `awaiting_operator` but leaves the
+    // pointer NULL) and the task appearing, the pointer is NULL, so this never clears prematurely.
+    if (run.blocked_user_task_key !== null) patch.blocked_user_task_key = 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
@@ -233,6 +287,7 @@ export async function startFeature(
       delivery_label: null,
       escalation_question: null,
       escalation_user_task_key: null,
+      blocked_user_task_key: null,
       updated_at: ts,
     });
   } else {
@@ -251,6 +306,7 @@ export async function startFeature(
       delivery_label: null,
       escalation_question: null,
       escalation_user_task_key: null,
+      blocked_user_task_key: null,
       created_at: ts,
       updated_at: ts,
     });

package/app/featureBlocked.test.ts

@@ -0,0 +1,135 @@
+// Read-model derivation test for the FEATURE-run BLOCKED reconcile (issue #220 — a blocked feature run
+// parked at `feature-blocked` had no completion affordance in nwf). When a run reaches a `blocked`
+// outcome `record-feature` holds the row at the non-terminal `awaiting_operator` status and it parks on
+// the native `feature-blocked` operator user task; `feature_runs` (which the pages read) had a status
+// but NO completable-task pointer, so the pages could not drive an acknowledge action. The blocked twin
+// of `deriveFeatureEscalationPatch` — the pure source of truth tested here — reconciles ONLY that
+// completable-task pointer (never the status, which `record-feature`/`record-blocked-ack` own), which
+// `pollFeatureBlocked` projects onto the row.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { deriveFeatureBlockedPatch } from "./feature.ts";
+import { pollFeatureBlocked } from "./service.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory table double, mirrors featureEscalation.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
+ *  pollFeatureBlocked 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("deriveFeatureBlockedPatch: a run parked at feature-blocked records the completable key (status untouched)", () => {
+  const patch = deriveFeatureBlockedPatch({ blocked_user_task_key: null }, { userTaskKey: "ut-9" });
+  assertEquals(patch, { blocked_user_task_key: "ut-9" });
+});
+
+test("deriveFeatureBlockedPatch: an already-recorded parked run yields no patch (idempotent)", () => {
+  const patch = deriveFeatureBlockedPatch({ blocked_user_task_key: "ut-9" }, { userTaskKey: "ut-9" });
+  assertEquals(patch, null);
+});
+
+test("deriveFeatureBlockedPatch: an observed run whose task is gone clears the stale pointer", () => {
+  const patch = deriveFeatureBlockedPatch({ blocked_user_task_key: "ut-9" }, null);
+  assertEquals(patch, { blocked_user_task_key: null });
+});
+
+// The pre-observation self-healing window (record-feature has persisted `awaiting_operator` but the
+// user task is not yet visible, so the pointer is still NULL): a premature "not parked" pass must NOT
+// write anything — the pointer is filled in on the next pass once the task is observable.
+test("deriveFeatureBlockedPatch: the pre-observation self-healing window yields no patch", () => {
+  const patch = deriveFeatureBlockedPatch({ blocked_user_task_key: null }, null);
+  assertEquals(patch, null);
+});
+
+test("pollFeatureBlocked: a parked awaiting_operator run is denormalised with the completable key", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#1", status: "awaiting_operator", process_key: "100", blocked_user_task_key: null },
+  ];
+  const engine = fakeEngine({ "100": [{ userTaskKey: "ut-1", elementId: "feature-blocked" }] });
+
+  await pollFeatureBlocked(data, engine);
+
+  // The poller never flips status — record-feature owns `awaiting_operator`, record-blocked-ack the terminal.
+  assertEquals(stores.feature_runs[0].status, "awaiting_operator");
+  assertEquals(stores.feature_runs[0].blocked_user_task_key, "ut-1");
+});
+
+test("pollFeatureBlocked: an observed run whose task is gone (out-of-band completion) clears the pointer", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#2", status: "awaiting_operator", process_key: "200", blocked_user_task_key: "ut-2" },
+  ];
+  const engine = fakeEngine({ "200": [] });
+
+  await pollFeatureBlocked(data, engine);
+
+  assertEquals(stores.feature_runs[0].blocked_user_task_key, null);
+});
+
+test("pollFeatureBlocked: only touches awaiting_operator runs, and never one without a process_key", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#3", status: "blocked", process_key: "300", blocked_user_task_key: null },
+    { feature_key: "o/r#4", status: "awaiting_operator", process_key: null, blocked_user_task_key: null },
+  ];
+  const engine = fakeEngine({ "300": [{ userTaskKey: "ut-3", elementId: "feature-blocked" }] });
+
+  await pollFeatureBlocked(data, engine);
+
+  // blocked is terminal → not a candidate; awaiting_operator with no process_key → skipped.
+  assertEquals(stores.feature_runs[0].blocked_user_task_key, null);
+  assertEquals(stores.feature_runs[1].blocked_user_task_key, null);
+});
+
+test("pollFeatureBlocked: a parked non-blocked task (feature-escalation) does not record a pointer", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#5", status: "awaiting_operator", process_key: "500", blocked_user_task_key: null },
+  ];
+  const engine = fakeEngine({ "500": [{ userTaskKey: "ut-5", elementId: "feature-escalation" }] });
+
+  await pollFeatureBlocked(data, engine);
+
+  assertEquals(stores.feature_runs[0].blocked_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, deriveFeatureEscalationPatch, FEATURE_ESCALATION_ELEMENT, type FeatureRun, featureRuns } from "./feature.ts";
+import { deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, type FeatureRun, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
   ensureFreshHeadRun,
@@ -1326,6 +1326,40 @@ export async function pollFeatureEscalations(data: DataLayer, engine: EngineClie
   }
 }
 
+/** Reconcile each BLOCKED FEATURE run against its native `feature-blocked` user task (issue #220 —
+ * a blocked run parked at `feature-blocked` had no completion affordance in nwf). When a feature run
+ * reaches a `blocked` outcome `record-feature` holds the row at the NON-terminal `awaiting_operator`
+ * status and it parks on the `feature-blocked` operator user task (an engine wait); no worker runs, so
+ * the schema-driven pages — which read `feature_runs` — had a status to show but NO pointer to drive a
+ * completion action, so the run sat parked forever unless completed out-of-band. This is the blocked
+ * twin of `pollFeatureEscalations`: for each run parked at (or resuming from) the blocked wait, read its
+ * open user tasks and project the parked task's completable `userTaskKey` onto the row via the pure
+ * `deriveFeatureBlockedPatch`, so the pages can drive an "Acknowledge blocked" action, and clear the
+ * pointer once it un-parks. It never touches `status` — `record-feature` owns the `awaiting_operator`
+ * flip and `record-blocked-ack` owns the terminal `blocked`, so the poller can never clobber either.
+ *
+ * Candidates are only the runs that could be parked here — `awaiting_operator` (parked at, or just
+ * un-parked from, the blocked wait) — queried via the `feature_runs(status)` index, so the pass stays
+ * O(in-flight), not O(total runs). The terminal-ward transition THROUGH `record-blocked-ack` (and the
+ * acknowledge operation) clears the pointer, so a run that has already settled to `blocked` never needs
+ * sweeping here. Best-effort + idempotent — per-run failures are isolated. */
+export async function pollFeatureBlocked(data: DataLayer, engine: EngineClient) {
+  for (const run of await featureRuns(data).find({ status: "awaiting_operator" })) {
+    if (!run.process_key) continue;
+    try {
+      const tasks = await engine.searchUserTasks({ processInstanceKey: run.process_key });
+      const task = tasks.find((t) => t.elementId === FEATURE_BLOCKED_ELEMENT);
+      const parked = task ? { userTaskKey: task.userTaskKey } : null;
+      const patch = deriveFeatureBlockedPatch(run, parked);
+      if (patch) {
+        await featureRuns(data).update(run.feature_key, { ...patch, updated_at: now() });
+      }
+    } catch (err) {
+      console.error(`[poller] feature blocked ${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`. */
@@ -1341,6 +1375,7 @@ export async function pollOnce(
   await pollDelivery(data);
   await pollFeatureDelivery(data);
   await pollFeatureEscalations(data, engine);
+  await pollFeatureBlocked(data, engine);
   if (engineRest) {
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);

package/db/migrations/032_feature_blocked_surface.sql

@@ -0,0 +1,26 @@
+-- Surface a blocked feature-run's completion affordance in the nwf UI (issue #220).
+--
+-- The escalation path (`feature-escalation`) got the full UI treatment in issue
+-- #210; the BLOCKED path (`feature-blocked`) did not. When a single-issue feature
+-- run reaches a `blocked` outcome it parks on the native `feature-blocked` operator
+-- user task (`candidateGroups=operators`) and `record-feature` holds the row at the
+-- NON-terminal `awaiting_operator` status. That wait was actionable only out-of-band
+-- (a direct `/v2/user-tasks/{key}/completion` call): the schema-driven pages read
+-- `feature_runs`, but nothing denormalised the completable `feature-blocked`
+-- userTaskKey onto the row, so the pages had no pointer to drive a completion action
+-- and the run sat parked forever with no affordance.
+--
+-- This column is the blocked twin of `escalation_user_task_key` (migration 031):
+-- the completable native `feature-blocked` user-task key the "Acknowledge blocked"
+-- affordance posts to (`completeUserTaskAttributed`) and the pages gate the control
+-- on (`showWhenField`, JS-truthy, so NULL correctly hides it). It is kept DISTINCT
+-- from `escalation_user_task_key` so the two human tasks are never conflated. The
+-- poller (`pollFeatureBlocked` in app/service.ts) fills it in once the user task is
+-- observable and clears it when the run un-parks; `record-blocked-ack` / the
+-- acknowledge operation clear it on the terminal-ward exit. It is NULL whenever the
+-- run is not parked at `feature-blocked`.
+--
+-- Forward-only, additive (expand): the column is nullable with no default. Numbered
+-- after the current highest prefix (031); the runner wraps each file in its own
+-- transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE feature_runs ADD COLUMN blocked_user_task_key TEXT;

package/e2e/feature-run.e2e.ts

@@ -22,7 +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";
+import { pollFeatureBlocked, pollFeatureEscalations } from "../app/service.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -59,6 +59,7 @@ interface FeatureRow {
   delivery_label: string | null;
   escalation_question: string | null;
   escalation_user_task_key: string | null;
+  blocked_user_task_key: string | null;
 }
 interface PrRow {
   pr_key: string;
@@ -189,8 +190,20 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         const prs = await app.db.table<PrRow>("pull_requests", "pr_key").find({});
         assert.equal(prs.length, 0, "a blocked run never enrolled a PR into the convergence loop");
 
-        // Acknowledging the blocked run records the note, settles it terminal `blocked`, and ends.
-        await app.engine.completeUserTask(task!.userTaskKey, { note: "reassigned to a human" });
+        // The poller fills in the completable user-task key (which no service task can know — the task
+        // doesn't exist yet when record-feature runs) so the pages can drive an attributed acknowledge.
+        await pollFeatureBlocked(app.db, app.engine);
+        const denorm = await featureRow(app, featureKey);
+        assert.ok(denorm.blocked_user_task_key, "the poller denormalised the completable blocked user-task key");
+        assert.equal(denorm.status, "awaiting_operator", "the run stays awaiting_operator while parked");
+
+        // Acknowledge through the app's OWN operation (the nwf UI's affordance) — the attributed
+        // completer resumes the SAME record-blocked-ack path a human would from the task inbox, with NO
+        // out-of-band /v2/user-tasks/{key}/completion call.
+        const acked = await app.api?.call("acknowledgeBlocked", {
+          body: { userTaskKey: denorm.blocked_user_task_key, note: "reassigned to a human" },
+        });
+        assert.equal(acked?.status, 200, "the operator acknowledgement completed the blocked task");
         await app.settle();
         const flows2 = takenFlows(app);
         assert.ok(flows2.includes("feature-blocked->record-blocked-ack"), "ack routes through record-blocked-ack");
@@ -198,6 +211,11 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         const settled = await featureRow(app, featureKey);
         assert.equal(settled.status, "blocked", "the acknowledged run settles at terminal blocked");
         assert.equal(settled.delivery_label, "operator: reassigned to a human", "the operator note is recorded");
+        assert.equal(settled.blocked_user_task_key, null, "the completable-task pointer was cleared on ack");
+
+        // A further poll pass is an idempotent no-op — a terminal run is not a candidate.
+        await pollFeatureBlocked(app.db, app.engine);
+        assert.equal((await featureRow(app, featureKey)).status, "blocked");
       },
     );
   });

package/openapi.yaml

@@ -977,6 +977,55 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /actions/acknowledge-blocked:
+    post:
+      operationId: acknowledgeBlocked
+      summary: "Acknowledge a blocked native feature run (issue #220). Completes the parked
+        `feature-blocked` operator user task with the operator's optional disposition note, driving the
+        canonical attributed completer (completeUserTaskAttributed) — the same resume path the task inbox
+        uses, recording who acknowledged. Completing it fires pr.record-blocked-ack, settling the run to
+        the terminal `blocked` status with the note, and the poller reconciles the completable-task
+        pointer off the row. This is the nwf UI's completion affordance for a feature run parked as
+        blocked (the blocked twin of answer-escalation)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - userTaskKey
+              properties:
+                userTaskKey:
+                  type: string
+                  minLength: 1
+                  description: The parked `feature-blocked` user-task key (feature_runs.blocked_user_task_key).
+                note:
+                  type: string
+                  description: Optional operator disposition note, recorded on the run (delivery_label). Blank ⇒ "acknowledged".
+                operator:
+                  type: string
+                  description: Optional operator handle recorded in the attribution ledger; defaults to "operator".
+      responses:
+        "200":
+          description: The blocked 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 a blocked task.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No open blocked user task matches the userTaskKey.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /hooks/agent-complete:
     post:
       operationId: agentCompleteEscalation

package/operations/acknowledgeBlocked.test.ts

@@ -0,0 +1,111 @@
+// Tests for the POST /app/api/actions/acknowledge-blocked operation `acknowledgeBlocked` (issue #220).
+// The nwf UI's completion affordance for a blocked feature run parked at `feature-blocked`: it routes
+// through the canonical attributed completer (completeBlockedAsHuman → completeUserTaskAttributed),
+// resuming the process (→ pr.record-blocked-ack) exactly as the task inbox would, and immediately
+// clears the denormalised completable-task pointer so the affordance stops rendering. Mirrors the
+// escalation twin (operations/answerFeatureEscalation.ts).
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./acknowledgeBlocked.ts";
+
+function memApp(openTasks: { userTaskKey: string; elementId?: string }[]): {
+  app: AppApi;
+  stores: Record<string, any[]>;
+  completed: { userTaskKey: string; variables: Record<string, unknown> }[];
+} {
+  const stores: Record<string, any[]> = {};
+  const completed: { userTaskKey: string; variables: Record<string, unknown> }[] = [];
+  function tbl(name: string, pk: string) {
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      async insert(row: any) {
+        rows.push({ ...row });
+        return rows.length;
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+      async delete(id: any) {
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const engine = {
+    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(),
+  } as any as AppApi;
+  return { app, stores, completed };
+}
+
+async function call(app: AppApi, body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("acknowledge-blocked: completes the feature-blocked task, records the note, clears the pointer", async () => {
+  const { app, stores, completed } = memApp([{ userTaskKey: "ut-1", elementId: "feature-blocked" }]);
+  stores.feature_runs = [{ feature_key: "o/r#1", status: "awaiting_operator", blocked_user_task_key: "ut-1" }];
+
+  const res = await call(app, { userTaskKey: "ut-1", note: "reassigned to a human", operator: "alice" });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  // The task is completed with the typed `note` variable the record-blocked-ack ioMapping reads.
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].userTaskKey, "ut-1");
+  assertEquals(completed[0].variables, { note: "reassigned to a human" });
+  // The attribution ledger records WHO acknowledged (a human — the authority, not reversible).
+  assertEquals(stores.task_completions.length, 1);
+  assertEquals(stores.task_completions[0].actor_kind, "human");
+  assertEquals(stores.task_completions[0].actor_id, "alice");
+  assertEquals(stores.task_completions[0].reversible, 0);
+  // The operation clears its own action's pointer immediately (status left to record-blocked-ack).
+  assertEquals(stores.feature_runs[0].blocked_user_task_key, null);
+});
+
+test("acknowledge-blocked: a blank note omits the variable so the ioMapping fallback fires", async () => {
+  const { app, stores, completed } = memApp([{ userTaskKey: "ut-2", elementId: "feature-blocked" }]);
+  stores.feature_runs = [{ feature_key: "o/r#2", status: "awaiting_operator", blocked_user_task_key: "ut-2" }];
+
+  const res = await call(app, { userTaskKey: "ut-2", note: "   " });
+
+  assertEquals(res.status, 200);
+  assertEquals(completed[0].variables, {});
+});
+
+test("acknowledge-blocked: a missing userTaskKey → 400", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { note: "x" });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+});
+
+test("acknowledge-blocked: no matching open task → 404", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { userTaskKey: "ut-gone" });
+  assertEquals(res.status, 404);
+  assertEquals(res.body.ok, false);
+});
+
+test("acknowledge-blocked: refuses a non-blocked task (an escalation) → 400", async () => {
+  const { app } = memApp([{ userTaskKey: "ut-esc", elementId: "feature-escalation" }]);
+  const res = await call(app, { userTaskKey: "ut-esc" });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+});

package/operations/acknowledgeBlocked.ts

@@ -0,0 +1,62 @@
+// POST /app/api/actions/acknowledge-blocked → operationId `acknowledgeBlocked` (issue #220).
+// The nwf UI's completion affordance for a BLOCKED single-issue feature run: an operator acknowledges
+// the parked `feature-blocked` user task (with an optional disposition note) directly from the Feature /
+// Overview pages, instead of the run sitting parked forever with no control (the escalation path got
+// this in issue #210; the blocked path did not).
+//
+// It routes through the ONE canonical attributed completer (`completeBlockedAsHuman` →
+// `completeUserTaskAttributed`), so the completion uses the exact same typed `.form` variable (`note`)
+// and engine resume path a human drives from the task inbox — no parallel completion — while recording
+// WHO acknowledged in the `task_completions` ledger. Completing the task fires `pr.record-blocked-ack`,
+// which settles the row to the terminal `blocked` status with the operator's note. The poller then
+// reconciles the completable-task pointer off the row (pollFeatureBlocked) once the task is gone.
+//
+// The runtime validates the body against openapi.yaml (`userTaskKey` required); this delegate narrows
+// the validated shape and builds the typed completion variables the `feature-blocked` form + the
+// `record-blocked-ack` ioMapping expect.
+
+import { completeBlockedAsHuman } 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("acknowledgeBlocked", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("acknowledge-blocked rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "userTaskKey is required" } };
+  }
+
+  const userTaskKey = str(body.userTaskKey);
+  if (!userTaskKey) return { status: 400, body: { ok: false, error: "userTaskKey is required" } };
+
+  // The `feature-blocked` form completes with an optional `note`; the `record-blocked-ack` ioMapping
+  // reads it (`if is defined(note) then note else null`) into `delivery_label`. An absent/blank note is
+  // recorded as an "acknowledged" label rather than an empty string — omit the variable entirely so the
+  // ioMapping's `is defined` fallback fires.
+  const note = str(body.note);
+  const variables: Record<string, unknown> = note ? { note } : {};
+
+  // 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 acknowledgement.
+  const operatorId = str(body.operator) || "operator";
+
+  const r = await completeBlockedAsHuman(app.data, app.engine, { userTaskKey, operatorId, variables });
+  if (r.ok) {
+    // Reconcile this operation's OWN action immediately: clear the denormalised blocked pointer so the
+    // pages stop offering an acknowledge affordance for a task that is now completed. Leave `status` to
+    // `record-blocked-ack` (which settles it to terminal `blocked`), so we never overwrite the status the
+    // resumed run has advanced to.
+    for (const run of await featureRuns(app.data).find({ blocked_user_task_key: userTaskKey })) {
+      await featureRuns(app.data).update(run.feature_key, {
+        blocked_user_task_key: null,
+        updated_at: new Date().toISOString(),
+      });
+    }
+    app.log.info("operator acknowledged blocked feature run", { userTaskKey, elementId: r.elementId });
+    return { status: 200, body: { ok: true, completionId: r.completionId, elementId: r.elementId } };
+  }
+  const status = r.reason === "no open blocked task" ? 404 : 400;
+  app.log.warn("acknowledge-blocked: 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.67.0",
+  "version": "0.68.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

@@ -88,6 +88,15 @@
               "path": "/app/api/actions/answer-escalation",
               "body": { "userTaskKey": "{{row.escalation_user_task_key}}", "resolution": "abandon" }
             }
+          },
+          {
+            "label": "Acknowledge blocked",
+            "confirm": "Acknowledge this blocked run? It settles to terminal blocked (the agent could not open a PR).",
+            "showWhenField": "blocked_user_task_key",
+            "action": {
+              "path": "/app/api/actions/acknowledge-blocked",
+              "body": { "userTaskKey": "{{row.blocked_user_task_key}}" }
+            }
           }
         ],
         "detail": {

package/pages/overview.page.json

@@ -141,6 +141,15 @@
               "path": "/app/api/actions/answer-escalation",
               "body": { "userTaskKey": "{{row.escalation_user_task_key}}", "resolution": "abandon" }
             }
+          },
+          {
+            "label": "Acknowledge blocked",
+            "confirm": "Acknowledge this blocked run? It settles to terminal blocked (the agent could not open a PR).",
+            "showWhenField": "blocked_user_task_key",
+            "action": {
+              "path": "/app/api/actions/acknowledge-blocked",
+              "body": { "userTaskKey": "{{row.blocked_user_task_key}}" }
+            }
           }
         ],
         "detail": {

package/workers/record-blocked-ack/worker.test.ts

@@ -32,12 +32,15 @@ function fakeApp(rows: Record<string, unknown>[]) {
 }
 
 test("record-blocked-ack: settles the parked run at terminal blocked and records the operator note", async () => {
-  const rows = [{ feature_key: "owner/repo#7", status: "awaiting_operator", delivery_label: null }];
+  const rows = [{ feature_key: "owner/repo#7", status: "awaiting_operator", delivery_label: null, blocked_user_task_key: "ut-7" }];
   const app = fakeApp(rows);
   const out = await handler({ variables: { featureKey: "owner/repo#7", note: "reassigned to a human" } } as any, app);
   assertEquals(out, {});
   assertEquals(rows[0].status, "blocked");
   assertEquals(rows[0].delivery_label, "operator: reassigned to a human");
+  // The completable-task pointer is cleared on the terminal-ward transition so the pages stop offering
+  // the acknowledge affordance for a now-completed task (pollFeatureBlocked no longer sweeps this row).
+  assertEquals(rows[0].blocked_user_task_key, null);
 });
 
 test("record-blocked-ack: a blank note falls back to an 'acknowledged' label", async () => {

package/workers/record-blocked-ack/worker.ts

@@ -26,6 +26,11 @@ const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
   await featureRuns(app.data).update(featureKey, {
     status: "blocked",
     delivery_label: note ? `operator: ${note}` : "acknowledged",
+    // The run has left the `feature-blocked` wait, so clear the denormalised completable-task pointer
+    // the pages gate the "Acknowledge blocked" affordance on. pollFeatureBlocked only sweeps
+    // `awaiting_operator` runs, so this terminal-ward transition must clear it itself or a stale pointer
+    // would linger on the now-terminal row.
+    blocked_user_task_key: null,
     updated_at: ts,
   });
   app.log.info("record-blocked-ack", { featureKey, note: note ?? null });