@nanobpm/nano-workforce 0.66.0 → 0.68.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Features
+
+* **agentic:** local-first visibility — on by default, security opt-in (hub) ([#218](https://github.com/nanobpm/nano-workforce/issues/218)) ([ffef1d9](https://github.com/nanobpm/nano-workforce/commit/ffef1d9819679cb6995ad2d2825bce5c6cabccb5)), closes [jwulf/c8ctl-plugin-nano#38](https://github.com/jwulf/c8ctl-plugin-nano/issues/38)
+
 # [0.66.0](https://github.com/nanobpm/nano-workforce/compare/v0.65.0...v0.66.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/agentic/channel.test.ts

@@ -5,10 +5,11 @@
 // 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 { createLogger } from "@nanobpm/urban/runtime";
 import { WebSocket } from "ws";
 import { assert, assertEquals } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
-import { type AgenticChannelHandle, mountAgenticChannel } from "./channel.ts";
+import { type AgenticChannelHandle, LOCAL_AGENTIC_TOKEN, mountAgenticChannel } from "./channel.ts";
 import { type AgenticContext, AgenticFamilyRegistry } from "./registry.ts";
 
 const SECRET = "test-agentic-secret";
@@ -242,3 +243,119 @@ test("a missing secret is refused (never mount an open channel)", async (t) => {
   assert(threw, "mountAgenticChannel must reject an empty secret");
   assertEquals(port > 0, true);
 });
+
+test("LOCAL mode (secure:false): the well-known token upgrades with NO credential", async (t) => {
+  const { server, port } = await startHttp();
+  // Local-first default-on: no secret, no credential — a `nano work` worker appears live with the
+  // well-known localhost token alone (security opt-in).
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const ws = await connect(port, `?token=${LOCAL_AGENTIC_TOKEN}`);
+  assertEquals(ws.readyState, WebSocket.OPEN);
+  assertEquals(channel.hub.connectionCount, 1);
+  assertEquals(channel.inspect().mode, "local");
+  ws.close();
+});
+
+test("LOCAL mode still rejects a wrong token (4401)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, "?token=not-the-local-token");
+  assertEquals(closedCode, 4401);
+  assertEquals(channel.hub.connectionCount, 0);
+});
+
+/** A capturing `Logger`: records every `(level, msg)` pair the sink receives. */
+function capturingLog(): { log: ReturnType<typeof noopLog>; records: Array<{ level: string; msg: string }> } {
+  const records: Array<{ level: string; msg: string }> = [];
+  const log = createLogger((level: string, msg: string) => {
+    records.push({ level, msg });
+  });
+  return { log, records };
+}
+
+test("LOCAL mode warns when the server is bound to a non-loopback interface", async (t) => {
+  const server = createServer((_req, res) => res.end());
+  await new Promise<void>((resolve) => server.listen(0, "0.0.0.0", resolve));
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const warned = records.some((r) => r.level === "warn" && r.msg.includes("not bound to loopback"));
+  assert(warned, "LOCAL mode on a non-loopback bind must warn that the well-known token is exposed");
+});
+
+test("LOCAL mode warns when the server bind address is unverifiable (not listening)", async (t) => {
+  const { server } = await startHttp();
+  // Simulate a server whose bind cannot be verified (e.g. mounted before `listen` resolves):
+  // `address()` returns null, so the LOCAL exposure check cannot confirm a loopback-only bind.
+  const realAddress = server.address.bind(server);
+  server.address = () => null;
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    server.address = realAddress;
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const warned = records.some(
+    (r) => r.level === "warn" && r.msg.includes("bind address could not be verified"),
+  );
+  assert(warned, "LOCAL mode on an unbound server must warn that the well-known token is unverifiable");
+});
+
+test("LOCAL mode does NOT warn when the server is bound to loopback", async (t) => {
+  const { server } = await startHttp();
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  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");
+});

package/app/agentic/channel.ts

@@ -14,6 +14,7 @@
 // Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
 // is untouched; advisory semantics preserved (a family never gates a BPMN sequence flow).
 import type { Server } from "node:http";
+import type { AddressInfo } from "node:net";
 import {
   AgenticHub,
   sharedSecretAuthenticator,
@@ -26,11 +27,47 @@ import { AgenticFamilyRegistry } from "./registry.ts";
 /** The path the agentic channel is served on, on the app's own port. */
 export const AGENTIC_PATH = "/agentic";
 
+/**
+ * The well-known identity token used in LOCAL mode (security opt-in). Nano is local-first: on a
+ * developer's own machine the visibility channel is on by default with no credential friction, so
+ * the hub and the `nano work` worker agree on this constant, well-known localhost token. It is NOT
+ * a secret — it only gates same-machine dev traffic. In secure mode (`secure: true` + a real
+ * `NANO_AGENTIC_SECRET`) this constant is never used and a real ADR 0028 verifier applies. Keep in
+ * lock-step with the worker constant in jwulf/c8ctl-plugin-nano (`c8ctl-plugin.js` LOCAL_AGENTIC_TOKEN).
+ */
+export const LOCAL_AGENTIC_TOKEN = "nano-local";
+
+/**
+ * True if `addr` (from {@link Server.address}) is a loopback / same-machine bind — the safety
+ * assumption LOCAL mode relies on. A string address is a UNIX domain socket / named pipe (same-host
+ * only) and is treated as safe; a TCP bind is loopback only for `127.0.0.0/8` or `::1`. A wildcard
+ * bind (`0.0.0.0` / `::`) or any specific public interface is NOT loopback, so the well-known
+ * {@link LOCAL_AGENTIC_TOKEN} would be reachable off-box. `null` (an unbound / not-yet-listening
+ * server) is NOT treated as safe — the bind is unverifiable, so callers must handle it explicitly
+ * rather than silently skipping the exposure check.
+ */
+function isLoopbackBind(addr: string | AddressInfo | null): boolean {
+  if (addr === null) return false;
+  if (typeof addr === "string") return true;
+  const host = addr.address;
+  return host === "::1" || host === "::ffff:127.0.0.1" || host.startsWith("127.");
+}
+
 export interface MountAgenticChannelOptions {
   /** The app's own `node:http` server (share its port; `app.httpServer` narrowed to `Server`). */
   readonly server: Server;
-  /** The shared-secret ADR 0028 identity token every valid peer must present as `?token=…`. */
+  /** The shared-secret ADR 0028 identity token every valid peer must present as `?token=…`. In LOCAL
+   * mode (`secure: false`) this may be empty — the hub substitutes {@link LOCAL_AGENTIC_TOKEN}. */
   readonly secret: string;
+  /**
+   * Security mode. Nano is local-first, so this defaults to `true` (strict) at the library level to
+   * keep the fail-closed contract for any caller that doesn't opt in — but `main.ts` passes
+   * `secure: false` whenever no `NANO_AGENTIC_SECRET` is configured, mounting an on-by-default LOCAL
+   * channel: a well-known localhost token ({@link LOCAL_AGENTIC_TOKEN}) and NO required capability
+   * credential. Set `secure: true` (with a real secret) to require an ADR 0028 identity token AND a
+   * capability credential on every upgrade.
+   */
+  readonly secure?: boolean;
   /** The app's SQLite data layer, threaded to family modules (may be absent when data isn't mounted). */
   readonly data: DataLayer | undefined;
   /** A structured logger for lifecycle lines. */
@@ -67,21 +104,56 @@ async function discoverRegistry(log: Logger): Promise<AgenticFamilyRegistry> {
 export async function mountAgenticChannel(
   opts: MountAgenticChannelOptions,
 ): Promise<AgenticChannelHandle> {
-  const { server, secret, data, log } = opts;
-  if (!secret) throw new Error("mountAgenticChannel requires a non-empty identity secret");
+  const { server, data, log } = opts;
+  // Local-first: `secure` defaults to true at the library level (fail-closed for callers that don't
+  // opt in), but `main.ts` passes `secure: false` for the on-by-default LOCAL channel. In LOCAL mode
+  // an empty secret is fine — we substitute the well-known localhost token and drop the credential
+  // requirement so a `nano work` worker appears live with zero configuration.
+  const secure = opts.secure ?? true;
+  const secret = opts.secret || (secure ? "" : LOCAL_AGENTIC_TOKEN);
+  if (secure && !secret) {
+    throw new Error("mountAgenticChannel (secure mode) requires a non-empty identity secret");
+  }
 
   const transport = new WebSocketChannelTransport({ server, path: AGENTIC_PATH });
   const hub = new AgenticHub({
     transport,
-    // 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.
-    authenticator: sharedSecretAuthenticator({ secret, requireCredential: true }),
+    // 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 }),
     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.
+  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.",
+        { 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.",
+        { mode: "local", bind: typeof addr === "object" ? addr.address : String(addr) },
+      );
+    }
+  }
+
   // If discovery or any family mount throws, the transport + hub are already live: tear down whatever
   // mounted (in reverse) and close the hub before rethrowing, so a failed boot never strands upgrade
   // handlers or half-open connections.
@@ -97,6 +169,7 @@ export async function mountAgenticChannel(
 
   log.info("agentic channel mounted", {
     path: AGENTIC_PATH,
+    mode: secure ? "secure" : "local",
     families: registry.names(),
   });
 
@@ -108,6 +181,7 @@ export async function mountAgenticChannel(
     inspect() {
       return {
         path: AGENTIC_PATH,
+        mode: secure ? "secure" : "local",
         families: registry.names(),
         connections: hub.connectionCount,
         address: hub.address,

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/main.ts

@@ -46,24 +46,40 @@ const app = await runFromEnv({ engine, host, port: PORT, handleSignals: false })
 // Agentic visibility channel (ADR 0056, epic #142). Ride the app's OWN HTTP server so the channel
 // shares the app port (no sidecar). This is the ONLY main.ts wiring for the whole epic — sibling
 // slices (H1/H3/H4) extend it by dropping a family module under `app/agentic/families/`, never here.
-// Mount only when a shared identity secret is configured, so the app never exposes an
-// unauthenticated upgrade; `app.httpServer` is a `node:http` Server once started (undefined on hosts
-// that don't surface one, e.g. Deno).
+//
+// Local-first (security opt-in): Nano is designed for local use, so the channel is ON BY DEFAULT.
+//   - No secret configured  -> LOCAL mode: well-known localhost token, no credential required, so a
+//     `nano work` worker appears live with zero configuration.
+//   - `NANO_AGENTIC_SECRET` (or `NANO_PR_WEBHOOK_SECRET`) set -> SECURE mode: ADR 0028 identity token
+//     + capability credential required on every upgrade.
+//   - `NANO_AGENTIC=off` (or 0/false/no) -> disabled entirely.
+// `app.httpServer` is a `node:http` Server once started (undefined on hosts that don't surface one,
+// e.g. Deno).
 let agentic: AgenticChannelHandle | undefined;
 const agenticSecret = envVar("NANO_AGENTIC_SECRET") ?? envVar("NANO_PR_WEBHOOK_SECRET");
+const agenticDisabled = /^(0|off|false|no)$/i.test(envVar("NANO_AGENTIC") ?? "");
 const httpServer = app.httpServer;
 if (httpServer instanceof Server) {
-  if (agenticSecret) {
+  if (agenticDisabled) {
+    app.log.info("agentic channel disabled (NANO_AGENTIC=off)");
+  } else {
+    const secure = Boolean(agenticSecret);
     agentic = await mountAgenticChannel({
       server: httpServer,
-      secret: agenticSecret,
+      secret: agenticSecret ?? "",
+      secure,
       data: app.data,
       log: app.log,
     });
-  } else {
-    app.log.warn("agentic channel not mounted: set NANO_AGENTIC_SECRET (or NANO_PR_WEBHOOK_SECRET)");
+    if (!secure) {
+      app.log.info(
+        "agentic channel mounted in LOCAL mode (on by default, token-only — a well-known localhost " +
+          "token, no capability credential). Set NANO_AGENTIC_SECRET for secure mode, or " +
+          "NANO_AGENTIC=off to disable.",
+      );
+    }
   }
-} else if (agenticSecret) {
+} else if (!agenticDisabled) {
   app.log.warn("agentic channel not mounted: app.httpServer is not a node:http Server on this host");
 }
 

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