@nanobpm/nano-workforce 0.67.0 → 0.69.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.69.0](https://github.com/nanobpm/nano-workforce/compare/v0.68.0...v0.69.0) (2026-08-15)
+
+
+### Features
+
+* **agentic:** enable nwf for a remote fleet — loopback-guard the LOCAL token + document network posture ([#224](https://github.com/nanobpm/nano-workforce/issues/224)) ([#228](https://github.com/nanobpm/nano-workforce/issues/228)) ([73f6170](https://github.com/nanobpm/nano-workforce/commit/73f6170ff4c0df0ad6c4eb2a2e6e9b3df5d1e343)), closes [nano-ide#235](https://github.com/nano-ide/issues/235) [nano-ide#235](https://github.com/nano-ide/issues/235)
+
+# [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/README.md

@@ -263,6 +263,70 @@ active epic already targets the same custom base. See
 | `NANO_PR_MAX_CI_FIX_ROUNDS` | `3` | max `senior:fix-ci` attempts to green a `blocked` PR before escalating; `0` disables (escalate immediately), clamped 0–20 |
 | `NANO_PR_REVIEW_WAIT_TIMEOUT` | `PT20M` | ISO-8601 duration the loop waits for a fresh review before escalating a stalled review (timer arm of the `wait-review` gateway) |
 | `NANO_PR_REVIEW_NUDGE_MINUTES` | `5` | cooldown between the poller's automatic reviewer re-request nudges for one waiting PR (clamped 1–1440) |
+| `NANO_PR_PUBLIC_BASE_URL` | `http://localhost:3000` | externally-reachable base URL for the capability hooks (`/app/api/hooks/*`). Must resolve from **wherever the agent runs** — set it to the app's LAN address (or console-proxy URL) for a remote fleet. Falls back to `NANO_PR_BASE_URL`, then `http://localhost:3000`. See [Fleet networking](#fleet-networking-remote-workers) |
+| `NANO_AGENTIC_SECRET` | — | enables **secure mode** for the agentic visibility channel (`/agentic`): requires an ADR 0028 identity token + capability credential from every peer. Required to attach agentic visibility from **off-box** workers; unset = on-by-default **LOCAL mode** (well-known token, loopback peers only). Also accepts `NANO_PR_WEBHOOK_SECRET` |
+
+### Fleet networking (remote workers)
+
+`nano-workforce` can drive a **distributed worker fleet** — `senior:*` agents running on other LAN
+machines. Two app surfaces must be reachable from those off-box workers:
+
+- The **capability hooks** — `/app/api/hooks/abandon` and `/app/api/hooks/blackboard`. Every
+  side-effecting agent is handed an unguessable per-run capability URL in its prompt and `curl`s it
+  before each irreversible action (an unknown token is a `404`). A remote worker can only reach these
+  if (a) the app's HTTP server is bound so off-box hosts can connect, and (b) the base URL baked into
+  that prompt resolves from the worker's host — hence **`NANO_PR_PUBLIC_BASE_URL` must be the app's
+  LAN address, not `localhost`**.
+- The **agentic visibility channel** — `/agentic` (WebSocket). In on-by-default **LOCAL mode** it is
+  gated only by a *well-known, non-secret* localhost token, so it is enforced **loopback-only**: an
+  off-box peer is refused — as is a **reverse-proxied** peer (a connection carrying an
+  `X-Forwarded-For`/`Forwarded`/`X-Real-IP` header is refused even over loopback, so forwarding
+  `/agentic` through the console proxy cannot smuggle the well-known token off-box). To give remote
+  workers visibility, run the channel in **secure mode** by setting `NANO_AGENTIC_SECRET`. (Fleet
+  coordination itself does not depend on this channel — it is visibility only.)
+
+#### Bind the HTTP server
+
+The capability hooks are only reachable off-box if the app's HTTP server binds to a routable
+interface. The declarative, per-app control is an **app-manifest** setting (loopback by default,
+opt-in to all interfaces):
+
+```jsonc
+// nano.app.json
+{ "network": { "bind": "all" } }   // 0.0.0.0 / :: — expose to the LAN for a remote fleet
+```
+
+> **Status:** this manifest key is delivered by the Urban runtime in
+> [`nanobpm/nano-ide#235`](https://github.com/nanobpm/nano-ide/issues/235) (add the field to the app
+> schema + plumb the bind host to the node adapter). Until that lands, the runtime binds to all
+> interfaces by default (Node's `listen(port)` default), so a fleet already reaches the hooks — but
+> once the parallel *loopback-by-default* change ships, set `"network": { "bind": "all" }` here to
+> keep nwf reachable. This repo is ready for that flip; nwf already enforces the LOCAL-token
+> loopback-only guard so binding wide never exposes the well-known agentic token off-box.
+
+#### Choose a path: direct LAN bind vs console proxy
+
+nwf composes with two deployment topologies — pick one and point the fleet at it:
+
+| Path | When | Fleet uses |
+|---|---|---|
+| **Direct LAN bind** | nwf run standalone for a fleet | Bind the server wide (above) and set `NANO_PR_PUBLIC_BASE_URL=http://<app-lan-host>:3000`. Workers `curl` the hooks directly on the app's LAN address. |
+| **Console reverse-proxy** | nwf embedded behind the nano console at `/console/app-view/Workforce` | Leave the app bound to loopback and set `NANO_PR_PUBLIC_BASE_URL` to the console's public origin + the app-view prefix, so `/app/api/hooks/*` resolves through the proxy. Workers reach the hooks via the console. |
+
+Either way the capability URL in each agent's prompt (`${NANO_PR_PUBLIC_BASE_URL}/app/api/hooks/…`)
+must resolve from the worker's host. **Verify** from a fleet host before relying on it:
+
+```sh
+# From a remote LAN worker, against the base URL seeded into agent prompts.
+# A live run returns { "prKey": "...", "status": "...", "abandoned": false }; -f exits non-zero on 404.
+curl -fsS "${NANO_PR_PUBLIC_BASE_URL}/app/api/hooks/abandon?token=<per-run-token>"
+```
+
+If the `curl` cannot reach the host, off-box agents will (correctly, per the abort contract) treat the
+run as abandoned and stop — the exact failure behind
+[`jwulf/c8ctl-plugin-nano#76`](https://github.com/jwulf/c8ctl-plugin-nano/issues/76). Fix it by
+binding wide + setting a routable `NANO_PR_PUBLIC_BASE_URL`, or by fronting nwf with the console proxy.
+
 
 ### Purge
 

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/agentic/channel.test.ts

@@ -5,11 +5,19 @@
 // hub is visible via `inspect()`, families mount/tear-down through the seam, and shutdown is clean.
 import { type AddressInfo, createServer, type Server } from "node:http";
 import { test } from "node:test";
+import { AUTH_UNAUTHORIZED } from "@nanobpm/agentic/channel";
 import { createLogger } from "@nanobpm/urban/runtime";
 import { WebSocket } from "ws";
 import { assert, assertEquals } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
-import { type AgenticChannelHandle, LOCAL_AGENTIC_TOKEN, mountAgenticChannel } from "./channel.ts";
+import {
+  type AgenticChannelHandle,
+  isForwardedConnection,
+  isLoopbackRemote,
+  LOCAL_AGENTIC_TOKEN,
+  loopbackOnly,
+  mountAgenticChannel,
+} from "./channel.ts";
 import { type AgenticContext, AgenticFamilyRegistry } from "./registry.ts";
 
 const SECRET = "test-agentic-secret";
@@ -359,3 +367,79 @@ test("LOCAL mode does NOT warn when the server is bound to loopback", async (t)
   const warned = records.some((r) => r.level === "warn" && r.msg.includes("not bound to loopback"));
   assert(!warned, "a loopback-bound LOCAL channel is the expected safe case and must not warn");
 });
+
+// --- Loopback-only enforcement of the LOCAL well-known token (issue #224 / nano-ide#235) ---
+//
+// The LOCAL token is not a secret, so once the app binds to all interfaces (network.bind: "all") it
+// must never be honoured off-box. `isLoopbackRemote` vets the peer's origin; `loopbackOnly` wraps an
+// authenticator to refuse a non-loopback peer with 4401 while delegating loopback peers to the base.
+
+test("isLoopbackRemote accepts same-host peers and rejects everything else", () => {
+  for (const ok of ["127.0.0.1", "127.0.0.5", "::1", "::ffff:127.0.0.1", "::ffff:127.1.2.3"]) {
+    assert(isLoopbackRemote(ok), `${ok} should be loopback`);
+  }
+  for (const no of [undefined, "", "10.0.0.4", "192.168.1.20", "::ffff:10.0.0.4", "2001:db8::1", "0.0.0.0"]) {
+    assert(!isLoopbackRemote(no), `${String(no)} should NOT be loopback`);
+  }
+});
+
+test("loopbackOnly refuses a non-loopback peer with 4401 and never calls the base authenticator", () => {
+  let baseCalls = 0;
+  const base = () => {
+    baseCalls++;
+    return { ok: true as const, grant: { identity: "peer" } };
+  };
+  const guarded = loopbackOnly(base);
+
+  const remote = guarded({ token: LOCAL_AGENTIC_TOKEN, remote: "10.0.0.4" });
+  assert(!("then" in remote), "authenticator result is synchronous here");
+  assertEquals((remote as { ok: boolean; code?: number }).ok, false);
+  assertEquals((remote as { code?: number }).code, AUTH_UNAUTHORIZED);
+  assertEquals(baseCalls, 0);
+});
+
+test("loopbackOnly delegates a loopback peer to the base authenticator", () => {
+  let baseCalls = 0;
+  const base = () => {
+    baseCalls++;
+    return { ok: true as const, grant: { identity: "peer" } };
+  };
+  const guarded = loopbackOnly(base);
+
+  const local = guarded({ token: LOCAL_AGENTIC_TOKEN, remote: "127.0.0.1" });
+  assertEquals((local as { ok: boolean }).ok, true);
+  assertEquals(baseCalls, 1);
+});
+
+// A reverse proxy that connects to the app over loopback makes an off-box client appear same-host to
+// `req.remote`. `isForwardedConnection` detects the relay from proxy-forwarding headers, so
+// `loopbackOnly` fails closed on a proxied peer even when `req.remote` itself is loopback.
+
+test("isForwardedConnection detects proxy-forwarding headers and ignores absent/empty ones", () => {
+  assert(isForwardedConnection({ "x-forwarded-for": "10.0.0.4" }), "x-forwarded-for marks a relay");
+  assert(isForwardedConnection({ forwarded: "for=10.0.0.4" }), "forwarded marks a relay");
+  assert(isForwardedConnection({ "x-real-ip": "10.0.0.4" }), "x-real-ip marks a relay");
+
+  assert(!isForwardedConnection(undefined), "no headers is a direct connection");
+  assert(!isForwardedConnection({}), "empty headers is a direct connection");
+  assert(!isForwardedConnection({ "x-forwarded-for": "   " }), "whitespace value is treated as absent");
+  assert(!isForwardedConnection({ "content-type": "application/json" }), "unrelated headers are ignored");
+});
+
+test("loopbackOnly refuses a reverse-proxied peer (loopback remote + forwarding header) with 4401", () => {
+  let baseCalls = 0;
+  const base = () => {
+    baseCalls++;
+    return { ok: true as const, grant: { identity: "peer" } };
+  };
+  const guarded = loopbackOnly(base);
+
+  const proxied = guarded({
+    token: LOCAL_AGENTIC_TOKEN,
+    remote: "127.0.0.1",
+    headers: { "x-forwarded-for": "203.0.113.7" },
+  });
+  assertEquals((proxied as { ok: boolean; code?: number }).ok, false);
+  assertEquals((proxied as { code?: number }).code, AUTH_UNAUTHORIZED);
+  assertEquals(baseCalls, 0);
+});

package/app/agentic/channel.ts

@@ -17,6 +17,8 @@ import type { Server } from "node:http";
 import type { AddressInfo } from "node:net";
 import {
   AgenticHub,
+  AUTH_UNAUTHORIZED,
+  type Authenticator,
   sharedSecretAuthenticator,
   WebSocketChannelTransport,
 } from "@nanobpm/agentic/channel";
@@ -53,6 +55,83 @@ function isLoopbackBind(addr: string | AddressInfo | null): boolean {
   return host === "::1" || host === "::ffff:127.0.0.1" || host.startsWith("127.");
 }
 
+/**
+ * True if a peer's remote address (`req.remote`, i.e. `socket.remoteAddress`) is a same-host /
+ * loopback peer. This is the per-connection counterpart to {@link isLoopbackBind}: while that vets
+ * the *server's* bind, this vets the *client's* origin, so LOCAL mode can be honoured off a
+ * wildcard/all-interfaces bind (`network.bind: "all"`, issue #224) yet still refuse the well-known
+ * {@link LOCAL_AGENTIC_TOKEN} to anything but a same-machine peer. Loopback is `127.0.0.0/8`, `::1`,
+ * or the IPv6-mapped IPv4 forms Node reports on a dual-stack listener (`::ffff:127.x`). An
+ * absent/unparseable remote is NOT provably same-host, so it is treated as non-loopback
+ * (fail-closed), matching the `isLoopbackBind(null) === false` posture.
+ */
+export function isLoopbackRemote(remote: string | undefined): boolean {
+  if (!remote) return false;
+  return (
+    remote === "::1" ||
+    remote === "::ffff:127.0.0.1" ||
+    remote.startsWith("127.") ||
+    remote.startsWith("::ffff:127.")
+  );
+}
+
+/**
+ * Proxy-forwarding request headers. Their presence means the connection was relayed through a
+ * reverse proxy, so `req.remote` is the *proxy's* address (typically loopback for an embedded/console
+ * proxy) rather than the true client — a loopback `remote` no longer proves a same-host peer. A
+ * genuine same-machine loopback peer connects directly and never carries one of these.
+ */
+const FORWARDING_HEADERS: readonly string[] = ["x-forwarded-for", "forwarded", "x-real-ip"];
+
+/**
+ * True if the handshake carries a proxy-forwarding header — i.e. the connection reached us through a
+ * reverse proxy, so `req.remote` is the proxy, not the originating client. Used to fail LOCAL mode
+ * closed: a relayed connection can present a loopback `remote` (the proxy) while the real client is
+ * off-box, so the well-known token must never be honoured for it (see {@link loopbackOnly}). Headers
+ * are lower-cased by the transport ({@link HandshakeRequest.headers}); an empty/whitespace value is
+ * treated as absent.
+ */
+export function isForwardedConnection(headers: Readonly<Record<string, string>> | undefined): boolean {
+  if (!headers) return false;
+  return FORWARDING_HEADERS.some((h) => {
+    const value = headers[h];
+    return typeof value === "string" && value.trim() !== "";
+  });
+}
+
+/**
+ * Wrap `base` so a peer is admitted ONLY from a direct, same-host loopback connection. LOCAL mode
+ * gates purely on the well-known {@link LOCAL_AGENTIC_TOKEN}, which is not a secret — so once the app
+ * is exposed on the LAN (`network.bind: "all"`, issue #224) that token must never be honoured
+ * off-box. This enforces the invariant per-connection (any other peer is closed `4401`), independent
+ * of the server's bind, closing the interplay the bind-to-all setting exposes (nano-ide#235).
+ *
+ * Two ways a peer can fail to be a same-host loopback client, both refused:
+ *  - a non-loopback `req.remote` (a direct off-box connection); or
+ *  - a proxy-forwarding header ({@link isForwardedConnection}) — the connection was relayed, so a
+ *    loopback `req.remote` is the *proxy*, not the client. Refusing any forwarded connection keeps
+ *    the guard robust even if `/agentic` is inadvertently reverse-proxied over loopback (the
+ *    embedded/console-proxy topology), where the off-box client would otherwise appear same-host.
+ *
+ * Note this guards ONLY the agentic visibility channel: the capability HTTP hooks
+ * (`/app/api/hooks/*`) carry their own unguessable per-request tokens and stay reachable off-box
+ * (including through the console proxy), which is what a remote fleet needs. To attach agentic
+ * visibility from off-box — directly or via a proxy — run the channel in SECURE mode instead.
+ */
+export function loopbackOnly(base: Authenticator): Authenticator {
+  return (req) => {
+    if (isForwardedConnection(req.headers) || !isLoopbackRemote(req.remote)) {
+      return {
+        ok: false,
+        code: AUTH_UNAUTHORIZED,
+        reason:
+          "LOCAL-mode agentic channel is loopback-only and refuses reverse-proxied peers; use secure mode (NANO_AGENTIC_SECRET) for off-box or proxied peers",
+      };
+    }
+    return base(req);
+  };
+}
+
 export interface MountAgenticChannelOptions {
   /** The app's own `node:http` server (share its port; `app.httpServer` narrowed to `Server`). */
   readonly server: Server;
@@ -116,39 +195,44 @@ export async function mountAgenticChannel(
   }
 
   const transport = new WebSocketChannelTransport({ server, path: AGENTIC_PATH });
+  // LOCAL mode gates only on the well-known localhost token, so it must be honoured only for a
+  // same-machine peer: wrap the authenticator to refuse any non-loopback remote (see loopbackOnly).
+  // Secure mode presents a real ADR 0028 identity token + capability credential, so it is safe from
+  // any origin and needs no such guard.
+  const baseAuthenticator = sharedSecretAuthenticator({ secret, requireCredential: secure });
   const hub = new AgenticHub({
     transport,
     // Secure mode: a valid identity token PLUS a required capability credential upgrades; either
     // missing/invalid is rejected (4401 / 4403). Swap in a real ADR 0028 verifier later by passing an
-    // Authenticator. LOCAL mode: token-only (the well-known localhost token), no credential required.
-    authenticator: sharedSecretAuthenticator({ secret, requireCredential: secure }),
+    // Authenticator. LOCAL mode: token-only (the well-known localhost token), loopback peers only.
+    authenticator: secure ? baseAuthenticator : loopbackOnly(baseAuthenticator),
     onError: (err, connectionId) =>
       log.warn("agentic hub error", { connectionId, err: String(err) }),
   });
   // Share the app's port: the transport rode the existing server, so it is already listening.
   await transport.ready();
 
-  // LOCAL mode gates only on the well-known localhost token, so it is safe ONLY while the server is
-  // bound to loopback. The channel rides the app's server and does not own its bind address, so it
-  // cannot enforce this — but if the server is exposed on a wildcard/public interface, the token is
-  // reachable off-box; warn loudly so an operator either binds to loopback or switches to secure mode.
-  // A `null` address (server not listening yet) is unverifiable — warn rather than silently skipping
-  // the exposure check, since the bind could later resolve to a public interface.
+  // LOCAL mode is now enforced loopback-only per connection (see loopbackOnly), so the well-known
+  // token can never be honoured off-box even on a wildcard/all-interfaces bind. A non-loopback bind
+  // is still worth surfacing though: it means off-box agentic peers are REFUSED, so a remote worker
+  // fleet gets no visibility until the channel runs in secure mode. Warn so the operator makes the
+  // deliberate choice. A `null` address (server not listening yet) is unverifiable — warn too.
   if (!secure) {
     const addr = server.address();
     if (addr === null) {
       log.warn(
         "agentic channel is in LOCAL mode but the server bind address could not be verified " +
-          "(the server is not listening yet) — the well-known LOCAL_AGENTIC_TOKEN cannot be " +
-          "confirmed loopback-only. Mount the channel after the server is listening, set " +
-          "NANO_AGENTIC_SECRET for secure mode, or bind the server to 127.0.0.1.",
+          "(the server is not listening yet) — the loopback-only enforcement for the well-known " +
+          "LOCAL_AGENTIC_TOKEN cannot be confirmed. Mount the channel after the server is listening, " +
+          "set NANO_AGENTIC_SECRET for secure mode, or bind the server to 127.0.0.1.",
         { mode: "local", bind: null },
       );
     } else if (!isLoopbackBind(addr)) {
       log.warn(
-        "agentic channel is in LOCAL mode but the server is not bound to loopback — the well-known " +
-          "LOCAL_AGENTIC_TOKEN is reachable from other hosts. Set NANO_AGENTIC_SECRET for secure " +
-          "mode, or bind the server to 127.0.0.1.",
+        "agentic channel is in LOCAL mode but the server is not bound to loopback — off-box peers " +
+          "are refused the channel (the well-known LOCAL_AGENTIC_TOKEN is enforced loopback-only), " +
+          "so a remote worker fleet cannot attach visibility. Set NANO_AGENTIC_SECRET for secure " +
+          "mode to serve remote peers, or bind the server to 127.0.0.1.",
         { mode: "local", bind: typeof addr === "object" ? addr.address : String(addr) },
       );
     }

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.69.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 });