@nanobpm/nano-workforce 0.167.4 → 0.168.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.168.0](https://github.com/nanobpm/nano-workforce/compare/v0.167.4...v0.168.0) (2026-08-31)
+
+### Features
+
+* correlate callActivity child-cell escalations & epic phase via parent/root keys ([#633](https://github.com/nanobpm/nano-workforce/issues/633)) ([#657](https://github.com/nanobpm/nano-workforce/issues/657)) ([22b8674](https://github.com/nanobpm/nano-workforce/commit/22b86746548627921a1bc049b7999eeaa8fb5104)), closes [Magikcraft/nano-bpm#977](https://github.com/Magikcraft/nano-bpm/issues/977) [#464](https://github.com/nanobpm/nano-workforce/issues/464) [#591](https://github.com/nanobpm/nano-workforce/issues/591)
+
 ## [0.167.4](https://github.com/nanobpm/nano-workforce/compare/v0.167.3...v0.167.4) (2026-08-31)
 
 ### Build System

package/app/agentCompletion.ts

@@ -68,6 +68,8 @@ export const taskCompletions = (data: DataLayer) =>
  *  agent path is scoped to escalations — it can never complete an arbitrary internal user task. */
 export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
   "feature-escalation",
+  "escalation", // shared human-escalation cell (human-escalation.bpmn, ADR 0006 S4 #603/#633) — the same
+  //              agent-answerable feature-escalation task, relocated into a callActivity child cell
   "plan-review-decision",
   "trial-merge-decision",
   "wait-answer", // PR review-loop escalation (convergence-loop.bpmn, U3)
@@ -121,6 +123,7 @@ export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
  *  validates against the SAME `.form` the task inbox renders — one contract, no second field list. */
 const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "feature-escalation": "feature-escalation",
+  "escalation": "feature-escalation", // shared human-escalation cell renders the SAME feature-escalation form (#603/#633)
   "plan-review-decision": "plan-review-decision",
   "trial-merge-decision": "trial-merge-decision",
   "wait-answer": "pr-escalation",

package/app/pollEpicPhase.test.ts

@@ -157,3 +157,67 @@ test("pollEpicPhase skips a live epic that has no engine instance yet", async ()
     assertEquals(called, false);
   });
 });
+
+/** Stub `globalThis.fetch` so `pollEpicPhase`'s callActivity hierarchy walk (issue #633) reads its
+ *  descendant instances from `childrenByParent` (keyed on the queried `parentProcessInstanceKey`), and
+ *  404s any other path so a stray call is loud. Returns a restore fn. */
+function stubProcessInstanceSearch(childrenByParent: Record<string, string[]>): () => void {
+  const orig = globalThis.fetch;
+  // biome-ignore lint/suspicious/noExplicitAny: minimal fetch double for the raw-REST search surface
+  globalThis.fetch = (async (url: string | URL, init?: any) => {
+    const u = String(url);
+    if (!u.endsWith("/process-instances/search")) return new Response("not found", { status: 404 });
+    const body = JSON.parse(init?.body ?? "{}");
+    const parent: string = body?.filter?.parentProcessInstanceKey ?? "";
+    const items = (childrenByParent[parent] ?? []).map((k) => ({ processInstanceKey: k }));
+    return new Response(JSON.stringify({ items }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as typeof fetch;
+  return () => {
+    globalThis.fetch = orig;
+  };
+}
+
+test("pollEpicPhase derives from an element INSIDE a callActivity CHILD cell via parent/root traversal (issue #633)", async () => {
+  // ADR 0006 S4 (#603/#633): once a wave/slice runs as a callActivity CHILD cell, the furthest-reached
+  // live token can sit INSIDE that child instance ("child-pi"), not on the parent plan-fanout spine
+  // ("pi-1"). The parent instance shows only a settled (COMPLETED) `record-plan`, so a parent-ONLY read
+  // would leave the phase at PLANNING; walking the hierarchy (parent → child) surfaces the child's ACTIVE
+  // `review-plan`, advancing the phase to Reviewing. The pure `deriveEpicPhaseLive` is unchanged — only
+  // its INPUT is widened to the whole instance hierarchy.
+  await withData(async (data) => {
+    await seedPlan(data, { epic_phase: EPIC_PHASE.PLANNING });
+    const engine = {
+      searchElementInstances: async ({ processInstanceKey }: { processInstanceKey: string }) =>
+        processInstanceKey === "child-pi"
+          ? [{ elementInstanceKey: "c1", processInstanceKey: "child-pi", elementId: "review-plan", state: "ACTIVE" }]
+          : [{ elementInstanceKey: "e1", processInstanceKey: "pi-1", elementId: "record-plan", state: "COMPLETED" }],
+    };
+    const restore = stubProcessInstanceSearch({ "pi-1": ["child-pi"], "child-pi": [] });
+    try {
+      await pollEpicPhase(data, engine as never, { restAddress: "http://engine.test/v2" });
+    } finally {
+      restore();
+    }
+    assertEquals((await plans(data).get("owner/repo#7"))?.epic_phase, EPIC_PHASE.REVIEWING);
+  });
+});
+
+test("pollEpicPhase without a raw-REST surface reads the parent instance ALONE (no traversal, pre-#633 behaviour)", async () => {
+  // The typed seam cannot enumerate children, so with no `engineRest` the walk degrades to the parent
+  // plan-fanout instance only — a child-cell token is invisible and the phase stays at PLANNING. This
+  // pins the two-arg (no-REST) call the unit path and degraded hosts use.
+  await withData(async (data) => {
+    await seedPlan(data, { epic_phase: EPIC_PHASE.PLANNING });
+    const engine = {
+      searchElementInstances: async ({ processInstanceKey }: { processInstanceKey: string }) =>
+        processInstanceKey === "child-pi"
+          ? [{ elementInstanceKey: "c1", processInstanceKey: "child-pi", elementId: "review-plan", state: "ACTIVE" }]
+          : [{ elementInstanceKey: "e1", processInstanceKey: "pi-1", elementId: "record-plan", state: "COMPLETED" }],
+    };
+    await pollEpicPhase(data, engine as never);
+    assertEquals((await plans(data).get("owner/repo#7"))?.epic_phase, EPIC_PHASE.PLANNING);
+  });
+});

package/app/pollUserTasks.test.ts

@@ -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; formKey?: string | number | null };
+type RawTask = { userTaskKey: string; elementId?: string; processInstanceKey?: string; rootProcessInstanceKey?: string | number | null; 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
@@ -444,7 +444,6 @@ test("pollUserTasks (engine-first): orphaned plan-review and PR-wait escalations
 });
 
 test("pollUserTasks (engine-first): a TRACKED task is still fully enriched from its subject row (no regression)", async () => {
-  // Enrich, don't gate: when a subject row DOES reference the task's instance, title/url/question come
   // from it exactly as the per-subject scan produced — the sweep maps by `processInstanceKey`.
   const { data, stores } = memData({
     feature_runs: [
@@ -479,6 +478,40 @@ test("pollUserTasks (engine-first): a TRACKED task is still fully enriched from
   assertEquals(byKey["ut-plan"].question, "scope too broad");
 });
 
+test("pollUserTasks (engine-first): a child-cell escalation correlates to its PARENT run via rootProcessInstanceKey (issue #633)", async () => {
+  // ADR 0006 S4 (#603/#633): once a slice's implement step runs as a callActivity CHILD cell, the
+  // agent-stuck escalation parks on the shared `human-escalation` cell's `escalation` element inside a
+  // CHILD instance ("child-pi") whose key NO subject row tracks — the owning feature run is tracked under
+  // the PARENT/root instance ("fp-10") the engine reports as `rootProcessInstanceKey`. The poller must
+  // correlate the child-instance task back to the parent run (subject + question + kind), not strand it
+  // as an orphan keyed to the raw child instance.
+  const { data, stores } = memData({
+    feature_runs: [
+      { feature_key: "o/r#10", status: "escalated", process_key: "fp-10", issue_url: "https://github.com/o/r/issues/10", title: "Add the framework selector", delivery_label: null },
+    ],
+    feature_escalations: [
+      { id: 1, feature_key: "o/r#10", question: "which framework?", created_at: "2025-01-01T00:00:00.000Z", job_key: "j1" },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-child", elementId: "escalation", processInstanceKey: "child-pi", rootProcessInstanceKey: "fp-10", 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(Object.keys(byKey), ["ut-child"]);
+  assertEquals(byKey["ut-child"].element_id, "escalation");
+  assertEquals(byKey["ut-child"].kind_label, "Feature escalation");
+  assertEquals(byKey["ut-child"].subject_type, "feature");
+  assertEquals(byKey["ut-child"].subject_key, "o/r#10"); // correlated to the PARENT run, not the child instance
+  assertEquals(byKey["ut-child"].subject_title, "Add the framework selector");
+  assertEquals(byKey["ut-child"].question, "which framework?"); // same feature_escalations log via the parent subject
+});
+
 test("pollUserTasks (engine-first): never leaks a non-escalation element nor a non-CREATED task", async () => {
   // The `USER_TASK_KIND_LABELS` gate keeps an arbitrary internal user task out of the inbox, and the
   // defensive state re-filter drops a lagging COMPLETED/CANCELED read (a dead affordance, #294) even if
@@ -825,6 +858,47 @@ test("pollUserTasks (engine-first): does NOT heal a JUST-escalated run inside th
   assertEquals(byKey["o/r#old"].status, "running", "a genuinely-stranded (old) run is still healed");
 });
 
+test("pollUserTasks (engine-first): does NOT heal an escalated run parked in a callActivity CHILD instance the sweep missed (issue #633)", async () => {
+  // A run's escalation can park inside a callActivity CHILD instance on the shared `human-escalation`
+  // cell's `escalation` element (ADR 0006 S4, #633), correlated back to the parent run via the root key.
+  // When this pass's engine-first sweep is truncated/unavailable, that child task is absent from `desired`,
+  // so the run falls through to the per-instance confirmation. Confirming ONLY the parent `process_key`
+  // (whose own open tasks are empty — the escalation lives in the CHILD instance) would read "no
+  // escalation open" and wrongly flip a genuinely-parked run back to `running`. The confirmation must
+  // include the callActivity descendants when the raw-REST surface is available.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString(); // past the heal grace window
+  const { data, stores } = memData({
+    feature_runs: [
+      { feature_key: "o/r#child", status: "escalated", process_key: "fp-parent", updated_at: stale, issue_url: null, title: "parked in child cell", delivery_label: null },
+    ],
+  });
+  // The sweep is unavailable (returns empty), so fp-parent is NOT confirmed parked via `desired`; the
+  // descendant walk over `/process-instances/search` surfaces the child instance carrying the escalation.
+  const orig = globalThis.fetch;
+  // biome-ignore lint/suspicious/noExplicitAny: minimal fetch double for the raw-REST search surfaces
+  globalThis.fetch = (async (url: string | URL, init?: any) => {
+    const u = String(url);
+    if (u.endsWith("/user-tasks/search")) {
+      return new Response(JSON.stringify({ items: [] }), { status: 200, headers: { "content-type": "application/json" } });
+    }
+    if (u.endsWith("/process-instances/search")) {
+      const parent = JSON.parse(init?.body ?? "{}")?.filter?.parentProcessInstanceKey;
+      const items = parent === "fp-parent" ? [{ processInstanceKey: "child-1" }] : [];
+      return new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } });
+    }
+    return new Response("not found", { status: 404 });
+  }) as typeof fetch;
+  // The escalation is parked in the CHILD instance on the `escalation` element, not on the parent.
+  const engine = fakeEngine({ "fp-parent": [], "child-1": [{ userTaskKey: "ut-child", elementId: "escalation" }] });
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    globalThis.fetch = orig;
+  }
+  const byKey = Object.fromEntries((stores.feature_runs ?? []).map((r) => [r.feature_key, r]));
+  assertEquals(byKey["o/r#child"].status, "escalated", "a run parked in a callActivity child cell survives when the sweep missed it");
+});
+
 test("pollUserTasks (typed-seam fallback): self-heals an escalated run with no open feature-escalation task (issue #642)", async () => {
   // The reduced-capability path scans FEATURE_ACTIVE_STATUSES instances (incl. `escalated`) directly,
   // so the per-instance open-task read is just as authoritative for the self-heal.

package/app/service.ts

@@ -88,6 +88,7 @@ import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
   buildUserTaskRow,
+  HUMAN_ESCALATION_ELEMENT,
   latestFeatureEscalationQuestion,
   latestOpenEscalationQuestion,
   latestPlanReviewFindings,
@@ -2270,6 +2271,14 @@ interface UserTaskSearchItem {
   userTaskKey?: string | number;
   elementId?: string;
   processInstanceKey?: string | number;
+  /** The top-level ancestor process instance in this task's callActivity hierarchy — present for
+   *  hierarchies created on an engine carrying the read-model parent/root keys (Magikcraft/nano-bpm#977,
+   *  engine-wasm ≥ 0.8.4). Equals `processInstanceKey` for a top-level task; for a task parked inside a
+   *  callActivity CHILD instance (the shared `human-escalation`/`implement-cell` cells, ADR 0006 S4) it
+   *  is the PARENT run's instance, so the poller can correlate the child-instance task back to the
+   *  tracked feature/plan subject (issue #633). Absent (`null`) on a pre-#977 engine or a top-level
+   *  task. The wire may send a JSON number or string. */
+  rootProcessInstanceKey?: string | number | null;
   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
@@ -2282,6 +2291,10 @@ interface OpenUserTask {
   userTaskKey: string;
   elementId: string;
   processInstanceKey: string;
+  /** The top-level ancestor instance key (`""` when the engine did not report one — a pre-#977 engine
+   *  or a top-level task), used to correlate a callActivity child-instance task back to its parent run
+   *  (issue #633). */
+  rootProcessInstanceKey: 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;
@@ -2326,7 +2339,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), formKey: it.formKey == null ? "" : String(it.formKey) });
+      out.push({ userTaskKey, elementId, processInstanceKey: it.processInstanceKey == null ? "" : String(it.processInstanceKey), rootProcessInstanceKey: it.rootProcessInstanceKey == null ? "" : String(it.rootProcessInstanceKey), formKey: it.formKey == null ? "" : String(it.formKey) });
     }
     if (items.length < limit) break; // last page
     from += items.length;
@@ -2360,23 +2373,121 @@ async function sweepOpenEscalationTasks(base: string, headers: Record<string, st
  * completed task's row is deleted (answered here, via the task inbox, or out-of-band) and `showCount`
  * reflects live pending work. Best-effort + idempotent — per-instance failures are isolated so one bad
  * instance never stalls the pass. */
+/** The subset of a Camunda-8 `/v2/process-instances/search` result item this app reads to walk a
+ * callActivity instance hierarchy (issue #633). `processInstanceKey` is the instance; the engine's
+ * read-model parent/root keys (Magikcraft/nano-bpm#977) let a caller relate a child instance to its
+ * ancestors — this pass only needs `processInstanceKey` (it filters BY `parentProcessInstanceKey`, so
+ * every returned row is by construction a child of the queried parent). Keys are stringified
+ * defensively (the wire may send a JSON number or string). */
+interface ProcessInstanceSearchItem {
+  processInstanceKey?: string | number;
+}
+
+/** Enumerate every DESCENDANT process instance of `rootKey` in its callActivity hierarchy (issue #633)
+ * over the raw Camunda-8 `/v2/process-instances/search` surface, walking `parentProcessInstanceKey`
+ * breadth-first. Returns the descendant instance keys (NOT including `rootKey` itself). The engine
+ * exposes a `parentProcessInstanceKey` filter but no `rootProcessInstanceKey` one, so the hierarchy is
+ * walked level by level (parent → children → grandchildren): the fine-grained cells nest two deep
+ * (`plan-fanout` → `implement-cell` → `human-escalation`), and a deeper future graph is covered by the
+ * BFS. Bounded by a total-instance guard so a pathological/looping hierarchy can neither explode nor
+ * spin; best-effort transport — a failed page/level returns what was gathered so far. Deduped so a
+ * re-parented row can't be walked twice. */
+async function searchDescendantInstanceKeys(base: string, headers: Record<string, string>, rootKey: string): Promise<string[]> {
+  const out: string[] = [];
+  const seen = new Set<string>([rootKey]);
+  let frontier = [rootKey];
+  const limit = 100;
+  const MAX_INSTANCES = 1000; // hard cap so a pathological hierarchy can't unbounded-fan-out this pass
+  for (let depth = 0; depth < 64 && frontier.length > 0 && out.length < MAX_INSTANCES; depth++) {
+    const next: string[] = [];
+    for (const parent of frontier) {
+      let from = 0;
+      for (let guard = 0; guard < 1000; guard++) {
+        let items: ProcessInstanceSearchItem[];
+        try {
+          const res = await fetch(`${base}/process-instances/search`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ filter: { parentProcessInstanceKey: parent }, page: { from, limit } }),
+          });
+          if (!res.ok) break; // engine unhappy → walk what we have, retry next pass
+          // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+          const body = (await res.json()) as { items?: ProcessInstanceSearchItem[] };
+          items = body.items ?? [];
+        } catch (err) {
+          console.error(`[poller] process-instance hierarchy walk (${parent}): ${err}`);
+          break;
+        }
+        for (const it of items) {
+          const key = it.processInstanceKey == null ? "" : String(it.processInstanceKey);
+          if (!key || seen.has(key)) continue;
+          seen.add(key);
+          out.push(key);
+          next.push(key);
+          if (out.length >= MAX_INSTANCES) break;
+        }
+        if (items.length < limit || out.length >= MAX_INSTANCES) break; // last page / capped
+        from += items.length;
+      }
+    }
+    frontier = next;
+  }
+  return out;
+}
+
+/** Gather the element instances of an epic's plan-fanout instance AND every callActivity DESCENDANT of
+ * it (issue #633) into ONE flat list the canonical `deriveEpicPhaseLive` reads — so once a wave/slice
+ * runs as a child cell instance (ADR 0006 S4) the "furthest-reached live element" derivation still sees
+ * the token position INSIDE the child, not just the parent spine. Extends the derivation's INPUT via the
+ * engine's native parent/root traversal rather than adding a second phase deriver (derivation over
+ * duplication). Without the raw-REST surface (`rest` null — unit tests / a degraded no-REST host) it
+ * degrades to the parent instance alone (the pre-composition behaviour), since the typed seam cannot
+ * enumerate children. */
+async function gatherHierarchyElementInstances(
+  engine: Pick<EngineClient, "searchElementInstances">,
+  rest: { base: string; headers: Record<string, string> } | null,
+  rootKey: string,
+): Promise<Awaited<ReturnType<EngineClient["searchElementInstances"]>>> {
+  const instanceKeys = [rootKey];
+  if (rest) {
+    const descendants = await searchDescendantInstanceKeys(rest.base, rest.headers, rootKey);
+    instanceKeys.push(...descendants);
+  }
+  const all: Awaited<ReturnType<EngineClient["searchElementInstances"]>> = [];
+  for (const key of instanceKeys) {
+    all.push(...(await engine.searchElementInstances({ processInstanceKey: key })));
+  }
+  return all;
+}
+
 /** Poll pass (S8, #542 / ADR 0006 §4b): reconcile each LIVE epic's `plans.epic_phase` from the engine
  * element-instance model — the PURE read-model derivation that RETIRES the write-time stamp the spine
  * workers used to write. For each plan still live (`EPIC_LIVE_STATUSES`) with a running instance, read
- * its element instances (`searchElementInstances`, nano-ide#473) and project the furthest-reached
- * active spine element onto its domain phase (`deriveEpicPhaseLive`, app/epicPhase.ts — the SAME
- * `ELEMENT_PHASE` structural map the stamp used). The wave label rides the `plan_wave_progress` rollup
- * VIEW (the single wave-frontier source, 060/082), so the Implementing band reads `wave n/t` without a
- * second wave derivation. Writes only on a real change (a steady-state pass is a no-op) and leaves the
- * last phase untouched when nothing active marks one (`null`), so a plan parked on non-spine plumbing
- * never clobbers to blank. The terminal `Dispatched` phase is a COMPLETION marker (no ACTIVE token to
- * read once the instance ends), so a second pass derives it from the durable terminal status
+ * its element instances (`searchElementInstances`, nano-ide#473) — the plan-fanout instance AND, once
+ * the raw-REST surface is available, every callActivity CHILD cell instance (ADR 0006 S4, #603/#633),
+ * gathered via the engine's native parent/root traversal (`gatherHierarchyElementInstances`) so the
+ * furthest-reached element INSIDE a child cell is seen — and project the furthest-reached active spine
+ * element onto its domain phase (`deriveEpicPhaseLive`, app/epicPhase.ts — the SAME `ELEMENT_PHASE`
+ * structural map the stamp used). The wave label rides the `plan_wave_progress` rollup VIEW (the single
+ * wave-frontier source, 060/082), so the Implementing band reads `wave n/t` without a second wave
+ * derivation. Writes only on a real change (a steady-state pass is a no-op) and leaves the last phase
+ * untouched when nothing active marks one (`null`), so a plan parked on non-spine plumbing never
+ * clobbers to blank. The terminal `Dispatched` phase is a COMPLETION marker (no ACTIVE token to read
+ * once the instance ends), so a second pass derives it from the durable terminal status
  * (`deriveTerminalEpicPhase` over `done` epics) rather than the fleeting ACTIVE `record-results` token
  * a coarse poll would miss. Best-effort + idempotent — a per-plan failure is isolated. */
 export async function pollEpicPhase(
   data: DataLayer,
   engine: Pick<EngineClient, "searchElementInstances">,
+  engineRest?: { restAddress: string; token?: string },
 ) {
+  const rest = engineRest
+    ? (() => {
+        const headers: Record<string, string> = { "content-type": "application/json" };
+        if (engineRest.token) headers.authorization = `Bearer ${engineRest.token}`;
+        return { base: engineRest.restAddress.replace(/\/+$/, ""), headers };
+      })()
+    : null;
   const waveByPlan = new Map<string, { current: number | null; total: number | null }>();
   for (const w of await data
     .table<{ plan_key: string; wave_count: number | null; current_wave: number | null }>(
@@ -2396,7 +2507,7 @@ export async function pollEpicPhase(
     for (const plan of await plans(data).find({ status })) {
       if (!plan.process_key) continue;
       try {
-        const elements = await engine.searchElementInstances({ processInstanceKey: plan.process_key });
+        const elements = await gatherHierarchyElementInstances(engine, rest, plan.process_key);
         const phase = deriveEpicPhaseLive(elements, waveByPlan.get(plan.plan_key) ?? undefined);
         if (phase !== null && phase !== plan.epic_phase) {
           await plans(data).update(plan.plan_key, { epic_phase: phase, updated_at: now() });
@@ -2535,6 +2646,15 @@ export async function pollUserTasks(
   engineRest?: { restAddress: string; token?: string },
 ) {
   const at = now();
+  // Raw-REST context (present in production; the reduced-capability seam host passes no `engineRest`) —
+  // used by the engine-first sweep AND the escalation self-heal's callActivity-hierarchy confirmation.
+  const rest = engineRest
+    ? (() => {
+        const headers: Record<string, string> = { "content-type": "application/json" };
+        if (engineRest.token) headers.authorization = `Bearer ${engineRest.token}`;
+        return { base: engineRest.restAddress.replace(/\/+$/, ""), headers };
+      })()
+    : null;
 
   // ── Enrichment: subject descriptors keyed by the ENGINE process-instance the task parks on ────────
   // Built from EVERY subject row (regardless of status), so a task on a subject whose row already went
@@ -2578,6 +2698,7 @@ export async function pollUserTasks(
   // when tracking is lost, so the fallback row still buckets correctly on the page.
   const DEFAULT_SUBJECT_TYPE: Readonly<Record<string, "feature" | "plan" | "pr">> = {
     [FEATURE_ESCALATION_ELEMENT]: "feature",
+    [HUMAN_ESCALATION_ELEMENT]: "feature",
     [FEATURE_BLOCKED_ELEMENT]: "feature",
     [PLAN_REVIEW_ELEMENT]: "plan",
     [TRIAL_MERGE_ELEMENT]: "plan",
@@ -2590,9 +2711,17 @@ 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, formKey: string): Promise<UserTaskContext | null> => {
+  //
+  // Parent/root correlation (#603/#633): a task parked inside a callActivity CHILD instance (the shared
+  // `human-escalation`/`implement-cell` cells, ADR 0006 S4) has a `processInstanceKey` no subject row
+  // tracks — its owning feature/plan run is the PARENT run, tracked under the `rootProcessInstanceKey`
+  // the engine reports (Magikcraft/nano-bpm#977). So the subject resolves off the DIRECT instance first
+  // and falls back to the ROOT (top-level ancestor) instance, correlating the child-instance escalation
+  // back to the parent run rather than stranding it as an orphan.
+  const contextFor = async (elementId: string, userTaskKey: string, processInstanceKey: string, rootProcessInstanceKey: string, formKey: string): Promise<UserTaskContext | null> => {
     if (userTaskKindLabel(elementId) === undefined) return null;
-    const subj = subjectByInstance.get(processInstanceKey);
+    const root = rootProcessInstanceKey.trim();
+    const subj = subjectByInstance.get(processInstanceKey) ?? (root && root !== processInstanceKey ? subjectByInstance.get(root) : undefined);
     // Orphaned-task fallback: the kind implies its aggregate even when no subject row references the
     // instance. A delivery-human node's id is inlined (`delivery-human-task__<node>`), so its bucket is
     // derived from the predicate rather than the static per-element table.
@@ -2606,9 +2735,13 @@ export async function pollUserTasks(
     let question: string | null = null;
     switch (elementId) {
       case FEATURE_ESCALATION_ELEMENT:
+      case HUMAN_ESCALATION_ELEMENT:
         // The escalate arm writes the synthesised question to `feature_escalations` keyed by the subject
         // (a standalone slice's `feature_key`, or the epic's `plan_key` for a plan-embedded slice, which
         // has no standalone `feature_runs` row) — the same key `subjectKey` resolves to for either subject.
+        // The shared `human-escalation` cell (`escalation`) is the same feature-escalation task relocated
+        // into a callActivity child, so it reads the SAME `feature_escalations` log via the correlated
+        // (parent/root) subject.
         question = latestFeatureEscalationQuestion(await featureEscalations(data).find({ feature_key: subjectKey }));
         break;
       case FEATURE_BLOCKED_ELEMENT:
@@ -2634,25 +2767,25 @@ export async function pollUserTasks(
   // 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, formKey: string) => {
+  const project = async (elementId: string | undefined, userTaskKey: string, processInstanceKey: string, rootProcessInstanceKey: string, formKey: string) => {
     if (!elementId) return;
     const rowKey = userTaskKey.trim();
     if (!rowKey || desiredByKey.has(rowKey)) return;
-    const ctx = await contextFor(elementId, userTaskKey, processInstanceKey, formKey);
+    const ctx = await contextFor(elementId, userTaskKey, processInstanceKey, rootProcessInstanceKey, formKey);
     if (!ctx) return;
     const row = buildUserTaskRow(ctx, at);
     if (row) desiredByKey.set(rowKey, row);
   };
 
-  if (engineRest) {
-    const base = engineRest.restAddress.replace(/\/+$/, "");
-    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, t.formKey);
+  if (rest) {
+    for (const t of await sweepOpenEscalationTasks(rest.base, rest.headers)) {
+      await project(t.elementId, t.userTaskKey, t.processInstanceKey, t.rootProcessInstanceKey, t.formKey);
     }
   } else {
     // Reduced-capability fallback (no raw-REST surface): typed-seam per-active-subject scan, tracked-only.
+    // The typed `openUserTasks` seam carries no parent/root key, so a child-instance task cannot be
+    // correlated here — this path reaches a task only THROUGH the tracked subject whose OWN instance it
+    // parks on (root correlation is a no-op, passed as "").
     const seen = new Set<string>();
     const scanInstance = async (processKey: string | null | undefined) => {
       if (!processKey || seen.has(processKey)) return;
@@ -2664,7 +2797,7 @@ export async function pollUserTasks(
         console.error(`[poller] user tasks (${processKey}): ${err}`);
         return;
       }
-      for (const t of tasks) await project(t.elementId, t.userTaskKey, processKey, t.formKey ?? "");
+      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);
@@ -2702,32 +2835,62 @@ export async function pollUserTasks(
   // is never guessed at.
   //
   // Presence in THIS pass's `desired` set is itself POSITIVE evidence of parking (truncation only ever
-  // DROPS tasks, never invents one), so a run whose `feature-escalation` task was already swept is
-  // genuinely parked — skip its per-instance `openUserTasks` RPC entirely (an avoidable N+1 on every
-  // tick). Only a run NOT confirmed parked by the sweep falls through to the per-instance check below.
-  const sweptParkedEscalations = new Set(
-    desired.filter((r) => r.element_id === FEATURE_ESCALATION_ELEMENT && r.process_key).map((r) => r.process_key),
-  );
+  // DROPS tasks, never invents one), so a run whose escalation task was already swept is genuinely
+  // parked — skip its per-instance `openUserTasks` RPC entirely (an avoidable N+1 on every tick). Only a
+  // run NOT confirmed parked by the sweep falls through to the per-instance check below.
+  //
+  // A run's escalation may park on its OWN inline `feature-escalation` (same instance as `process_key`)
+  // OR — once its implement step runs as a callActivity child cell (ADR 0006 S4, #603/#633) — on the
+  // shared `human-escalation` cell's `escalation` element inside a CHILD instance, correlated back to
+  // the run via the parent/root key (so the desired row's `subject_key` is the run's `feature_key`, not
+  // the child instance). So the swept set is keyed by BOTH the task's own `process_key` AND its
+  // correlated `subject_key`, and a run counts as parked when either matches (`process_key` for the
+  // inline case, `feature_key` for the child-cell case).
+  const sweptParkedEscalations = new Set<string>();
+  for (const r of desired) {
+    if (r.element_id !== FEATURE_ESCALATION_ELEMENT && r.element_id !== HUMAN_ESCALATION_ELEMENT) continue;
+    if (r.subject_type !== "feature") continue;
+    if (r.process_key) sweptParkedEscalations.add(r.process_key);
+    if (r.subject_key) sweptParkedEscalations.add(r.subject_key);
+  }
   for (const run of await featureRuns(data).find({ status: "escalated" })) {
     if (!run.process_key) continue;
-    if (sweptParkedEscalations.has(run.process_key)) continue; // already seen parked this pass — no RPC, no heal
+    if (sweptParkedEscalations.has(run.process_key) || sweptParkedEscalations.has(run.feature_key)) continue; // already seen parked this pass — no RPC, no heal
     // A just-written escalation may not have its `feature-escalation` user task yet: the sole writer,
     // `record-feature-escalation`, stamps `updated_at` immediately BEFORE the engine creates the task.
     // Skip healing inside the grace window so this pass never races that transition and steals a fresh
     // escalation; a genuinely-stranded (old, or timestamp-less) row is past the window and still healed.
     const escalatedAt = Date.parse(run.updated_at ?? "");
     if (Number.isFinite(escalatedAt) && Date.now() - escalatedAt < FEATURE_ESCALATION_HEAL_GRACE_MS) continue;
-    let openTasks: { elementId?: string }[];
-    try {
-      openTasks = await engine.openUserTasks({ processInstanceKey: run.process_key });
-    } catch (err) {
-      // Negative evidence from a failed query is not proof the run is unparked — leave it for a later pass.
-      console.error(`[poller] escalated-run self-heal (${run.feature_key} @ ${run.process_key}): ${err}`);
-      continue;
-    }
-    if (!openTasks.some((t) => t.elementId === FEATURE_ESCALATION_ELEMENT)) {
-      await featureRuns(data).update(run.feature_key, { status: "running", updated_at: at });
+    // Confirm across the run's WHOLE callActivity hierarchy, not just its parent instance: a child-cell
+    // escalation (ADR 0006 S4, #603/#633) parks on the shared `human-escalation` cell's `escalation`
+    // element inside a DESCENDANT instance that the parent's `openUserTasks` never reports. Confirming
+    // the parent alone would read "no escalation open" and wrongly flip a genuinely-parked child-cell run
+    // back to `running` whenever THIS pass's sweep missed it (truncated/unavailable, so it is absent from
+    // `desired`). Include the callActivity descendants when the raw-REST surface is available; the
+    // reduced-capability seam (no `rest`) cannot walk the hierarchy, so it stays parent-only (child-cell
+    // correlation is a no-op on that path anyway). Any per-instance query error is negative evidence, not
+    // proof the run is unparked — skip the heal and leave the row for a later pass (parity with before).
+    const confirmInstances = [run.process_key];
+    if (rest) confirmInstances.push(...(await searchDescendantInstanceKeys(rest.base, rest.headers, run.process_key)));
+    let stillParked = false;
+    let queryErrored = false;
+    for (const instanceKey of confirmInstances) {
+      let openTasks: { elementId?: string }[];
+      try {
+        openTasks = await engine.openUserTasks({ processInstanceKey: instanceKey });
+      } catch (err) {
+        console.error(`[poller] escalated-run self-heal (${run.feature_key} @ ${instanceKey}): ${err}`);
+        queryErrored = true;
+        break;
+      }
+      if (openTasks.some((t) => t.elementId === FEATURE_ESCALATION_ELEMENT || t.elementId === HUMAN_ESCALATION_ELEMENT)) {
+        stillParked = true;
+        break;
+      }
     }
+    if (queryErrored || stillParked) continue;
+    await featureRuns(data).update(run.feature_key, { status: "running", updated_at: at });
   }
 }
 
@@ -2751,7 +2914,7 @@ export async function pollOnce(
   await pollFeatureDelivery(data);
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
-  await pollEpicPhase(data, engine);
+  await pollEpicPhase(data, engine, engineRest);
   await pollTasklessPlanTermination(data, engine);
   await pollDeliveryGraphPhase(data, engine);
   await pollDeliveryProposals(data);

package/app/userTasks.ts

@@ -60,6 +60,17 @@ export const PR_WAIT_MERGE_ANSWER_ELEMENT = "wait-merge-answer";
  *  hire — a `yolo`-policy request never reaches this path (see `app/agentic/permission-bridge.ts`). */
 export const ACP_PERMISSION_ELEMENT = "acp-permission";
 
+/** The shared human-escalation cell's escalation user task (`human-escalation.bpmn`, ADR 0006 S4,
+ *  issue #603/#633). The fine-grained `implement-cell` delegates its escalation to the reusable
+ *  `human-escalation` cell via `callActivity`, so once a wave/slice runs as a child instance the
+ *  agent-stuck escalation parks on THIS element id (`escalation`) inside that child — NOT on the
+ *  parent's inline `feature-escalation`. It renders the SAME `feature-escalation` form and is the same
+ *  agent-answerable task escalation, so the inbox surfaces it under the one "Feature escalation" kind
+ *  and the poller correlates it back to the parent run via the engine's native parent/root instance
+ *  keys (Magikcraft/nano-bpm#977, the #464 option-B decision). Without this the child-instance
+ *  escalation is filtered out by the unknown-kind guard and silently vanishes from the Tasks inbox. */
+export const HUMAN_ESCALATION_ELEMENT = "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. */
@@ -92,6 +103,7 @@ export const userTasks = (data: DataLayer) => data.table<UserTaskRow>("user_task
  *  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",
+  [HUMAN_ESCALATION_ELEMENT]: "Feature escalation",
   [FEATURE_BLOCKED_ELEMENT]: "Blocked feature run",
   [PLAN_REVIEW_ELEMENT]: "Plan review",
   [EMPTY_PLAN_ELEMENT]: "Empty plan",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.167.4",
+  "version": "0.168.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",