@nanobpm/nano-workforce 0.171.1 → 0.171.3

package/app/userTaskInboxDriftGuard.test.ts

@@ -0,0 +1,102 @@
+// Drift guard for the Tasks-inbox closed sets (issue #674 — fix the class, not the bug).
+//
+// Root cause of #674: the readiness/preflight escalation user tasks (`readiness-escalation-pf`,
+// `readiness-escalation`) were deployed BPMN `<bpmn:userTask>`s with a linked `.form`, but their
+// element ids were never added to the app-tier closed sets that gate surfacing (`USER_TASK_KIND_LABELS`,
+// app/userTasks.ts) and completion (`HUMAN_COMPLETABLE_ELEMENTS` / `ESCALATION_FORM_BY_ELEMENT`,
+// app/agentCompletion.ts). The poller's leak guard (`userTaskKindLabel(id) === undefined`) silently
+// DROPPED every such task, so a parked run went invisible in the Tasks surface AND uncompletable
+// through the one canonical `complete-user-task` door.
+//
+// This test makes that drift structurally impossible: it enumerates EVERY human `<bpmn:userTask>`
+// (bearing a `<zeebe:userTask />`) in the deployed processes (`resources/processes/*.bpmn`) and asserts
+// each element id is a KNOWN Tasks-inbox kind, and — where it declares a static `zeebe:formDefinition`
+// form and is completable — that the completer's form contract resolves to the SAME `.form` the BPMN
+// declares. So a future BPMN user task can never again vanish from the inbox by being absent from the
+// hand-maintained closed set: the closed set's completeness is DERIVED from the deployed BPMN, not
+// asserted blind.
+//
+// On `main` (before #674's registration) this test FAILS on `readiness-escalation-pf` /
+// `readiness-escalation`; it passes once both are registered.
+import { readdirSync, readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { escalationFormId, HUMAN_COMPLETABLE_ELEMENTS } from "./agentCompletion.ts";
+import { isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { userTaskKindLabel } from "./userTasks.ts";
+
+const PROCESS_DIR = "resources/processes";
+
+/** Demo/fixture processes that are deployed for the engine-spine e2e (`e2e/user-task-spine.e2e.ts`)
+ *  but are NOT part of the workforce escalation surface — their user tasks are deliberately not
+ *  Tasks-inbox kinds. Kept as a tiny, explicitly-documented file allowlist (not a per-id one) so a new
+ *  REAL escalation process is still fully guarded. */
+const DEMO_PROCESS_FILES: ReadonlySet<string> = new Set(["spine-demo.bpmn"]);
+
+interface DeployedUserTask {
+  file: string;
+  elementId: string;
+  /** The `zeebe:formDefinition formId`, when the task declares a static form. */
+  formId: string | null;
+}
+
+/** Parse every human `<bpmn:userTask>` (one bearing a `<zeebe:userTask />`, i.e. a native user task an
+ *  operator answers — not a job-worker task) out of the deployed process BPMN. Text parsing, matching
+ *  the repo's lightweight model-guard style (convergenceEscalationGuard.test.ts et al.). */
+function deployedHumanUserTasks(): DeployedUserTask[] {
+  const out: DeployedUserTask[] = [];
+  for (const file of readdirSync(PROCESS_DIR).filter((f) => f.endsWith(".bpmn"))) {
+    if (DEMO_PROCESS_FILES.has(file)) continue;
+    const xml = readFileSync(`${PROCESS_DIR}/${file}`, "utf8");
+    for (const m of xml.matchAll(/<bpmn:userTask\b[^>]*\bid="([^"]+)"([\s\S]*?)<\/bpmn:userTask>/g)) {
+      const [, elementId, body] = m;
+      if (!/<zeebe:userTask\b/.test(body)) continue; // not a native human user task (no <zeebe:userTask/>)
+      const form = body.match(/<zeebe:formDefinition\b[^>]*\bformId="([^"]+)"/);
+      out.push({ file, elementId, formId: form ? form[1] : null });
+    }
+  }
+  return out;
+}
+
+test("drift guard: every deployed human user task is a known Tasks-inbox kind (issue #674)", () => {
+  const tasks = deployedHumanUserTasks();
+  // Sanity: the sweep actually found the deployed escalations (guards against a parser that silently
+  // matches nothing and vacuously passes).
+  assert(tasks.length > 0, `expected the process sweep to find the deployed user tasks, got ${tasks.length}`);
+  assert(
+    tasks.some((t) => t.elementId === "readiness-escalation-pf"),
+    "expected readiness-escalation-pf among the deployed user tasks",
+  );
+  assert(
+    tasks.some((t) => t.elementId === "readiness-escalation"),
+    "expected readiness-escalation among the deployed user tasks",
+  );
+
+  const unsurfaced = tasks.filter((t) => userTaskKindLabel(t.elementId) === undefined);
+  assertEquals(
+    unsurfaced.map((t) => `${t.file}:${t.elementId}`),
+    [],
+    "deployed user task(s) are not registered in USER_TASK_KIND_LABELS — pollUserTasks' leak guard would drop them from the Tasks inbox (issue #674)",
+  );
+});
+
+test("drift guard: every deployed fixed-form user task is human-completable through the canonical door (issue #674)", () => {
+  // The delivery-graph `human` node renders DIFFERENT forms per node (variable form, resolved at
+  // activation), so it is intentionally absent from the static `ESCALATION_FORM_BY_ELEMENT` contract —
+  // exclude it from the fixed-form assertion (it is still asserted to be a KNOWN kind above).
+  const fixedForm = deployedHumanUserTasks().filter((t) => t.formId && !isDeliveryHumanElement(t.elementId));
+
+  const notCompletable = fixedForm.filter((t) => !HUMAN_COMPLETABLE_ELEMENTS.has(t.elementId));
+  assertEquals(
+    notCompletable.map((t) => `${t.file}:${t.elementId}`),
+    [],
+    "deployed fixed-form user task(s) are not in HUMAN_COMPLETABLE_ELEMENTS — the canonical complete-user-task door would reject them",
+  );
+
+  const formMismatch = fixedForm.filter((t) => escalationFormId(t.elementId) !== t.formId);
+  assertEquals(
+    formMismatch.map((t) => `${t.file}:${t.elementId} bpmn=${t.formId} app=${escalationFormId(t.elementId) ?? "undefined"}`),
+    [],
+    "deployed user task(s) map to a different .form contract in ESCALATION_FORM_BY_ELEMENT than the BPMN declares",
+  );
+});

package/app/userTasks.ts

@@ -72,6 +72,24 @@ export const ACP_PERMISSION_ELEMENT = "acp-permission";
  *  escalation is filtered out by the unknown-kind guard and silently vanishes from the Tasks inbox. */
 export const HUMAN_ESCALATION_ELEMENT = "escalation";
 
+/** The readiness/preflight escalation user task parked when a LEADING readiness/capability PREFLIGHT
+ *  times out before its `ReadinessProbe` went green — a human decision (acknowledge/proceed vs abandon).
+ *  This is the `pf_*` embedded-subprocess variant that appears both in `feature.bpmn` (the feature-run
+ *  readiness preflight) and `plan-fanout.bpmn` (the producer-capability preflight). It parks on the
+ *  run's OWN engine instance (an embedded subprocess, not a callActivity child), renders the deployed
+ *  `readiness-escalation` `.form`, and is HUMAN-only: an agent must NOT auto-answer a readiness gate
+ *  (that would silently defeat the very "is upstream actually ready?" decision the gate exists to make),
+ *  so it lives in `HUMAN_COMPLETABLE_ELEMENTS`, never in `ESCALATION_TASK_ELEMENTS`. Without this the
+ *  task's kind is `undefined`, the poller's leak guard drops it, and the run wedges invisibly + unanswerably
+ *  (issue #674). */
+export const READINESS_ESCALATION_PF_ELEMENT = "readiness-escalation-pf";
+
+/** The readiness/wait-gate escalation user task (`readiness-gate.bpmn`, `wait-gate.bpmn`) — the same
+ *  human readiness decision on the standalone inter-epic wait-gate cell rather than the inline preflight.
+ *  Same `readiness-escalation` `.form`, same HUMAN-only policy as `READINESS_ESCALATION_PF_ELEMENT`
+ *  (issue #674). */
+export const READINESS_ESCALATION_ELEMENT = "readiness-escalation";
+
 /** 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. */
@@ -186,6 +204,8 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [PR_WAIT_ANSWER_ELEMENT]: "PR review",
   [PR_WAIT_MERGE_ANSWER_ELEMENT]: "PR merge",
   [CONFORMANCE_ESCALATION_ELEMENT]: "Conformance review",
+  [READINESS_ESCALATION_PF_ELEMENT]: "Upstream readiness stalled",
+  [READINESS_ESCALATION_ELEMENT]: "Readiness escalation",
   [DELIVERY_HUMAN_ELEMENT]: "Delivery: human step",
   [ACP_PERMISSION_ELEMENT]: "Agent permission",
 };
@@ -342,8 +362,21 @@ export function latestTrialMergeQuestion(audits: readonly TrialMergeAuditRow[]):
   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`. */
+/** Pure: the "what is the run waiting on" question line for a readiness/preflight escalation
+ *  (`readiness-escalation-pf` / `readiness-escalation`, issue #674) — the unresolved probe/capability
+ *  the leading readiness gate stalled on. The wait-gate projection already renders that clause on the
+ *  subject row: a plan gated behind a producer capability carries it on `plans.wait_gate_label`
+ *  ("waiting on <clause> · re-checks …", app/waitGate.ts), and a feature preflight carries its rollup
+ *  on `feature_runs.delivery_label`. Prefer whichever the subject supplies; fall back to a static
+ *  readiness-stalled line so the Tasks grid never renders a blank question for a parked gate.
+ *  Always returns a non-empty string — the static fallback guarantees a question is never blank. */
+export function readinessEscalationQuestion(label?: string | null): string {
+  const t = typeof label === "string" ? label.trim() : "";
+  return (
+    t ||
+    "The readiness preflight timed out before its ReadinessProbe went green. Proceed against the (now-published) upstream, or abandon the gate."
+  );
+}
 export interface PrEscalationRow {
   id: number;
   pr_key: string;

package/e2e/agent-answerable.e2e.ts

@@ -1,13 +1,14 @@
 // End-to-end proof for agent-answerable escalations (epic #156, slice U6; ADR 0046). Boots the whole
 // app against the WASM engine and drives the REAL plan-fanout.bpmn to the implementation-phase task
-// escalation — the native `feature-escalation` userTask + form the human path (U2) completes — then
+// escalation — the native `escalation` userTask (formId `feature-escalation`) on the `human-escalation`
+// grandchild the shared implement-cell spawns, which the human path (U2) completes — then
 // completes it through the HOST-SIDE AGENT COMPLETER (`completeEscalationAsAgent`) instead of a raw
 // human completion. It proves the three things U6 promises:
 //
 //   1. an AGENT assignee completing the SAME `.form` resumes the process with typed vars IDENTICAL to
 //      a human completion — asserted on the cumulative taken sequence flows: `{resolution:"answer"}`
-//      routes `w_gw_answer -> implement-task`, exactly as the U2 human test asserts (an empty/wrong
-//      completion would take the abandon default);
+//      routes `ic_gw_answer -> record-implementing -> implement-task`, exactly as the U2 human test
+//      asserts (an empty/wrong completion would take the abandon default);
 //   2. attribution is recorded — the `task_completions` ledger row is actor_kind=agent + the agent id
 //      + the submitted variables;
 //   3. the completion is reversible — a human reverts it, and the ledger records who + when.
@@ -111,7 +112,9 @@ describe("agent-answerable escalations (U6 — same form, agent completer, attri
   }
 
   async function openTask(app: TestApp, processKey: string, elementId: string): Promise<InboxTask> {
-    const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
+    // Root-scoped: after the ADR 0006 S4 composition the escalation user task parks on a
+    // `human-escalation` grandchild instance the shared `implement-cell` spawns, not on the parent.
+    const tasks = await app.engine.searchUserTasks({ rootProcessInstanceKey: processKey });
     const match = tasks.find((t) => t.elementId === elementId);
     assert.ok(match, `expected an open ${elementId} user task (open: ${tasks.map((t) => t.elementId).join(", ")})`);
     return match!;
@@ -134,8 +137,8 @@ describe("agent-answerable escalations (U6 — same form, agent completer, attri
         },
       },
       async ({ app, processKey }) => {
-        const task = await openTask(app, processKey, "feature-escalation");
-        assert.ok(task.userTaskKey, "the feature escalation carries a completable userTaskKey");
+        const task = await openTask(app, processKey, "escalation");
+        assert.ok(task.userTaskKey, "the human-escalation cell task carries a completable userTaskKey");
 
         // Complete AS AN AGENT through the host-side completer — the same typed `{resolution, answer}`
         // a human submits through the inbox, only the caller differs.
@@ -145,18 +148,18 @@ describe("agent-answerable escalations (U6 — same form, agent completer, attri
           variables: { resolution: "answer", answer: "use v2" },
         });
         assert.equal(r.ok, true, "the agent completer accepted the escalation completion");
-        assert.equal(r.elementId, "feature-escalation");
+        assert.equal(r.elementId, "escalation");
         await app.settle();
 
         // IDENTICAL resume to the human path (mirrors U2's human test): the typed resolution loops
-        // the child back to re-dispatch the SAME task — NOT the abandon default.
+        // the cell back to re-dispatch the SAME task through its implementing-reset — NOT the abandon default.
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("w_gw_answer->implement-task"),
-          `agent answer routed back to implement-task (flows: ${flows.join(", ")})`,
+          flows.includes("ic_gw_answer->record-implementing") && flows.includes("record-implementing->implement-task"),
+          `agent answer routed back to implement-task through the cell reset (flows: ${flows.join(", ")})`,
         );
         assert.ok(
-          !flows.includes("w_gw_answer->w_end"),
+          !flows.includes("ic_gw_answer->ic_end"),
           "the abandon (default) flow was NOT taken",
         );
 
@@ -168,7 +171,7 @@ describe("agent-answerable escalations (U6 — same form, agent completer, attri
         const row = completions[0];
         assert.equal(row.actor_kind, "agent");
         assert.equal(row.actor_id, "senior:answer-bot");
-        assert.equal(row.element_id, "feature-escalation");
+        assert.equal(row.element_id, "escalation");
         assert.deepEqual(JSON.parse(row.variables_json), { resolution: "answer", answer: "use v2" });
         assert.equal(row.reversible, 1, "an agent completion is reversible");
         assert.equal(row.reverted, 0);

package/e2e/feature-preflight.e2e.ts

@@ -158,8 +158,9 @@ describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)"
       );
       assert.ok(
         flows.includes("ensure-base-branch->record-feature-implementing") &&
-          flows.includes("record-feature-implementing->implement-task"),
-        `the run reaches the implement agent only after the gate (flows: ${flows.join(", ")})`,
+          flows.includes("record-feature-implementing->implement") &&
+          flows.includes("Start->implement-task"),
+        `the run reaches the implement agent (via the implement cell) only after the gate (flows: ${flows.join(", ")})`,
       );
       // A green probe never escalates.
       const tasks = await app.engine.searchUserTasks({ processInstanceKey });
@@ -190,8 +191,9 @@ describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)"
       );
       assert.ok(!flows.includes("gw-readiness->readiness-preflight"), "an ungated feature never enters the preflight");
       assert.ok(
-        flows.includes("record-feature-implementing->implement-task"),
-        "an ungated feature reaches the implement agent",
+        flows.includes("record-feature-implementing->implement") &&
+          flows.includes("Start->implement-task"),
+        "an ungated feature reaches the implement agent (via the implement cell)",
       );
     } finally {
       await app.stop();

package/e2e/feature-run.e2e.ts

@@ -3,8 +3,9 @@
 //   • raise-only — the agent opens a PR, `converge` is off → the run ends at `opened`, no hand-off;
 //   • raise + converge — with `converge` on, the opened PR is enrolled into the convergence loop
 //     (a `pull_requests` row appears) and the feature_run lands `converging`;
-//   • escalate + resume — the agent escalates, a native `feature-escalation` user task parks the
-//     run, and answering re-dispatches the SAME implement task (mirrors the epic slice).
+//   • escalate + resume — the agent escalates, the shared implement-cell spawns a `human-escalation`
+//     grandchild whose native `escalation` user task parks the run, and answering re-dispatches the
+//     SAME implement task inside the cell (mirrors the epic slice).
 //
 // The gateway assertions are the falsifiable core: the WASM engine folds a completed instance's
 // variables away, so we assert on the cumulative taken sequence flows (an empty/wrong result takes a
@@ -236,23 +237,26 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
       },
       { baseBranch: "epic/e2e" },
       async ({ app, processKey }) => {
-        const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
-        const task = tasks.find((t) => t.elementId === "feature-escalation") as InboxTask | undefined;
-        assert.ok(task?.userTaskKey, "the feature escalation parked a completable native user task");
+        // The escalation user task now lives on a `human-escalation` grandchild instance the shared
+        // `implement-cell` spawns (ADR 0006 S4), so it is found root-scoped, by the cell's `escalation`
+        // element — not `feature-escalation` on the parent (that inline task no longer exists).
+        const tasks = await app.engine.searchUserTasks({ rootProcessInstanceKey: processKey });
+        const task = tasks.find((t) => t.elementId === "escalation") as InboxTask | undefined;
+        assert.ok(task?.userTaskKey, "the human-escalation cell parked a completable native user task on a child instance");
 
         await app.engine.completeUserTask(task!.userTaskKey, { resolution: "answer", answer: "use v2" });
         await app.settle();
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("w_gw_answer->record-feature-implementing"),
-          `answer re-dispatched through the implementing-reset task (flows: ${flows.join(", ")})`,
+          flows.includes("ic_gw_answer->record-implementing"),
+          `answer re-dispatched through the cell's implementing-reset task (flows: ${flows.join(", ")})`,
         );
         assert.ok(
-          flows.includes("record-feature-implementing->implement-task"),
-          `the reset task re-enters the same implement task (flows: ${flows.join(", ")})`,
+          flows.includes("record-implementing->implement-task"),
+          `the reset task re-enters the same implement task inside the cell (flows: ${flows.join(", ")})`,
         );
-        assert.ok(!flows.includes("w_gw_answer->record-feature"), "the abandon (default) flow was NOT taken");
+        assert.ok(!flows.includes("ic_gw_answer->ic_end"), "the abandon (default) flow was NOT taken");
         assert.equal(calls, 2, "the implementation agent was re-dispatched exactly once after the answer");
       },
     );
@@ -289,9 +293,9 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
       assert.equal(parked.status, "escalated", "the run parks at escalated while awaiting the answer");
       assert.ok(parked.process_key, "the parked run carries its engine process-instance key");
 
-      const tasks = await app.engine.searchUserTasks({ processInstanceKey: parked.process_key! });
-      const task = tasks.find((t) => t.elementId === "feature-escalation") as InboxTask | undefined;
-      assert.ok(task?.userTaskKey, "the feature escalation parked a completable native user task");
+      const tasks = await app.engine.searchUserTasks({ rootProcessInstanceKey: parked.process_key! });
+      const task = tasks.find((t) => t.elementId === "escalation") as InboxTask | undefined;
+      assert.ok(task?.userTaskKey, "the human-escalation cell parked a completable native user task on a child instance");
 
       await app.engine.completeUserTask(task!.userTaskKey, { resolution: "answer", answer: "use v2" });
       await app.settle();
@@ -315,19 +319,24 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
       },
       { baseBranch: "epic/e2e" },
       async ({ app, processKey }) => {
-        const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
-        const task = tasks.find((t) => t.elementId === "feature-escalation") as InboxTask | undefined;
-        assert.ok(task?.userTaskKey, "the feature escalation parked a completable native user task");
+        const tasks = await app.engine.searchUserTasks({ rootProcessInstanceKey: processKey });
+        const task = tasks.find((t) => t.elementId === "escalation") as InboxTask | undefined;
+        assert.ok(task?.userTaskKey, "the human-escalation cell parked a completable native user task on a child instance");
 
         await app.engine.completeUserTask(task!.userTaskKey, { resolution: "abandon" });
         await app.settle();
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("w_gw_answer->record-feature"),
-          `abandon routed to record-feature (flows: ${flows.join(", ")})`,
+          flows.includes("ic_gw_answer->ic_end"),
+          `abandon took the cell's default abandon flow to the task-done end (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(!flows.includes("ic_gw_answer->record-implementing"), "the answer loop was NOT taken");
+        // The abandoned cell completes and the parent routes to its terminal recorder exactly once.
+        assert.ok(
+          flows.includes("implement->record-feature"),
+          `the completed cell routes the parent to record-feature (flows: ${flows.join(", ")})`,
         );
-        assert.ok(!flows.includes("w_gw_answer->record-feature-implementing"), "the answer loop was NOT taken");
       },
     );
   });
@@ -345,16 +354,19 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
       },
       { baseBranch: "epic/e2e" },
       async ({ app, featureKey, processKey }) => {
-        // The `record-feature-escalation` service task runs on the escalated arm (before the user task),
+        // The cell's `record-escalation` service task runs on the escalated arm (before the human task),
         // so the row already carries the flipped status when the run parks, and the agent's question is
         // recorded in the `feature_escalations` audit log the poller reads (issue #332 dropped the
         // denormalised `feature_runs.escalation_question` column).
         const parked = await featureRow(app, featureKey);
         assert.equal(parked.status, "escalated", "the escalated status is surfaced on the read model");
 
-        const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
-        const task = tasks.find((t) => t.elementId === "feature-escalation") as InboxTask | undefined;
-        assert.ok(task?.userTaskKey, "the feature escalation parked a completable native user task");
+        // The escalation parks on a `human-escalation` grandchild instance (ADR 0006 S4), so it is found
+        // root-scoped, by the cell's `escalation` element — the reduced-path poller correlates that
+        // grandchild task back to the feature subject via its rootProcessInstanceKey (real child execution).
+        const tasks = await app.engine.searchUserTasks({ rootProcessInstanceKey: processKey });
+        const task = tasks.find((t) => t.elementId === "escalation") as InboxTask | undefined;
+        assert.ok(task?.userTaskKey, "the human-escalation cell parked a completable native user task on a child instance");
 
         // The poller projects the parked task onto the Tasks inbox `user_tasks` read-model by reading
         // the engine directly, sourcing the question from the `feature_escalations` audit log.
@@ -376,9 +388,9 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("w_gw_answer->record-feature-implementing") &&
-            flows.includes("record-feature-implementing->implement-task"),
-          `the answer re-dispatched the same implement task through the reset (flows: ${flows.join(", ")})`,
+          flows.includes("ic_gw_answer->record-implementing") &&
+            flows.includes("record-implementing->implement-task"),
+          `the answer re-dispatched the same implement task through the cell's reset (flows: ${flows.join(", ")})`,
         );
         assert.equal(calls, 2, "the implementation agent was re-dispatched exactly once after the answer");
 

package/e2e/plan-fanout-sla.e2e.ts

@@ -108,7 +108,10 @@ describe("plan-fanout escalation SLA + assignment (U5)", () => {
   }
 
   async function openTask(app: TestApp, processKey: string, elementId: string): Promise<InboxTask> {
-    const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
+    // Root-scoped: the implement-stage escalation now parks on a `human-escalation` grandchild the
+    // shared `implement-cell` spawns (ADR 0006 S4); plan-level tasks (plan-review, trial-merge) still
+    // park on the root instance and remain discoverable under a root-scoped search (superset).
+    const tasks = await app.engine.searchUserTasks({ rootProcessInstanceKey: processKey });
     const match = tasks.find((t) => t.elementId === elementId);
     assert.ok(match, `expected an open ${elementId} user task (open: ${tasks.map((t) => t.elementId).join(", ")})`);
     return match!;
@@ -118,7 +121,7 @@ describe("plan-fanout escalation SLA + assignment (U5)", () => {
    *  filter) and NOT by a bogus group — proving `zeebe:assignmentDefinition candidateGroups` took. */
   async function assertAssignmentFilterable(app: TestApp, processKey: string, elementId: string) {
     const byOperators = await app.engine.searchUserTasks({
-      processInstanceKey: processKey,
+      rootProcessInstanceKey: processKey,
       candidateGroup: "operators",
     });
     assert.ok(
@@ -126,7 +129,7 @@ describe("plan-fanout escalation SLA + assignment (U5)", () => {
       `${elementId} is filterable by the operators candidate group`,
     );
     const byBogus = await app.engine.searchUserTasks({
-      processInstanceKey: processKey,
+      rootProcessInstanceKey: processKey,
       candidateGroup: "nobody-here",
     });
     assert.ok(
@@ -150,20 +153,21 @@ describe("plan-fanout escalation SLA + assignment (U5)", () => {
         }),
       },
       async ({ app, processKey }) => {
-        await openTask(app, processKey, "feature-escalation");
-        await assertAssignmentFilterable(app, processKey, "feature-escalation");
+        await openTask(app, processKey, "escalation");
+        await assertAssignmentFilterable(app, processKey, "escalation");
 
-        // Never answer — let the SLA elapse. The interrupting boundary cancels the parked task and
-        // routes to the task-done end (the safe auto-abandon default).
+        // Never answer — let the SLA elapse. The interrupting boundary (on the human-escalation cell's
+        // `escalation` task) cancels the parked task and routes to its SLA auto-abandon end; the cell
+        // then takes its abandon default (the safe auto-abandon of the slice).
         await advancePastTimer(app, PAST_SLA_MS);
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("be_feature_sla->w_end"),
-          `the SLA boundary auto-abandoned to the task-done end (flows: ${flows.join(", ")})`,
+          flows.includes("be_he_sla->he_end_sla"),
+          `the SLA boundary auto-abandoned to the human-escalation cell's SLA end (flows: ${flows.join(", ")})`,
         );
         assert.ok(
-          !flows.includes("w_gw_answer->implement-task"),
+          !flows.includes("ic_gw_answer->record-implementing"),
           "the human answer loop was NOT taken",
         );
       },

package/e2e/plan-fanout.e2e.ts

@@ -106,7 +106,11 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
   }
 
   async function openTask(app: TestApp, processKey: string, elementId: string): Promise<InboxTask> {
-    const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
+    // Root-scoped: the implement-stage escalation now parks on a `human-escalation` grandchild the
+    // shared `implement-cell` spawns (ADR 0006 S4); plan-level tasks (plan-review, empty-plan,
+    // trial-merge, the caps-timeout `feature-escalation`) still park on the root and remain
+    // discoverable under a root-scoped search (a superset of the parent's own tasks).
+    const tasks = await app.engine.searchUserTasks({ rootProcessInstanceKey: processKey });
     const match = tasks.find((t) => t.elementId === elementId);
     assert.ok(match, `expected an open ${elementId} user task (open: ${tasks.map((t) => t.elementId).join(", ")})`);
     return match!;
@@ -131,20 +135,20 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
         },
       },
       async ({ app, processKey }) => {
-        const task = await openTask(app, processKey, "feature-escalation");
-        assert.ok(task.userTaskKey, "the feature escalation carries a completable userTaskKey");
+        const task = await openTask(app, processKey, "escalation");
+        assert.ok(task.userTaskKey, "the human-escalation cell task carries a completable userTaskKey");
 
-        // Answer it: the typed resolution loops the child back to re-dispatch the SAME task.
+        // Answer it: the typed resolution loops the cell back to re-dispatch the SAME task.
         await app.engine.completeUserTask(task.userTaskKey, { resolution: "answer", answer: "use v2" });
         await app.settle();
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("w_gw_answer->implement-task"),
-          `answer routed back to implement-task (flows: ${flows.join(", ")})`,
+          flows.includes("ic_gw_answer->record-implementing") && flows.includes("record-implementing->implement-task"),
+          `answer routed back to implement-task through the cell reset (flows: ${flows.join(", ")})`,
         );
         assert.ok(
-          !flows.includes("w_gw_answer->w_end"),
+          !flows.includes("ic_gw_answer->ic_end"),
           "the abandon (default) flow was NOT taken",
         );
       },
@@ -163,17 +167,17 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
         }),
       },
       async ({ app, processKey }) => {
-        const task = await openTask(app, processKey, "feature-escalation");
+        const task = await openTask(app, processKey, "escalation");
         await app.engine.completeUserTask(task.userTaskKey, { resolution: "abandon" });
         await app.settle();
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("w_gw_answer->w_end"),
-          `abandon routed to the task-done end (flows: ${flows.join(", ")})`,
+          flows.includes("ic_gw_answer->ic_end"),
+          `abandon routed to the cell's task-done end (flows: ${flows.join(", ")})`,
         );
         assert.ok(
-          !flows.includes("w_gw_answer->implement-task"),
+          !flows.includes("ic_gw_answer->record-implementing"),
           "the answer loop was NOT taken",
         );
       },
@@ -454,7 +458,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
           `task with needs routed through the barrier gateway to wait-caps-resolved (flows: ${parked.join(", ")})`,
         );
         assert.ok(
-          !parked.includes("w_gw_needs->implement-task"),
+          !parked.includes("w_gw_needs->implement-cell-call"),
           "the no-needs shortcut was NOT taken for a task that declares needs",
         );
         assert.equal(featureBrief, undefined, "the agent has not been dispatched while parked at the barrier");
@@ -471,8 +475,8 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("wait-caps-resolved->implement-task"),
-          `caps-resolved released the barrier into implement-task (flows: ${flows.join(", ")})`,
+          flows.includes("wait-caps-resolved->implement-cell-call") && flows.includes("Start->implement-task"),
+          `caps-resolved released the barrier into the implement cell (flows: ${flows.join(", ")})`,
         );
         assert.equal(
           featureBrief,
@@ -534,15 +538,16 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
           `the caps bound escalated the parked task to the operator (flows: ${flows.join(", ")})`,
         );
         assert.ok(
-          !flows.includes("wait-caps-resolved->implement-task"),
+          !flows.includes("wait-caps-resolved->implement-cell-call"),
           "the resolve arm was withdrawn — the token did not also proceed as if resolved",
         );
         assert.equal(featureRan, false, "the agent was NOT dispatched — the unresolved task escalated instead");
 
-        // The escalation is a genuine, operable operator decision point: answering it loops the
-        // child back to re-dispatch the task (the operator having unblocked/decided), exactly like an
-        // agent-raised escalation — proving this is a real bounded wait + operator escalation, not a
-        // dead end.
+        // The escalation is a genuine, operable operator decision point: answering it releases the
+        // caps barrier into the implement cell (the operator having unblocked/decided), proving this is
+        // a real bounded wait + operator escalation, not a dead end. This is the plan-fanout's OWN
+        // caps-timeout `feature-escalation` task (the fan-out-specific barrier is surrounding
+        // orchestration, retained per ADR 0006 S4), distinct from the implement cell's `escalation`.
         const task = await openTask(app, processKey, "feature-escalation");
         assert.ok(task.userTaskKey, "the caps-timeout escalation carries a completable userTaskKey");
         await app.engine.completeUserTask(task.userTaskKey, { resolution: "answer", answer: "shipped it manually" });
@@ -550,8 +555,8 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
 
         const answered = takenFlows(app);
         assert.ok(
-          answered.includes("w_gw_answer->implement-task"),
-          `answering the caps escalation routed back to implement-task (flows: ${answered.join(", ")})`,
+          answered.includes("w_gw_answer->implement-cell-call") && answered.includes("Start->implement-task"),
+          `answering the caps escalation released the barrier into the implement cell (flows: ${answered.join(", ")})`,
         );
         assert.equal(featureRan, true, "the agent was dispatched once the operator answered the caps escalation");
       },

package/nano.app.json

@@ -172,10 +172,6 @@
       "taskType": "pr.record-wave",
       "handler": "workers/record-wave/worker.ts"
     },
-    {
-      "taskType": "pr.record-wave-escalation",
-      "handler": "workers/record-wave-escalation/worker.ts"
-    },
     {
       "taskType": "pr.record-feature",
       "handler": "workers/record-feature/worker.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.171.1",
+  "version": "0.171.3",
   "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",
@@ -63,12 +63,12 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.10.0",
-    "@nanobpm/urban": "^0.88.1",
+    "@nanobpm/urban": "^0.90.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^1.0.1",
+    "@nanobpm/urban-testkit": "^1.2.0",
     "@nanobpm/workflow": "^0.14.0",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.0",