@nanobpm/nano-workforce 0.125.0 → 0.127.0

package/.github/workflows/invariants.yml

@@ -11,11 +11,19 @@ name: Whole-repo invariants (merge-skew guard)
 #
 # This lean workflow re-asserts those whole-repo invariants where the merge actually happens:
 #   - `merge_group`  — the queue's PROSPECTIVE merged commit, so a skew is blocked BEFORE it lands.
+#                      THIS is the merge-skew guard: `derived == f(sources_A ∪ sources_B)`.
+#   - `pull_request` — required so the SAME check (matched by job name) also reports on the PR head.
+#                      GitHub's merge queue will not enqueue a PR until every required status check
+#                      has reported on it, and a check that fires only on `merge_group` never does —
+#                      it stays "expected" and the PR can never enter the queue (deadlock). The PR-head
+#                      run also validates the PR's OWN tree (a self-collision / stale artifact the PR
+#                      introduces alone), catching it before the queue rather than at merge time.
 #   - `push: [main]` — a fast backstop that fails a `main`-scoped build within minutes if something
 #                      slipped through, instead of first surfacing on an unrelated open PR.
 #   - `schedule`     — a daily catch-all for any skew introduced by a merge that bypassed the queue.
 on:
   merge_group:
+  pull_request:
   push:
     branches: [main]
   schedule:

package/.github/workflows/pr-title-lint.yml

@@ -7,6 +7,13 @@ name: PR title lint
 on:
   pull_request:
     types: [opened, edited, synchronize, reopened]
+  # Required status checks in the `main` merge queue must ALSO report on the
+  # queue's speculative `merge_group` commit, or the queue stalls forever waiting
+  # for a check that only ran on the PR. A `merge_group` commit has no PR title to
+  # lint (the title was already validated when the PR entered the queue), so the
+  # job runs with its only step skipped and reports success — the green the queue
+  # needs, without re-linting.
+  merge_group:
 
 permissions:
   pull-requests: read
@@ -16,7 +23,8 @@ jobs:
     name: Conventional PR title
     runs-on: ubuntu-latest
     steps:
-      - uses: amannn/action-semantic-pull-request@v5
+      - if: github.event_name == 'pull_request'
+        uses: amannn/action-semantic-pull-request@v5
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:

package/.github/workflows/release.yml

@@ -43,8 +43,14 @@ jobs:
           REPO: ${{ github.repository }}
         run: |
           set -euo pipefail
-          # These must ALL be `success` on the release commit before we ship. Keep
-          # in lock-step with the `main` ruleset's required status checks.
+          # These must ALL be `success` on the release commit before we ship.
+          # This is the `main` ruleset's required-check set MINUS the PR-only
+          # checks: `Conventional PR title` gates the merge queue but never runs
+          # on `push:main` (it has no PR title to lint on a merge commit — see
+          # pr-title-lint.yml), so requiring it here would deadlock every release.
+          # With the merge queue enabled these checks already passed on the
+          # speculative merged commit before it landed; this `push:main` gate is
+          # the backstop. Keep in lock-step with the ruleset's required checks.
           required=("typecheck + test (Node)" "whole-repo invariants")
           # Dedupe to ONE row per check name — the latest run (max .id) — so re-runs
           # can't leave us reading a stale conclusion. Slurp every page into a

package/AGENTS.md

@@ -370,6 +370,24 @@ agents:
 - **Never `git push --force` on `main`;** use `--force-with-lease` on feature
   branches.
 
+### Merging to `main` (merge queue)
+
+`main` is protected by an **active ruleset** with a **GitHub merge queue**. You
+do not merge a PR directly — you **add it to the queue** (UI "Merge when ready",
+or the product merge loop's queued-merge path). The queue then builds the
+**prospective merged commit** (`merge_group`) and only lands it if the required
+checks pass **on that speculative tree**:
+
+- `typecheck + test (Node)`, `whole-repo invariants`, `Conventional PR title`.
+
+`whole-repo invariants` (the merge-skew guard, #366) runs only on the
+`merge_group` commit and on `push:main`, never on a plain PR — so a
+green-in-isolation PR that would collide once merged (a duplicate migration
+prefix, a layout/artifact drift) is **blocked at merge time**, not after it has
+already reddened `main`. Grouping is `ALLGREEN` (SQUASH merge), so any red entry
+invalidates the whole batch. `Conventional PR title` passes through on
+`merge_group` (the title was validated when the PR entered the queue).
+
 ## Distributed fleet: NANO_WORKFORCE_BASE_URL
 
 The abandon and blackboard hooks are how a **distributed worker fleet** calls back

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.127.0](https://github.com/nanobpm/nano-workforce/compare/v0.126.0...v0.127.0) (2026-08-23)
+
+
+### Features
+
+* **tasks:** collapse Tasks page to one user_tasks list, complete via engine forms ([#461](https://github.com/nanobpm/nano-workforce/issues/461)) ([#484](https://github.com/nanobpm/nano-workforce/issues/484)) ([bbc0745](https://github.com/nanobpm/nano-workforce/commit/bbc0745ddc7b5f79cfee5096dfbd07cf29ea0f38)), closes [nano-ide#457](https://github.com/nano-ide/issues/457) [#445](https://github.com/nanobpm/nano-workforce/issues/445) [#458](https://github.com/nanobpm/nano-workforce/issues/458)
+
+# [0.126.0](https://github.com/nanobpm/nano-workforce/compare/v0.125.0...v0.126.0) (2026-08-23)
+
+
+### Features
+
+* **delivery-graphs:** preview a staged proposal's generated DI, zero deploy ([#469](https://github.com/nanobpm/nano-workforce/issues/469)) ([c275d72](https://github.com/nanobpm/nano-workforce/commit/c275d7279d8a46d1ca8ce82e366016ca7ef0a22f)), closes [Magikcraft/nano-bpm#972](https://github.com/Magikcraft/nano-bpm/issues/972)
+
 # [0.125.0](https://github.com/nanobpm/nano-workforce/compare/v0.124.0...v0.125.0) (2026-08-23)
 
 

package/app/agentCompletion.ts

@@ -122,6 +122,17 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   // (returns `null`) and the completer accepts the captured form variables for the emit binder to type.
 };
 
+/** The fixed `.form` linkage (a `zeebe:formDefinition formId`) that governs a fixed-form escalation
+ *  kind's completion, or `undefined` for a kind with no static form (the delivery-graph `human` node,
+ *  which renders DIFFERENT forms per node — its `formKey` only ever comes from the engine at runtime).
+ *  Exposed so the Tasks-inbox poller can denormalise a row's `form_key` from this SAME single source of
+ *  truth when the raw `/v2/user-tasks/search` result omits the engine-resolved key (issue #461) — the
+ *  REST gateway addresses a deployed form by value whether that value is a deploy key or an authored
+ *  form id, so this id resolves the same deployed `.form` the completer validates against. */
+export function escalationFormId(elementId: string): string | undefined {
+  return ESCALATION_FORM_BY_ELEMENT[elementId];
+}
+
 /** A field's `conditional.hide` rule, parsed from the FEEL subset the `.form` files use
  *  (`=<ref> != "<value>"` / `=<ref> == "<value>"`). A required field is only enforced when it is
  *  actually shown, so an "answer only when resolution=answer" field is not demanded on the abandon

package/app/agentic/vocab/demand-report.test.ts

@@ -9,7 +9,12 @@ import { CREW_VOCAB_VERSION } from "./crew-vocab.ts";
 import { buildRegistryReport, engineRestAddress, toWireReport } from "./demand-report.ts";
 
 const NOW = new Date(0);
-const leaf = (taskType: string): TaskDefinitionLeaf => ({ taskType, process: "p", elementId: taskType });
+// A demanded taskDefinition leaf. `agentic` is the structural signal the engine reads from a task's
+// `linkName="prompt"` side-car (agentic package >=0.4): true for an external agent task (its type is a
+// routing token matched against crew supply), false for a deterministic in-process host job (bucketed
+// as nonAgentic, out of the demand×supply accounting). Defaults to an agent task since most demand
+// here is agentic; the host-job cases pass `false` explicitly.
+const leaf = (taskType: string, agentic = true): TaskDefinitionLeaf => ({ taskType, process: "p", elementId: taskType, agentic });
 
 const plannerFrontier: RegisteredWorker = { instance: "w-front", capability: { cognition: "planning", weight: 5, family: "frontier" } };
 const plannerKimi: RegisteredWorker = { instance: "w-kimi", capability: { cognition: "planning", weight: 5, family: "kimi" } };
@@ -41,11 +46,14 @@ test("an agent job type with no enrolled senior worker is flagged missing, not n
   assertEquals(report.status, "red");
 });
 
-test("ordinary host jobs (pr.*) are not colon-form and pass through the bridge untouched", () => {
-  const report = buildRegistryReport({ taskDefinitions: [leaf("pr.finalize")], workers: [], now: NOW });
-  const pr = report.networks.find((n) => n.network === "pr");
-  assert(pr !== undefined, "pr.finalize stays a pr-network routing token");
-  assert(pr.tokens.some((t) => t.token === "pr.finalize"));
+test("ordinary host jobs (pr.*) are non-agentic (no prompt link) and excluded from demand×supply", () => {
+  // A deterministic in-process host job carries no `linkName="prompt"` side-car, so the engine reports
+  // it agentic:false and the model buckets it as nonAgentic — off the agentic demand board, never a
+  // false RED. The colon-form bridge still leaves its dot-form type untouched (it is not `<rank>:<task>`).
+  const report = buildRegistryReport({ taskDefinitions: [leaf("pr.finalize", false)], workers: [], now: NOW });
+  assert(report.nonAgentic.includes("pr.finalize"), "pr.finalize is a non-agentic host job");
+  assert(!report.networks.some((n) => n.network === "pr"), "and is not counted as agentic pr-network demand");
+  assertEquals(report.missing, []);
 });
 
 test("flags a demanded leaf with no supplier as missing (red) and a supplied leaf as satisfied", () => {
@@ -68,10 +76,15 @@ test("flags a demanded leaf with no supplier as missing (red) and a supplied lea
   assertEquals(report.demandUnavailable, false);
 });
 
-test("a deployed type that is not a valid routing token is surfaced as nonAgentic, not missing", () => {
-  const report = buildRegistryReport({ taskDefinitions: [leaf("weird token!")], workers: [], now: NOW });
-  assert(report.nonAgentic.includes("weird token!"));
-  assertEquals(report.missing, []);
+test("an agentic leaf whose type resolves to no crew role is a missing (red) gap, not silently dropped", () => {
+  // Under the structural model, nonAgentic means "no prompt link", NOT "unparseable/unknown token": an
+  // agent task (agentic:true) demanding a rank no crew role serves is a real RED supply gap the board
+  // must surface. `principal:*` is a new rank with no crew role — the #323 bridge derives `principal`,
+  // which resolves to no supply and trips this regression guard rather than being swept into nonAgentic.
+  const report = buildRegistryReport({ taskDefinitions: [leaf("principal:feature")], workers: [], now: NOW });
+  assert(report.missing.includes("principal"), "an unsuppliable agent rank is missing, not nonAgentic");
+  assertEquals(report.nonAgentic, []);
+  assertEquals(report.status, "red");
 });
 
 test("the diversity SLO reads the correlated supply — green for distinct-family spar seats", () => {

package/app/pollUserTasks.test.ts

@@ -55,7 +55,7 @@ function memData(seed: Record<string, any[]> = {}): { data: DataLayer; stores: R
 /** A single engine-reported user task in the fixture. `state` mirrors the engine lifecycle; it
  *  defaults to `"CREATED"` (the only open/answerable state) so existing fixtures read as live tasks.
  *  A looping instance holds multiple tasks for one element (COMPLETED from prior rounds + the live one). */
-type FakeTask = { userTaskKey: string; elementId?: string; state?: "CREATED" | "COMPLETED" | "CANCELED" };
+type FakeTask = { userTaskKey: string; elementId?: string; state?: "CREATED" | "COMPLETED" | "CANCELED"; formKey?: string };
 
 /** A fake engine whose user tasks are keyed by processInstanceKey (the only field the poller queries on
  *  for plan / PR instances). It models the real engine's two accessors from ONE fixture so a test
@@ -370,7 +370,7 @@ test("pollUserTasks: an instance whose only task is COMPLETED surfaces no row",
 
 /** A single task as the raw Camunda-8 `/v2/user-tasks/search` reports it — carries `processInstanceKey`
  *  (the typed seam omits it) so the sweep can map a task back to its subject for enrichment. */
-type RawTask = { userTaskKey: string; elementId?: string; processInstanceKey?: string; state?: string };
+type RawTask = { userTaskKey: string; elementId?: string; processInstanceKey?: string; state?: string; formKey?: string | number | null };
 
 /** Stub `globalThis.fetch` so `pollUserTasks`' engine-first sweep reads its open tasks from `tasks`.
  *  Honours the `page.from`/`page.limit` pagination the sweep drives, and 404s any other path so a stray
@@ -611,3 +611,67 @@ test("pollUserTasks (typed-seam fallback): projects an inlined delivery-human ta
   assertEquals(byKey["35002"].subject_key, "delivery-graph-403eb22e");
   assertEquals(byKey["35002"].subject_title, "release runbook");
 });
+
+// ── form_key denormalisation (issue #461) ─────────────────────────────────────────────────────────
+// The collapsed Tasks page renders ONE `user_tasks` grid and completes each heterogeneous row via its
+// ENGINE-declared form (nano-ide#457). That needs the task's engine `formKey` denormalised onto the
+// row so the grid can resolve the deployed `.form` per row. The poller derives it in the SAME canonical
+// path it derives `kind_label`: read `formKey` from the `/v2/user-tasks/search` result, falling back to
+// `ESCALATION_FORM_BY_ELEMENT` for the fixed-form kinds the search omits it for.
+
+test("pollUserTasks (engine-first): a delivery-graph escalation row is present in the single list AND carries its engine form_key (issue #461)", async () => {
+  // The regressed case: an armed delivery-graph run escalated (a bounded service node's timeout twin,
+  // dynamic id `delivery-human-task__<node>__esc`) — counted by the `filter: []` badge but rendered by no
+  // allowlisted grid. Under the single grid it must (a) surface and (b) be completable via its engine form,
+  // so its `formKey` (reported by the engine on the task) is denormalised onto the row.
+  const { data, stores } = memData({
+    delivery_graph_runs: [
+      { run_key: "delivery-graph-407178305d01", process_key: "dg-1", status: "running", title: "ship the release" },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "39354", elementId: "delivery-human-task__n1_task__esc", processInstanceKey: "dg-1", state: "CREATED", formKey: "form-esc-88" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["39354"]); // present in the single list
+  assertEquals(byKey["39354"].element_id, "delivery-human-task__n1_task__esc");
+  assertEquals(byKey["39354"].kind_label, "Delivery: human step");
+  assertEquals(byKey["39354"].form_key, "form-esc-88"); // completable via its engine-declared form
+});
+
+test("pollUserTasks (engine-first): a fixed-kind escalation whose search omits formKey derives form_key from its .form linkage (issue #461)", async () => {
+  // Fallback: the raw search can omit `formKey` for a task; a fixed-form kind's `.form` linkage is a
+  // static single source of truth (`ESCALATION_FORM_BY_ELEMENT`), so the row is still completable.
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-plan", elementId: "plan-review-decision", processInstanceKey: "pi-1", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(byKey["ut-plan"].form_key, "plan-review-decision");
+});
+
+test("pollUserTasks (typed-seam fallback): denormalises the engine form_key from the typed openUserTasks seam (issue #461)", async () => {
+  const { data, stores } = memData({
+    plans: [{ plan_key: "o/r#20", status: "dispatched", process_key: "pp-20", issue_url: null, title: "epic" }],
+  });
+  const engine = fakeEngine({
+    "pp-20": [{ userTaskKey: "ut-plan", elementId: "plan-review-decision", formKey: "form-77" }],
+  });
+
+  await pollUserTasks(data, engine); // no engineRest → typed-seam fallback
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(byKey["ut-plan"].form_key, "form-77");
+});

package/app/service.ts

@@ -10,6 +10,7 @@
 import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { ABANDONED_STATUS, abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
+import { escalationFormId } from "./agentCompletion.ts";
 import { agentSlaTimeout } from "./agentSla.ts";
 import {
   CAPS_RESOLVED_MESSAGE,
@@ -2186,6 +2187,10 @@ interface UserTaskSearchItem {
   elementId?: string;
   processInstanceKey?: string | number;
   state?: string;
+  /** The engine's resolution of the task's `.form` linkage (its `formId="X"`) to the deployed form's
+   *  key, attached to the open task. Denormalised onto the row so the collapsed Tasks grid can render
+   *  the deployed form per row (issue #461). The wire may send a JSON number or string. */
+  formKey?: string | number;
 }
 
 /** One discovered open escalation user task, normalised for projection. */
@@ -2193,6 +2198,9 @@ interface OpenUserTask {
   userTaskKey: string;
   elementId: string;
   processInstanceKey: string;
+  /** The engine-reported `formKey`, or "" when the search omitted it (the poller then falls back to the
+   *  kind's static `.form` linkage). */
+  formKey: string;
 }
 
 /** Engine-first sweep (issue #358): read EVERY open (`CREATED`) native user task from the engine over
@@ -2234,7 +2242,7 @@ async function sweepOpenEscalationTasks(base: string, headers: Record<string, st
       const userTaskKey = it.userTaskKey == null ? "" : String(it.userTaskKey);
       if (!userTaskKey || seen.has(userTaskKey)) continue;
       seen.add(userTaskKey);
-      out.push({ userTaskKey, elementId, processInstanceKey: it.processInstanceKey == null ? "" : String(it.processInstanceKey) });
+      out.push({ userTaskKey, elementId, processInstanceKey: it.processInstanceKey == null ? "" : String(it.processInstanceKey), formKey: it.formKey == null ? "" : String(it.formKey) });
     }
     if (items.length < limit) break; // last page
     from += items.length;
@@ -2379,7 +2387,7 @@ export async function pollUserTasks(
   // element + the instance it parks on) into its desired-row context, enriching from its subject row
   // when the instance is tracked or a per-kind fallback when it is orphaned. Returns `null` for a
   // non-escalation element (the leak guard) so an arbitrary internal user task can never reach the inbox.
-  const contextFor = async (elementId: string, userTaskKey: string, processInstanceKey: string): Promise<UserTaskContext | null> => {
+  const contextFor = async (elementId: string, userTaskKey: string, processInstanceKey: string, formKey: string): Promise<UserTaskContext | null> => {
     if (userTaskKindLabel(elementId) === undefined) return null;
     const subj = subjectByInstance.get(processInstanceKey);
     // Orphaned-task fallback: the kind implies its aggregate even when no subject row references the
@@ -2387,6 +2395,11 @@ export async function pollUserTasks(
     // derived from the predicate rather than the static per-element table.
     const subjectType = subj?.type ?? DEFAULT_SUBJECT_TYPE[elementId] ?? (isDeliveryHumanElement(elementId) ? "delivery" : "plan");
     const subjectKey = subj?.key ?? processInstanceKey;
+    // Denormalise the engine `formKey` so the collapsed Tasks grid renders the deployed `.form` per row
+    // (issue #461). Prefer the engine-resolved key the search reported; fall back to the fixed-form kind's
+    // static `.form` linkage (`escalationFormId`) when the search omitted it — the delivery-graph `human`
+    // node has no static form (varies per node), so it relies wholly on the engine-reported key.
+    const resolvedFormKey = formKey.trim() || escalationFormId(elementId) || null;
     let question: string | null = null;
     switch (elementId) {
       case FEATURE_ESCALATION_ELEMENT:
@@ -2412,17 +2425,17 @@ export async function pollUserTasks(
         question = conformanceEscalationQuestion(subj ? { summary: subj.conformanceSummary } : undefined);
         break;
     }
-    return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? null, question, processKey: processInstanceKey };
+    return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? null, question, processKey: processInstanceKey, formKey: resolvedFormKey };
   };
 
   // Desired set, deduped by completable key (a task is open at most once; guard a page overlap / a
   // subject seen under two statuses mid-pass).
   const desiredByKey = new Map<string, UserTaskRow>();
-  const project = async (elementId: string | undefined, userTaskKey: string, processInstanceKey: string) => {
+  const project = async (elementId: string | undefined, userTaskKey: string, processInstanceKey: string, formKey: string) => {
     if (!elementId) return;
     const rowKey = userTaskKey.trim();
     if (!rowKey || desiredByKey.has(rowKey)) return;
-    const ctx = await contextFor(elementId, userTaskKey, processInstanceKey);
+    const ctx = await contextFor(elementId, userTaskKey, processInstanceKey, formKey);
     if (!ctx) return;
     const row = buildUserTaskRow(ctx, at);
     if (row) desiredByKey.set(rowKey, row);
@@ -2433,7 +2446,7 @@ export async function pollUserTasks(
     const headers: Record<string, string> = { "content-type": "application/json" };
     if (engineRest.token) headers.authorization = `Bearer ${engineRest.token}`;
     for (const t of await sweepOpenEscalationTasks(base, headers)) {
-      await project(t.elementId, t.userTaskKey, t.processInstanceKey);
+      await project(t.elementId, t.userTaskKey, t.processInstanceKey, t.formKey);
     }
   } else {
     // Reduced-capability fallback (no raw-REST surface): typed-seam per-active-subject scan, tracked-only.
@@ -2441,14 +2454,14 @@ export async function pollUserTasks(
     const scanInstance = async (processKey: string | null | undefined) => {
       if (!processKey || seen.has(processKey)) return;
       seen.add(processKey);
-      let tasks: { userTaskKey: string; elementId?: string }[];
+      let tasks: { userTaskKey: string; elementId?: string; formKey?: string }[];
       try {
         tasks = await engine.openUserTasks({ processInstanceKey: processKey });
       } catch (err) {
         console.error(`[poller] user tasks (${processKey}): ${err}`);
         return;
       }
-      for (const t of tasks) await project(t.elementId, t.userTaskKey, processKey);
+      for (const t of tasks) await project(t.elementId, t.userTaskKey, processKey, t.formKey ?? "");
     };
     for (const status of FEATURE_ACTIVE_STATUSES) for (const run of await featureRuns(data).find({ status })) await scanInstance(run.process_key);
     for (const status of PLAN_ACTIVE_STATUSES) for (const plan of await plans(data).find({ status })) await scanInstance(plan.process_key);

package/app/tasksPage.test.ts

@@ -0,0 +1,44 @@
+// Structure guard for the collapsed Tasks page (issue #461). The Tasks page is ONE `user_tasks`
+// dataGrid (`filter: []`, `orderBy updated_at desc`) with `kind_label` as a "Type" column, completing
+// each row via its ENGINE-declared form (nano-ide#457's `detail.engineForm`) — not seven
+// `element_id`-allowlisted grids each with a hand-authored `detail.form` that duplicates a deployed
+// `.form` resource AND leaves dynamic-id delivery-graph tasks (counted by the `filter: []` badge)
+// rendered by no grid. This test pins that end-state so the anti-pattern can't creep back:
+//   • exactly one `dataGrid`, over `user_tasks`, unfiltered, recency-ordered → badge ≡ list;
+//   • a "Type" column bound to `kind_label`;
+//   • an engine-form detail (`form_key` / `user_task_key`), and NO page-local `detail.form`.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+
+// biome-ignore lint/suspicious/noExplicitAny: reading an untyped page manifest for structural assertions
+const page: any = JSON.parse(readFileSync(fileURLToPath(new URL("../pages/tasks.page.json", import.meta.url)), "utf8"));
+// biome-ignore lint/suspicious/noExplicitAny: see above
+const nodes: any[] = page.nodes ?? [];
+// biome-ignore lint/suspicious/noExplicitAny: see above
+const grids: any[] = nodes.filter((n) => n.type === "dataGrid");
+
+test("Tasks page is exactly ONE dataGrid over user_tasks (filter [], orderBy updated_at desc)", () => {
+  assertEquals(grids.length, 1);
+  const [grid] = grids;
+  assertEquals(grid.props.data.table, "user_tasks");
+  assertEquals(grid.props.data.filter, []);
+  assertEquals(grid.props.data.orderBy, { field: "updated_at", dir: "desc" });
+});
+
+test("Tasks grid surfaces kind_label as a 'Type' column", () => {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  const typeCol = grids[0].props.columns.find((c: any) => c.field === "kind_label");
+  assert(typeCol, "a kind_label column must exist");
+  assertEquals(typeCol.header, "Type");
+});
+
+test("Tasks grid completes each row via its engine-declared form (nano-ide#457), not a page-local detail.form", () => {
+  const { detail } = grids[0].props;
+  assert(detail?.engineForm, "the grid detail must opt into engineForm rendering");
+  assertEquals(detail.engineForm.formKeyField, "form_key");
+  assertEquals(detail.engineForm.userTaskKeyField, "user_task_key");
+  // The seven bespoke per-type detail.form blocks (each a copy of a deployed `.form`) are gone.
+  for (const g of grids) assert(!g.props.detail?.form, "no grid may carry a page-local detail.form");
+});

package/app/userTasks.test.ts

@@ -49,11 +49,30 @@ test("buildUserTaskRow: a plan-review task becomes a labelled row with its findi
     subject_url: "https://github.com/o/r/issues/1",
     question: "cap reached: revise scope",
     process_key: "pk-1",
+    form_key: null,
     created_at: AT,
     updated_at: AT,
   });
 });
 
+test("buildUserTaskRow: denormalises the engine form_key, trimming blanks to null (issue #461)", () => {
+  const withForm = buildUserTaskRow(
+    { userTaskKey: "ut-f", elementId: PLAN_REVIEW_ELEMENT, subjectType: "plan", subjectKey: "o/r#1", formKey: "  form-9  " },
+    AT,
+  );
+  assertEquals(withForm?.form_key, "form-9");
+  const blank = buildUserTaskRow(
+    { userTaskKey: "ut-b", elementId: PLAN_REVIEW_ELEMENT, subjectType: "plan", subjectKey: "o/r#1", formKey: "   " },
+    AT,
+  );
+  assertEquals(blank?.form_key, null);
+  const absent = buildUserTaskRow(
+    { userTaskKey: "ut-n", elementId: PLAN_REVIEW_ELEMENT, subjectType: "plan", subjectKey: "o/r#1" },
+    AT,
+  );
+  assertEquals(absent?.form_key, null);
+});
+
 test("buildUserTaskRow: a blank question / missing url normalises to null", () => {
   const row = buildUserTaskRow(
     { userTaskKey: "ut-2", elementId: TRIAL_MERGE_ELEMENT, subjectType: "plan", subjectKey: "o/r#2", question: "   " },

package/app/userTasks.ts

@@ -60,6 +60,11 @@ export interface UserTaskRow {
   subject_url: string | null;
   question: string | null;
   process_key: string | null;
+  /** The engine `formKey` of the parked user task's engine-declared form, denormalised so the single
+   *  collapsed Tasks grid can resolve and render the deployed `.form` per row (nano-ide#457). Derived in
+   *  the poller from the `/v2/user-tasks/search` result, falling back to the fixed-form kinds' static
+   *  `.form` linkage; NULL when neither resolves (the grid degrades to bare completion). */
+  form_key: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -103,6 +108,10 @@ export interface UserTaskContext {
   subjectUrl?: string | null;
   question?: string | null;
   processKey?: string | null;
+  /** The engine-resolved `formKey` of the task's engine-declared form, as the poller read it from the
+   *  `/v2/user-tasks/search` result (or the fixed-form fallback). Optional/blank tolerated —
+   *  `buildUserTaskRow` normalises a blank to NULL. */
+  formKey?: string | null;
 }
 
 /** Pure: turn one resolved open escalation task into its desired read-model row, or `null` when the
@@ -123,6 +132,7 @@ export function buildUserTaskRow(ctx: UserTaskContext, at: string = now()): User
   const subjectKey = ctx.subjectKey.trim() || (ctx.processKey ?? "").trim() || userTaskKey;
   const question = typeof ctx.question === "string" && ctx.question.trim() ? ctx.question.trim() : null;
   const subjectTitle = typeof ctx.subjectTitle === "string" && ctx.subjectTitle.trim() ? ctx.subjectTitle.trim() : subjectKey;
+  const formKey = typeof ctx.formKey === "string" && ctx.formKey.trim() ? ctx.formKey.trim() : null;
   return {
     user_task_key: userTaskKey,
     element_id: ctx.elementId,
@@ -133,6 +143,7 @@ export function buildUserTaskRow(ctx: UserTaskContext, at: string = now()): User
     subject_url: ctx.subjectUrl ?? null,
     question,
     process_key: ctx.processKey ?? null,
+    form_key: formKey,
     created_at: at,
     updated_at: at,
   };
@@ -158,7 +169,8 @@ function sameRow(a: UserTaskRow, b: UserTaskRow): boolean {
     a.subject_title === b.subject_title &&
     a.subject_url === b.subject_url &&
     a.question === b.question &&
-    a.process_key === b.process_key
+    a.process_key === b.process_key &&
+    a.form_key === b.form_key
   );
 }
 

package/db/migrations/077_user_tasks_form_key.sql

@@ -0,0 +1,25 @@
+-- Denormalise the engine `form_key` onto the unified Tasks-inbox read-model (issue #461) — additive,
+-- nullable. The collapsed Tasks page renders ONE `user_tasks` grid and completes each heterogeneous row
+-- via its ENGINE-declared form (nano-ide#457's `detail.engineForm`), instead of seven
+-- `element_id`-allowlisted grids each with a hand-authored `detail.form` copy of a deployed `.form`.
+-- Rendering the deployed form per row needs the task's engine `formKey` on the row, so the grid can
+-- resolve `GET /app/actions/form?formKey=<row.form_key>` — the SAME single source of truth
+-- `taskInbox` uses (no page-local field duplication).
+--
+-- Derived in the canonical poller path exactly as `kind_label` is (no drift surface): `pollUserTasks`
+-- (app/service.ts) reads the engine-resolved `formKey` from the Camunda `/v2/user-tasks/search` result
+-- and `buildUserTaskRow` (app/userTasks.ts) writes it, falling back to the fixed-form kinds' static
+-- `.form` linkage (`ESCALATION_FORM_BY_ELEMENT`, app/agentCompletion.ts) when the search omits it.
+-- NULL when neither resolves — the grid degrades to bare completion, matching `taskInbox`.
+--
+-- Forward-only, additive (expand): a new nullable column on an existing table, no shape rewrite and no
+-- backfill (the poller repopulates every open row on its next pass). Numbered after the current highest
+-- prefix (076); the runner wraps each file in its own transaction, so this file must NOT contain
+-- BEGIN/COMMIT.
+ALTER TABLE user_tasks ADD COLUMN form_key TEXT;
+
+-- The collapsed Tasks page reads `user_tasks` UNFILTERED ordered by `updated_at desc` (pages/tasks.page.json),
+-- an access pattern the existing composite indexes (`(element_id, updated_at)`, `(subject, element_id)`) can't
+-- serve — SQLite would scan + sort the whole table as the inbox grows. Front the unified inbox's sort with a
+-- single-column index on `updated_at`. Additive and idempotent.
+CREATE INDEX IF NOT EXISTS idx_user_tasks_updated ON user_tasks(updated_at);