@nanobpm/nano-workforce 0.70.2 → 0.71.0

package/app/userTasks.ts

@@ -0,0 +1,217 @@
+// Unified "Tasks" inbox read-model (issue #236) — the schema-driven pages' single source for the
+// Tasks page, listing EVERY open native user-task escalation awaiting a human decision so an operator
+// can resolve one in the nwf UI (Urban's `taskInbox` at /tasks is a read-only stub).
+//
+// The four migrated escalations (ADR 0046) are native `userTask`s with linked `.form`s. Their
+// completable keys were only ever denormalised for the FEATURE kinds (migrations 031/032, onto
+// `feature_runs`); the epic/PR kinds (`plan-review-decision`, `trial-merge-decision`, the PR
+// `wait-answer`) had no app-side pointer, so the pages could not drive a completion. This module owns
+// the `user_tasks` read-model row shape and the PURE derivation the `pollUserTasks` reconcile
+// (app/service.ts) projects: `buildUserTaskRow` (one open task → a desired row) and
+// `reconcileUserTasks` (the desired set vs the persisted set → the minimal upserts + deletes). The
+// engine iteration + writes live in the poller; the decisions live here so they are unit-testable
+// without a host, mirroring `deriveFeatureEscalationPatch`.
+//
+// Completion is NOT owned here — the page posts the typed form variables to the ONE canonical human
+// completer (`completeEscalationAsHuman`, app/agentCompletion.ts) / the existing feature answer &
+// acknowledge operations, the exact resume path the task inbox uses. This module only makes the open
+// tasks visible; a completed task's row is removed on the next pass when the engine no longer reports
+// it open.
+import type { DataLayer } from "@nanobpm/urban";
+import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT } from "./feature.ts";
+import type { PlanReview } from "./plan.ts";
+import type { TrialMergeAuditRow } from "./trialMerge.ts";
+
+const now = () => new Date().toISOString();
+
+/** The plan-review cap escalation user task (plan-fanout.bpmn) — a human directive (proceed/revise)
+ *  when the adversarial review loop exhausts its budget without approval. */
+export const PLAN_REVIEW_ELEMENT = "plan-review-decision";
+
+/** The trial-merge escalation user task (plan-fanout.bpmn) — a human decision (proceed/rebase/abandon)
+ *  when a wave's trial merge comes back red. */
+export const TRIAL_MERGE_ELEMENT = "trial-merge-decision";
+
+/** The PR review-loop escalation user task (convergence-loop.bpmn) — a human answer that resumes the
+ *  review loop and is handed to the next round. */
+export const PR_WAIT_ANSWER_ELEMENT = "wait-answer";
+
+/** One row per currently-open native user-task escalation, denormalised for the Tasks page. Keyed on
+ *  the completable `user_task_key` (a task is open at most once). Present iff the engine reports the
+ *  task open; `pollUserTasks` deletes it once the task is gone. */
+export interface UserTaskRow {
+  user_task_key: string;
+  element_id: string;
+  kind_label: string;
+  subject_type: string;
+  subject_key: string;
+  subject_url: string | null;
+  question: string | null;
+  process_key: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export const userTasks = (data: DataLayer) => data.table<UserTaskRow>("user_tasks", "user_task_key");
+
+/** Human-readable label per escalation element. The set of keys is the closed set of user-task
+ *  elements the Tasks inbox surfaces — an element absent from here is not an escalation and is
+ *  ignored by `buildUserTaskRow`, so an arbitrary internal user task can never leak into the inbox. */
+export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
+  [FEATURE_ESCALATION_ELEMENT]: "Feature escalation",
+  [FEATURE_BLOCKED_ELEMENT]: "Blocked feature run",
+  [PLAN_REVIEW_ELEMENT]: "Plan review",
+  [TRIAL_MERGE_ELEMENT]: "Trial merge",
+  [PR_WAIT_ANSWER_ELEMENT]: "PR review",
+};
+
+/** The denormalised context the poller has resolved for an open escalation user task. */
+export interface UserTaskContext {
+  userTaskKey: string;
+  elementId: string;
+  subjectType: "feature" | "plan" | "pr";
+  subjectKey: string;
+  subjectUrl?: string | null;
+  question?: string | null;
+  processKey?: string | null;
+}
+
+/** Pure: turn one resolved open escalation task into its desired read-model row, or `null` when the
+ *  element is not one of the surfaced escalation kinds (so a non-escalation user task is never listed)
+ *  or the required keys are blank. `created_at`/`updated_at` default to now for a fresh row; the
+ *  reconcile preserves the original `created_at` on an update. */
+export function buildUserTaskRow(ctx: UserTaskContext, at: string = now()): UserTaskRow | null {
+  const userTaskKey = ctx.userTaskKey.trim();
+  const subjectKey = ctx.subjectKey.trim();
+  const kindLabel = USER_TASK_KIND_LABELS[ctx.elementId];
+  if (!userTaskKey || !subjectKey || !kindLabel) return null;
+  const question = typeof ctx.question === "string" && ctx.question.trim() ? ctx.question.trim() : null;
+  return {
+    user_task_key: userTaskKey,
+    element_id: ctx.elementId,
+    kind_label: kindLabel,
+    subject_type: ctx.subjectType,
+    subject_key: subjectKey,
+    subject_url: ctx.subjectUrl ?? null,
+    question,
+    process_key: ctx.processKey ?? null,
+    created_at: at,
+    updated_at: at,
+  };
+}
+
+/** The minimal write plan a reconcile pass applies: rows to insert, rows to update in place (the
+ *  task is still open but its denormalised context changed), and keys to delete (the task is gone). */
+export interface UserTaskReconcile {
+  inserts: UserTaskRow[];
+  updates: UserTaskRow[];
+  deletes: string[];
+}
+
+/** True when the persisted row already matches the freshly-derived one on every display field, so the
+ *  reconcile can skip a no-op write (an update touches `updated_at`, which would otherwise churn the
+ *  row on every pass). `created_at`/`updated_at` are intentionally excluded. */
+function sameRow(a: UserTaskRow, b: UserTaskRow): boolean {
+  return (
+    a.element_id === b.element_id &&
+    a.kind_label === b.kind_label &&
+    a.subject_type === b.subject_type &&
+    a.subject_key === b.subject_key &&
+    a.subject_url === b.subject_url &&
+    a.question === b.question &&
+    a.process_key === b.process_key
+  );
+}
+
+/** Pure source of truth for the `pollUserTasks` reconcile: diff the DESIRED open-task rows (derived
+ *  from the engine this pass) against the PERSISTED rows, returning the minimal insert/update/delete
+ *  plan. A desired row not yet persisted is an insert; a persisted row whose task is still desired but
+ *  whose context drifted is an update (preserving its original `created_at`); a persisted row no longer
+ *  desired is a delete (its task was completed — here, via the inbox, or out-of-band). Idempotent: a
+ *  steady state with no drift yields empty lists, so the poller performs zero writes. */
+export function reconcileUserTasks(persisted: UserTaskRow[], desired: UserTaskRow[]): UserTaskReconcile {
+  const persistedByKey = new Map(persisted.map((r) => [r.user_task_key, r]));
+  const desiredByKey = new Map(desired.map((r) => [r.user_task_key, r]));
+  const inserts: UserTaskRow[] = [];
+  const updates: UserTaskRow[] = [];
+  const deletes: string[] = [];
+
+  for (const row of desired) {
+    const existing = persistedByKey.get(row.user_task_key);
+    if (!existing) {
+      inserts.push(row);
+    } else if (!sameRow(existing, row)) {
+      updates.push({ ...row, created_at: existing.created_at });
+    }
+  }
+  for (const row of persisted) {
+    if (!desiredByKey.has(row.user_task_key)) deletes.push(row.user_task_key);
+  }
+  return { inserts, updates, deletes };
+}
+
+// ── Audit-table accessors + derivations used by the poller to enrich the question text ────────────
+// These read the question/findings each escalation kind already records in a SURVIVING audit table,
+// keyed by the subject, so the Tasks grid can show WHAT is being decided. They are display-only.
+//
+// NB: the bespoke `plan_escalations` / `plan_review_escalations` mirror tables were retired in
+// migration 027 (the CONTRACT phase of the native-userTask migration), so the enrichment is derived
+// from the canonical append-only audit logs that DID survive — `plan_reviews` (the adversarial
+// plan-review log) and `plan_trial_merges` (the D3 trial-merge gate log) — not from a dropped mirror.
+// The PR-loop `escalations` audit table was deliberately KEPT by 027, so `prEscalations` still reads it.
+
+/** Pure: the findings that drove the still-open `plan-review-decision` escalation — the latest
+ *  adversarial plan-review round's critique. `plan_reviews` is append-only per (epoch, round); the
+ *  parked escalation is the tail of the current epoch, so the latest round by (epoch, round) carries
+ *  the rejecting findings the human is being asked to overrule. `null` when there is no round yet. */
+export function latestPlanReviewFindings(reviews: readonly PlanReview[]): string | null {
+  let latest: PlanReview | undefined;
+  for (const r of reviews) {
+    if (!latest || r.epoch > latest.epoch || (r.epoch === latest.epoch && r.round > latest.round)) latest = r;
+  }
+  return latest?.findings ?? null;
+}
+
+/** Pure: the summary that drove the still-open `trial-merge-decision` escalation — the newest
+ *  UNRESOLVED red trial-merge attempt. `plan_trial_merges` is append-only and supersede-on-insert
+ *  marks superseded rows `resolved = 1`, so the newest unresolved `suite-failed`/`merge-conflict` row
+ *  (highest `id`) is the wave awaiting the human decision. `null` when none is open. */
+export function latestTrialMergeQuestion(audits: readonly TrialMergeAuditRow[]): string | null {
+  let latest: TrialMergeAuditRow | undefined;
+  for (const a of audits) {
+    if (a.resolved === 1) continue;
+    if (a.result !== "suite-failed" && a.result !== "merge-conflict") continue;
+    if (!latest || a.id > latest.id) latest = a;
+  }
+  return latest?.summary ?? null;
+}
+
+/** One PR review-loop escalation (001_init.sql `escalations`). `status` is open | answered; the poller
+ *  reads the OPEN row's `question`. */
+export interface PrEscalationRow {
+  id: number;
+  pr_key: string;
+  round_no: number;
+  kind: string;
+  question: string;
+  answer: string | null;
+  status: string;
+  asked_at: string;
+  answered_at: string | null;
+}
+
+export const prEscalations = (data: DataLayer) =>
+  data.table<PrEscalationRow>("escalations", "id");
+
+/** Pure: the question for the still-open PR review-loop escalation. `escalations` is append-only and
+ *  `id` is an AUTOINCREMENT PK, so when a PR has multiple `open` rows the newest (highest `id`) is the
+ *  live one the human is being asked; a positional `[0]` from an unordered `find` could surface a stale
+ *  row. `null` when there is no open escalation. */
+export function latestOpenEscalationQuestion(rows: readonly PrEscalationRow[]): string | null {
+  let latest: PrEscalationRow | undefined;
+  for (const r of rows) {
+    if (r.status !== "open") continue;
+    if (!latest || r.id > latest.id) latest = r;
+  }
+  return latest?.question ?? null;
+}

package/db/migrations/034_user_tasks_inbox.sql

@@ -0,0 +1,51 @@
+-- Unified "Tasks" inbox read-model (issue #236) — surface EVERY open native user-task escalation
+-- awaiting a human decision in the nwf UI, so an operator can resolve one without leaving the app.
+--
+-- The four migrated escalations (ADR 0046) are native BPMN `userTask`s with linked `.form`s:
+-- `feature-escalation` (a stuck single-issue run), `feature-blocked` (a blocked run to acknowledge),
+-- `plan-review-decision` (a plan-review cap escalation), `trial-merge-decision` (a red trial merge),
+-- and the PR review-loop `wait-answer`. The completable user-task keys were only ever denormalised
+-- for the FEATURE kinds (migrations 031/032, onto `feature_runs`); the epic/PR kinds had NO app-side
+-- pointer at all, so the only surface that listed them was Urban's read-only `taskInbox` stub.
+--
+-- This is the schema-driven pages' single source for the Tasks page `dataGrid`s: `pollUserTasks`
+-- (app/service.ts) reconciles one row per currently-open escalation user task from the engine
+-- (`searchUserTasks`), denormalising the completable `user_task_key` plus display context (the
+-- escalation `question`, its `subject_*`, and `element_id`). A row exists iff the user task is open;
+-- the poller deletes a row once its task is gone (answered here, via the task inbox, or out-of-band),
+-- so `showCount` reflects live pending work. The completion affordances post the typed form variables
+-- to the canonical human completer (`completeEscalationAsHuman` / the existing feature answer/ack
+-- operations), the same resume path the task inbox uses — no parallel completion.
+--
+-- Forward-only, additive (expand): a brand-new table, no existing shape touched. Numbered after the
+-- current highest prefix (033); the runner wraps each file in its own transaction, so this file must
+-- NOT contain BEGIN/COMMIT.
+CREATE TABLE user_tasks (
+  -- The completable native user-task key (the engine's `userTaskKey`) — the PK, since a user task is
+  -- open at most once and every completion affordance posts to it.
+  user_task_key TEXT PRIMARY KEY,
+  -- The BPMN `elementId` of the parked user task (one of the migrated escalation elements). Drives
+  -- which typed decision form / completion operation the page routes the answer through.
+  element_id    TEXT NOT NULL,
+  -- Human-readable kind label for the grid (e.g. "Plan review", "Trial merge").
+  kind_label    TEXT NOT NULL,
+  -- The domain subject the escalation belongs to: `subject_type` is feature | plan | pr; `subject_key`
+  -- is its aggregate key (feature_key / plan_key / pr_key); `subject_url` is an optional external link
+  -- (the issue/PR URL) shown as a clickable column.
+  subject_type  TEXT NOT NULL,
+  subject_key   TEXT NOT NULL,
+  subject_url   TEXT,
+  -- The escalation question / findings the agent (or loop) raised, denormalised for display so the
+  -- operator can decide without opening the process. Best-effort; NULL when none was recorded.
+  question      TEXT,
+  -- The owning process instance key, for the process-explorer link. NULL when unknown.
+  process_key   TEXT,
+  created_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL
+);
+
+-- The pages filter the grid by `element_id` (one grid per kind) and order by recency
+-- (`WHERE element_id IN (...) ORDER BY updated_at DESC`). A single composite index on
+-- `(element_id, updated_at)` serves both the equality filter and the ordered read in one structure —
+-- no extra sort/scan — so the read stays O(matching), not O(all open tasks), as the table grows.
+CREATE INDEX idx_user_tasks_element_updated ON user_tasks(element_id, updated_at);

package/nano.app.json

@@ -66,7 +66,8 @@
       "statusField": "status",
       "activeStatuses": [
         "running",
-        "escalated"
+        "escalated",
+        "awaiting_operator"
       ],
       "onTerminated": {
         "set": {

package/openapi.yaml

@@ -1244,6 +1244,59 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /actions/complete-user-task:
+    post:
+      operationId: completeUserTask
+      summary: "Complete an open native user-task escalation from the nwf Tasks inbox (issue #236).
+        Submits the parked task's typed `.form` variables (e.g. a plan-review `{ directive, notes }`, a
+        trial-merge `{ action, notes }`, or a PR `{ answer }`) to the canonical human completer
+        (completeEscalationAsHuman → completeUserTaskAttributed) — the same resume path the task inbox
+        uses, recording who answered. The completer refuses any user task that is not one of the
+        migrated escalation elements. The feature-run kinds keep their own operations
+        (answer-escalation / acknowledge-blocked); this door is for the plan-review / trial-merge / PR
+        `wait-answer` kinds whose completion is a straight typed pass-through. On success the answered
+        task's read-model row is dropped so the Tasks grid stops offering a decision for it."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - userTaskKey
+                - variables
+              properties:
+                userTaskKey:
+                  type: string
+                  minLength: 1
+                  description: The parked escalation user-task key (user_tasks.user_task_key).
+                variables:
+                  type: object
+                  additionalProperties: true
+                  description: The typed form variables the parked task's `.form` expects (kind-specific).
+                operator:
+                  type: string
+                  description: Optional operator handle recorded in the attribution ledger; defaults to "operator".
+      responses:
+        "200":
+          description: The escalation user task was completed and the process resumed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field was missing/invalid, or the target is not an escalation task.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No open escalation user task matches the userTaskKey.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /actions/acknowledge-blocked:
     post:
       operationId: acknowledgeBlocked

package/operations/completeUserTask.test.ts

@@ -0,0 +1,146 @@
+// Tests for the POST /app/api/actions/complete-user-task operation `completeUserTask` (issue #236).
+// The nwf Tasks page's decision affordance for the plan-review / trial-merge / PR `wait-answer`
+// escalations: it routes the typed form variables through the canonical human completer
+// (completeEscalationAsHuman → completeUserTaskAttributed), resuming the process exactly as the task
+// inbox would, and drops the answered task's read-model row so the grid stops offering a decision.
+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 "./completeUserTask.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: in-memory doubles, mirrors acknowledgeBlocked.test.ts
+function memApp(openTasks: { userTaskKey: string; elementId?: string }[]): {
+  app: AppApi;
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  stores: Record<string, any[]>;
+  completed: { userTaskKey: string; variables: Record<string, unknown> }[];
+} {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  const stores: Record<string, any[]> = {};
+  const completed: { userTaskKey: string; variables: Record<string, unknown> }[] = [];
+  function tbl(name: string, pk: string) {
+    // biome-ignore lint/suspicious/noExplicitAny: see above
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async insert(row: any) {
+        rows.push({ ...row });
+        return rows.length;
+      },
+      // 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) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async delete(id: any) {
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+      // 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 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(),
+    // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  } as any as AppApi;
+  return { app, stores, completed };
+}
+
+async function call(app: AppApi, body: unknown) {
+  // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("complete-user-task: completes a plan-review escalation and drops its read-model row", async () => {
+  const { app, stores, completed } = memApp([{ userTaskKey: "ut-1", elementId: "plan-review-decision" }]);
+  stores.user_tasks = [{ user_task_key: "ut-1", element_id: "plan-review-decision" }];
+
+  const res = await call(app, { userTaskKey: "ut-1", variables: { directive: "revise", notes: "narrow scope" } });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.elementId, "plan-review-decision");
+  assertEquals(completed, [{ userTaskKey: "ut-1", variables: { directive: "revise", notes: "narrow scope" } }]);
+  assertEquals(stores.user_tasks, []);
+  // Attribution recorded as a human completion.
+  assertEquals(stores.task_completions.length, 1);
+  assertEquals(stores.task_completions[0].actor_kind, "human");
+});
+
+test("complete-user-task: completes a trial-merge escalation with the typed action variable", async () => {
+  const { app, completed } = memApp([{ userTaskKey: "ut-2", elementId: "trial-merge-decision" }]);
+
+  const res = await call(app, { userTaskKey: "ut-2", variables: { action: "rebase" } });
+
+  assertEquals(res.status, 200);
+  assertEquals(completed, [{ userTaskKey: "ut-2", variables: { action: "rebase" } }]);
+});
+
+test("complete-user-task: a missing userTaskKey is a 400", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { variables: { answer: "x" } });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+});
+
+test("complete-user-task: non-object variables are rejected 400", async () => {
+  const { app } = memApp([{ userTaskKey: "ut-3", elementId: "wait-answer" }]);
+  const res = await call(app, { userTaskKey: "ut-3", variables: "nope" });
+  assertEquals(res.status, 400);
+});
+
+test("complete-user-task: an unknown key is a 404 (no open escalation task)", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { userTaskKey: "ghost", variables: { answer: "x" } });
+  assertEquals(res.status, 404);
+});
+
+test("complete-user-task: refuses a non-escalation user task (400)", async () => {
+  const { app, completed } = memApp([{ userTaskKey: "ut-4", elementId: "feature-blocked" }]);
+  const res = await call(app, { userTaskKey: "ut-4", variables: { note: "x" } });
+  assertEquals(res.status, 400);
+  assertEquals(completed, []);
+});
+
+test("complete-user-task: a read-model cleanup failure does not mask a resumed completion (200)", async () => {
+  const { app, completed } = memApp([{ userTaskKey: "ut-5", elementId: "plan-review-decision" }]);
+  // The engine has already resumed the process; a transient delete failure on the latency-optimising
+  // read-model cleanup must not surface as a 5xx for a task that IS completed (poller reconciles).
+  const realTable = app.data.table.bind(app.data);
+  // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  (app.data as any).table = (name: string, pk: string) => {
+    const t = realTable(name, pk);
+    if (name === "user_tasks") {
+      return {
+        ...t,
+        delete: async () => {
+          throw new Error("transient DB error");
+        },
+      };
+    }
+    return t;
+  };
+
+  const res = await call(app, { userTaskKey: "ut-5", variables: { directive: "revise", notes: "narrow scope" } });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(completed, [{ userTaskKey: "ut-5", variables: { directive: "revise", notes: "narrow scope" } }]);
+});

package/operations/completeUserTask.ts

@@ -0,0 +1,72 @@
+// POST /app/api/actions/complete-user-task → operationId `completeUserTask` (issue #236).
+//
+// The nwf **Tasks** page's decision affordance for the epic/PR native escalations that had no
+// app-side completion path — `plan-review-decision`, `trial-merge-decision`, and the PR review-loop
+// `wait-answer`. An operator submits the parked task's typed `.form` variables (e.g. a plan-review
+// `{ directive, notes }`, a trial-merge `{ action, notes }`, or a PR `{ answer }`) directly from the
+// Tasks inbox instead of only from Urban's read-only task-inbox stub.
+//
+// It routes through the ONE canonical human completer (`completeEscalationAsHuman` →
+// `completeUserTaskAttributed`), so the completion uses the exact same typed variables and engine
+// resume path a human drives from the task inbox — no parallel completion — while recording WHO
+// answered in the `task_completions` ledger. That completer refuses any user task that is not one of
+// the migrated escalation elements (`ESCALATION_TASK_ELEMENTS`), so this generic door can never
+// complete an arbitrary internal user task. The feature-run kinds keep their own reconcile-bearing
+// operations (`answer-escalation` / `acknowledge-blocked`); this door is for the escalation kinds
+// whose completion is a straight typed pass-through.
+//
+// On success it removes the answered task's `user_tasks` read-model row so the Tasks grid stops
+// offering a decision for a task that is now completed, without waiting a poll cycle; the poller
+// (`pollUserTasks`) is the durable source of truth and will re-derive the exact same empty state.
+// That read-model cleanup is best-effort — a transient delete failure is logged and swallowed rather
+// than masking a completion the engine has already resumed with a spurious 5xx.
+//
+// The runtime validates the body against openapi.yaml (`userTaskKey` + `variables` required); this
+// delegate narrows the validated shape and applies the shared human-completion contract.
+
+import { completeEscalationAsHuman } from "../app/agentCompletion.ts";
+import { userTasks } from "../app/userTasks.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("completeUserTask", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("complete-user-task rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "userTaskKey and variables are required" } };
+  }
+
+  const userTaskKey = str(body.userTaskKey);
+  if (!userTaskKey) return { status: 400, body: { ok: false, error: "userTaskKey is required" } };
+
+  const variables = body.variables;
+  if (!variables || typeof variables !== "object" || Array.isArray(variables)) {
+    return { status: 400, body: { ok: false, error: "variables must be an object" } };
+  }
+
+  // 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 completion.
+  const operatorId = str(body.operator) || "operator";
+
+  const r = await completeEscalationAsHuman(app.data, app.engine, { userTaskKey, operatorId, variables });
+  if (r.ok) {
+    // Reconcile this operation's OWN action immediately: drop the read-model row so the Tasks page
+    // stops offering a decision for a task that is now completed. The poller re-derives the same
+    // state, so this is a latency optimisation, not the source of truth — make it best-effort so a
+    // transient cleanup failure never masks a completion the engine has already resumed (which would
+    // return a spurious 5xx to the UI for a task that IS done). The poller re-derives the empty state.
+    try {
+      await userTasks(app.data).delete(userTaskKey);
+    } catch (err) {
+      app.log.warn("complete-user-task: read-model cleanup failed (poller will reconcile)", {
+        userTaskKey,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+    app.log.info("operator completed user task", { userTaskKey, elementId: r.elementId });
+    return { status: 200, body: { ok: true, completionId: r.completionId, elementId: r.elementId } };
+  }
+  const status = r.reason === "no open escalation task" ? 404 : 400;
+  app.log.warn("complete-user-task: 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.70.2",
+  "version": "0.71.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/cockpit.page.json

@@ -13,6 +13,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ],
         "sticky": true

package/pages/epic-detail.page.json

@@ -14,6 +14,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }

package/pages/epic.page.json

@@ -14,6 +14,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }

package/pages/feature.page.json

@@ -14,6 +14,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }

package/pages/home.page.json

@@ -25,6 +25,10 @@
             "label": "Feature",
             "page": "feature"
           },
+          {
+            "label": "Tasks",
+            "page": "tasks"
+          },
           {
             "label": "Cockpit",
             "page": "cockpit"

package/pages/overview.page.json

@@ -14,6 +14,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }