@nanobpm/nano-workforce 0.171.1 → 0.171.3

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.171.3](https://github.com/nanobpm/nano-workforce/compare/v0.171.2...v0.171.3) (2026-08-31)
+
+### Code Refactoring
+
+* compose implement → implement-cell (feature + plan-fanout) ([#646](https://github.com/nanobpm/nano-workforce/issues/646)) ([#656](https://github.com/nanobpm/nano-workforce/issues/656)) ([caca54e](https://github.com/nanobpm/nano-workforce/commit/caca54e42caf0a1db83a8f15092c7c834e05e81f)), closes [#642](https://github.com/nanobpm/nano-workforce/issues/642) [#360](https://github.com/nanobpm/nano-workforce/issues/360) [#642](https://github.com/nanobpm/nano-workforce/issues/642) [#642](https://github.com/nanobpm/nano-workforce/issues/642)
+
+## [0.171.2](https://github.com/nanobpm/nano-workforce/compare/v0.171.1...v0.171.2) (2026-08-31)
+
+### Bug Fixes
+
+* surface + complete readiness/preflight escalations in the Tasks inbox ([#675](https://github.com/nanobpm/nano-workforce/issues/675)) ([9d874e8](https://github.com/nanobpm/nano-workforce/commit/9d874e889f3155b7887bb48032e39c5f78e33ce3)), closes [#674](https://github.com/nanobpm/nano-workforce/issues/674)
+
 ## [0.171.1](https://github.com/nanobpm/nano-workforce/compare/v0.171.0...v0.171.1) (2026-08-31)
 
 ### Code Refactoring

package/app/agentCompletion.test.ts

@@ -286,6 +286,38 @@ test("empty-plan-escalation is HUMAN-completable but NOT agent-completable (issu
   assertEquals(completed[0].variables, { directive: "revise", notes: "look again" });
 });
 
+test("readiness-escalation(-pf) is HUMAN-completable but NOT agent-completable (issue #674)", async () => {
+  // A readiness/preflight gate adjudicates whether upstream is ACTUALLY ready (proceed) or the gate
+  // should be abandoned. Like feature-blocked/conformance/empty-plan it is a HUMAN operator decision —
+  // an agent must never auto-answer it, or the fleet would silently defeat the very readiness gate the
+  // task exists to enforce. So both ids stay OUTSIDE `ESCALATION_TASK_ELEMENTS` (agent-refused) but are
+  // retired by the HUMAN completer via the one canonical `complete-user-task` door.
+  for (const elementId of ["readiness-escalation-pf", "readiness-escalation"] as const) {
+    const stores = { task_completions: { rows: [] as any[], key: "id" } };
+    const data = memData(stores);
+    const { engine, completed } = fakeEngine([{ userTaskKey: "ut-r", elementId }]);
+
+    const asAgent = await completeEscalationAsAgent(data, engine, {
+      userTaskKey: "ut-r",
+      agentId: "bot",
+      variables: { resolution: "acknowledge" },
+    });
+    assertEquals(asAgent.ok, false, `the agent completer refuses ${elementId}`);
+    assertEquals(asAgent.reason, "not a completable task");
+    assertEquals(completed.length, 0);
+
+    const asHuman = await completeEscalationAsHuman(data, engine, {
+      userTaskKey: "ut-r",
+      operatorId: "alice",
+      variables: { resolution: "abandon", answer: "upstream never published" },
+    });
+    assertEquals(asHuman.ok, true, `the human completer retires ${elementId}`);
+    assertEquals(asHuman.elementId, elementId);
+    assertEquals(completed.length, 1);
+    assertEquals(completed[0].variables, { resolution: "abandon", answer: "upstream never published" });
+  }
+});
+
 test("human completer refuses a non-escalation user task and is a no-op for an unknown key", async () => {
   const stores = { task_completions: { rows: [] as any[], key: "id" } };
   const data = memData(stores);

package/app/agentCompletion.ts

@@ -24,7 +24,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
-import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT } from "./userTasks.ts";
+import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT, READINESS_ESCALATION_ELEMENT, READINESS_ESCALATION_PF_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
 
@@ -101,6 +101,16 @@ export const CONFORMANCE_ESCALATION_TASK_ELEMENT = CONFORMANCE_ESCALATION_ELEMEN
  *  Re-exported from the canonical `EMPTY_PLAN_ELEMENT` (app/userTasks.ts) — one source of truth. */
 export const EMPTY_PLAN_TASK_ELEMENT = EMPTY_PLAN_ELEMENT;
 
+/** The readiness/preflight escalation user-task element ids (`readiness-escalation-pf` in feature.bpmn's
+ *  readiness preflight + plan-fanout.bpmn's producer-capability preflight; `readiness-escalation` in
+ *  readiness-gate.bpmn / wait-gate.bpmn). Like `feature-blocked`, `conformance-escalation` and
+ *  `empty-plan-escalation` these are HUMAN-only decisions — an agent must never auto-answer a readiness
+ *  gate (that would silently defeat the "is upstream actually ready?" adjudication the gate exists for),
+ *  so they live OUTSIDE `ESCALATION_TASK_ELEMENTS` and only the HUMAN completer accepts them (issue
+ *  #674). Re-exported from the canonical constants in app/userTasks.ts — one source of truth. */
+export const READINESS_ESCALATION_PF_TASK_ELEMENT = READINESS_ESCALATION_PF_ELEMENT;
+export const READINESS_ESCALATION_TASK_ELEMENT = READINESS_ESCALATION_ELEMENT;
+
 /** The user-task `elementId`s a HUMAN operator may complete from the Tasks inbox via the one canonical
  *  `complete-user-task` door: every agent-answerable escalation PLUS the human-only `feature-blocked`
  *  and `conformance-escalation` acknowledgements, PLUS the advisory ACP permission prompt
@@ -115,6 +125,8 @@ export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
   FEATURE_BLOCKED_TASK_ELEMENT,
   CONFORMANCE_ESCALATION_TASK_ELEMENT,
   EMPTY_PLAN_TASK_ELEMENT,
+  READINESS_ESCALATION_PF_TASK_ELEMENT,
+  READINESS_ESCALATION_TASK_ELEMENT,
   ACP_PERMISSION_ELEMENT,
 ]);
 
@@ -131,6 +143,8 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "feature-blocked": "feature-blocked",
   [EMPTY_PLAN_TASK_ELEMENT]: "empty-plan-escalation",
   [CONFORMANCE_ESCALATION_TASK_ELEMENT]: "conformance-escalation",
+  [READINESS_ESCALATION_PF_TASK_ELEMENT]: "readiness-escalation",
+  [READINESS_ESCALATION_TASK_ELEMENT]: "readiness-escalation",
   // NOTE: the delivery-graph `human` node (`DELIVERY_HUMAN_ELEMENT`, ADR 0005 S3) is intentionally
   // ABSENT here. Unlike the fixed-form escalations above, ONE `delivery-human-task` element is DESIGNED
   // to render DIFFERENT forms per node (explicit → category → generic → agent-router, `app/deliveryHuman.ts`

package/app/deliveryDispatch.test.ts

@@ -56,10 +56,14 @@ function manifestBindings(): Binding[] {
 }
 
 // The deployed process models — scanned for their prompt-bearing agent tasks, the real dispatch
-// corpus the door's verbs must already exist in.
+// corpus the door's verbs must already exist in. Includes the shared S4 atomic cells (ADR 0006): the
+// implement/escalation and trial-merge agent tasks now live in `implement-cell` / `merge-cell`, which
+// `feature.bpmn` and the `plan-fanout` MI body compose by `callActivity`.
 const MODEL_FILES = [
   "feature.bpmn",
   "plan-fanout.bpmn",
+  "implement-cell.bpmn",
+  "merge-cell.bpmn",
   "convergence-loop.bpmn",
   "merge-loop.bpmn",
   "retro.bpmn",
@@ -85,7 +89,7 @@ test("VERB PARITY: every mapped dispatch verb is a real senior:* agent task in t
 });
 
 test("VERB PARITY: the implementation kinds keep the pre-collapse senior:feature target", () => {
-  // feature.bpmn's implement task and plan-fanout.bpmn's per-slice implement task both dispatch
+  // implement-cell.bpmn's agent task (composed by feature.bpmn and the plan-fanout MI body) dispatches
   // senior:feature today — the door preserves that for the single-issue implementation kinds.
   assertEquals(dispatchJobTypeForKind("feature"), "senior:feature");
   assertEquals(dispatchJobTypeForKind("plan-task"), "senior:feature");

package/app/escalationTaxonomy.ts

@@ -39,10 +39,11 @@ export type EscalationKind =
   | "dead-end-base"
   // `mergeProtocol` (app/mergeProtocol.ts) — the repo's declared land method.
   | "merge-protocol"
-  // plan-fanout `w_gw` "clean terminal?" gateway — the implement-stage escalation net (issue #360).
-  // Any non-clean-terminal slice outcome routes through the `record-wave-escalation` worker, which
-  // classifies with this kind: the agent's own answerable question passes through, and a no-machine-
-  // readable result (or a blank-question `escalated`) is synthesised into an answerable one.
+  // The shared `implement-cell`'s `ic_gw` "clean terminal?" gateway — the implement-stage escalation
+  // net (issue #360). Any non-clean-terminal slice outcome routes through the cell's unified
+  // `record-feature-escalation` worker, which classifies with this kind: the agent's own answerable
+  // question passes through, and a no-machine-readable result (or a blank-question `escalated`) is
+  // synthesised into an answerable one.
   | "task";
 
 /** Everything the classifier may need from any raise site. Each field is consumed only by the

package/app/fineGrainedCells.test.ts

@@ -99,3 +99,96 @@ test("feature.bpmn composes its converge step via callActivity to converge-cell
     );
   }
 });
+
+test("feature.bpmn composes its implement step via callActivity to implement-cell — no inlined implement serviceTask", () => {
+  // The implement seam (deferred out of #632, tracked in #646) composes the shared `implement-cell`
+  // via a `callActivity` with an explicit `zeebe:ioMapping`, rather than an inlined `senior:feature`
+  // serviceTask plus a per-caller escalation loop. The atomic cell owns its own escalation retry
+  // (through the shared `human-escalation` cell), so the parent no longer carries the
+  // `record-feature-escalation` / `feature-escalation` / answer-loop gateways.
+  const xml = flat("feature");
+  assert(
+    /<bpmn:callActivity\b[^>]*\bid="implement"[\s\S]*?<zeebe:calledElement\b[^>]*\bprocessId="implement-cell"/.test(xml),
+    "feature.bpmn must compose implement as a callActivity to implement-cell",
+  );
+  assert(
+    !/<bpmn:serviceTask\b[^>]*\bid="implement-task"/.test(xml),
+    "feature.bpmn must not keep an inlined implement-task serviceTask once the cell is composed",
+  );
+  // The inlined escalation loop is relocated into the atomic cell — the parent path must not keep it.
+  assert(
+    !/<bpmn:serviceTask\b[^>]*\bid="record-feature-escalation"/.test(xml),
+    "feature.bpmn must not keep the inlined record-feature-escalation serviceTask once the cell owns escalation",
+  );
+  assert(
+    !/<bpmn:userTask\b[^>]*\bid="feature-escalation"/.test(xml),
+    "feature.bpmn must not keep the inlined feature-escalation userTask once the cell owns escalation",
+  );
+  // Pin the explicit `zeebe:ioMapping` on the implement callActivity block alone (no `propagateAll*`).
+  const implementBlock =
+    xml.match(/<bpmn:callActivity\b[^>]*\bid="implement"[\s\S]*?<\/bpmn:callActivity>/)?.[0] ?? "";
+  assert(
+    /<zeebe:ioMapping>[\s\S]*?<\/zeebe:ioMapping>/.test(implementBlock),
+    "the implement callActivity must carry an explicit zeebe:ioMapping",
+  );
+  assert(
+    /<zeebe:input\b[^>]*\btarget="task"/.test(implementBlock),
+    "the implement callActivity ioMapping must map the task slice into the child scope",
+  );
+  for (const field of ["status", "summary", "pr"]) {
+    assert(
+      new RegExp(`<zeebe:output\\b[^>]*\\btarget="${field}"`).test(implementBlock),
+      `the implement callActivity ioMapping must map the child result field ${field} back into the parent scope`,
+    );
+  }
+});
+
+test("plan-fanout.bpmn composes its per-wave implement step via a callActivity to implement-cell", () => {
+  // Per ADR 0006 §2 the composition "replaces the inlined segments, not the surrounding orchestration":
+  // the multi-instance `implement` subProcess (one token per wave task) keeps its fan-out-specific
+  // capability barrier (`caps-prepare` / `wait-caps`) as surrounding orchestration, and its inlined
+  // implement/escalation SEGMENT (the per-wave `senior:feature` serviceTask, the `w_gw` "clean
+  // terminal?" gateway, and the `record-wave-escalation` recorder) collapses into a `callActivity` to
+  // the shared `implement-cell` — the atomic cell now owns the agent loop and its escalation through the
+  // shared `human-escalation` cell ("a wave IS a callActivity", #464/#646). The MI stays on the
+  // subProcess (one token per wave); the cell is invoked once per token.
+  const xml = flat("plan-fanout");
+  // The MI element is the `implement` subProcess (one token per wave), preserved as the caps-barrier
+  // host; assert its multi-instance loop over `waveTasks`.
+  const implementSub =
+    xml.match(/<bpmn:subProcess\b[^>]*\bid="implement"[\s\S]*?<\/bpmn:subProcess>/)?.[0] ?? "";
+  assert(implementSub.length > 0, "plan-fanout.bpmn must keep the per-wave implement subProcess (the caps-barrier host)");
+  assert(
+    /<bpmn:multiInstanceLoopCharacteristics>[\s\S]*?inputCollection="=waveTasks"/.test(implementSub),
+    "the implement subProcess must be multi-instance — one token per wave task",
+  );
+  // The caps barrier stays in the wave (fan-out-specific, not part of the atomic cell).
+  assert(
+    /<zeebe:taskDefinition\b[^>]*\btype="pr.caps-prepare"/.test(implementSub),
+    "the capability barrier (caps-prepare) stays in the wave as surrounding orchestration",
+  );
+  // The implement/escalation segment is replaced by a callActivity to the shared implement-cell.
+  const cellCall =
+    implementSub.match(/<bpmn:callActivity\b[^>]*\bid="implement-cell-call"[\s\S]*?<\/bpmn:callActivity>/)?.[0] ?? "";
+  assert(
+    /<zeebe:calledElement\b[^>]*\bprocessId="implement-cell"/.test(cellCall),
+    "plan-fanout.bpmn must compose the per-wave implement as a callActivity to implement-cell",
+  );
+  assert(
+    /<zeebe:ioMapping>[\s\S]*?<\/zeebe:ioMapping>/.test(cellCall),
+    "the implement-cell callActivity must carry an explicit zeebe:ioMapping (no propagateAll*)",
+  );
+  assert(
+    /<zeebe:input\b[^>]*\btarget="task"/.test(cellCall) && /<zeebe:input\b[^>]*\btarget="subjectKey"/.test(cellCall),
+    "the implement-cell callActivity must map the wave task and the plan subject key into the child scope",
+  );
+  // The inlined per-wave agent loop + escalation recorder no longer sit on the fan-out path.
+  assert(
+    !/<bpmn:serviceTask\b[^>]*\bid="implement-task"/.test(implementSub),
+    "plan-fanout.bpmn must not keep an inlined implement-task serviceTask once the cell is composed",
+  );
+  assert(
+    !/type="pr.record-wave-escalation"/.test(xml),
+    "plan-fanout.bpmn must not keep the inlined record-wave-escalation recorder (folded into the cell's recorder)",
+  );
+});

package/app/planFanoutCleanTerminal.test.ts

@@ -1,40 +1,43 @@
-// Structural guard for the wave subprocess's "clean terminal?" gateway (w_gw) — the implement-stage
-// escalation net (#358/#360). The whole point of the net is that a slice with NO clean terminal
-// status escalates to a human. The no-result case (implement-task completes with `status`
-// missing/undefined) is EXACTLY what must escalate, so the gateway must not depend on a `not(...)`
-// negation that FEEL leaves `null` for a missing `status` (a null condition takes NO flow and would
-// fall through to the default). We eliminate that failure mode categorically: ESCALATE is the
-// DEFAULT flow and DONE is gated on the closed set of clean terminal statuses — so anything that is
-// not a recognised clean terminal (including a missing/undefined status) escalates, regardless of
-// how the engine evaluates equality against null.
+// Structural guard for the implement cell's "clean terminal?" gateway (ic_gw) — the implement-stage
+// escalation net (#358/#360), now owned by the shared `implement-cell` (ADR 0006 S4). Before the S4
+// composition this gateway lived inline as `plan-fanout.bpmn`'s `w_gw` and `feature.bpmn`'s equivalent;
+// composing the atomic cell relocated it (and its `record-escalation` recorder + `human-escalation`
+// loop) into `implement-cell.bpmn`, which BOTH `feature.bpmn` and the `plan-fanout` MI body compose by
+// `callActivity`. The invariant is unchanged: a slice with NO clean terminal status escalates to a
+// human. The no-result case (the agent completes with `status` missing/undefined) is EXACTLY what must
+// escalate, so the gateway must not depend on a `not(...)` negation that FEEL leaves `null` for a
+// missing `status` (a null condition takes NO flow and would fall through to the default). We eliminate
+// that failure mode categorically: ESCALATE is the DEFAULT flow and DONE is gated on the closed set of
+// clean terminal statuses — so anything that is not a recognised clean terminal (including a
+// missing/undefined status) escalates, regardless of how the engine evaluates equality against null.
 //
 // Pure text assertions over the committed BPMN (no engine), matching the repo's model-guard style.
 import { readFileSync } from "node:fs";
 import { test } from "node:test";
 import { assert, assertStringIncludes } from "#test-assert";
 
-const bpmn = readFileSync("resources/processes/plan-fanout.bpmn", "utf8");
+const bpmn = readFileSync("resources/processes/implement-cell.bpmn", "utf8");
 const flat = bpmn.replace(/\s+/g, " ");
 
-const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="w_gw"[^>]*>/)?.[0] ?? "";
-const wDone = flat.match(/<bpmn:sequenceFlow\b[^>]*\bid="w_done"[^>]*\/>|<bpmn:sequenceFlow\b[^>]*\bid="w_done"[\s\S]*?<\/bpmn:sequenceFlow>/)?.[0] ?? "";
-const wEscalate = flat.match(/<bpmn:sequenceFlow\b[^>]*\bid="w_escalate"[^>]*\/>|<bpmn:sequenceFlow\b[^>]*\bid="w_escalate"[\s\S]*?<\/bpmn:sequenceFlow>/)?.[0] ?? "";
+const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="ic_gw"[^>]*>/)?.[0] ?? "";
+const icDone = flat.match(/<bpmn:sequenceFlow\b[^>]*\bid="ic_done"[^>]*\/>|<bpmn:sequenceFlow\b[^>]*\bid="ic_done"[\s\S]*?<\/bpmn:sequenceFlow>/)?.[0] ?? "";
+const icEscalate = flat.match(/<bpmn:sequenceFlow\b[^>]*\bid="ic_escalate"[^>]*\/>|<bpmn:sequenceFlow\b[^>]*\bid="ic_escalate"[\s\S]*?<\/bpmn:sequenceFlow>/)?.[0] ?? "";
 
-test("w_gw: ESCALATE is the default flow, so a missing/undefined status can never fall through to done", () => {
-  assert(gw, "w_gw gateway must exist");
-  assertStringIncludes(gw, 'default="w_escalate"', "escalate must be the default — the no-result case escalates, never silently completes");
+test("ic_gw: ESCALATE is the default flow, so a missing/undefined status can never fall through to done", () => {
+  assert(gw, "ic_gw gateway must exist");
+  assertStringIncludes(gw, 'default="ic_escalate"', "escalate must be the default — the no-result case escalates, never silently completes");
 });
 
-test("w_gw: DONE is gated on the closed set of clean terminal statuses (not a fragile not(...) negation)", () => {
-  assert(wDone, "w_done flow must exist");
-  assertStringIncludes(wDone, "conditionExpression", "the done flow must be conditional, not the default");
-  assertStringIncludes(wDone, 'status = "opened"', "done requires a recognised clean terminal status");
-  assertStringIncludes(wDone, 'status = "blocked"', "done requires a recognised clean terminal status");
-  assertStringIncludes(wDone, 'status = "skipped"', "done requires a recognised clean terminal status");
+test("ic_gw: DONE is gated on the closed set of clean terminal statuses (not a fragile not(...) negation)", () => {
+  assert(icDone, "ic_done flow must exist");
+  assertStringIncludes(icDone, "conditionExpression", "the done flow must be conditional, not the default");
+  assertStringIncludes(icDone, 'status = "opened"', "done requires a recognised clean terminal status");
+  assertStringIncludes(icDone, 'status = "blocked"', "done requires a recognised clean terminal status");
+  assertStringIncludes(icDone, 'status = "skipped"', "done requires a recognised clean terminal status");
 });
 
-test("w_gw: the escalate flow carries no condition — it is the unconditional default sink", () => {
-  assert(wEscalate, "w_escalate flow must exist");
-  assert(!wEscalate.includes("conditionExpression"), "escalate is the default flow and must carry no condition");
-  assert(!wEscalate.includes("not("), "escalate must not depend on a not(...) negation that FEEL leaves null for a missing status");
+test("ic_gw: the escalate flow carries no condition — it is the unconditional default sink", () => {
+  assert(icEscalate, "ic_escalate flow must exist");
+  assert(!icEscalate.includes("conditionExpression"), "escalate is the default flow and must carry no condition");
+  assert(!icEscalate.includes("not("), "escalate must not depend on a not(...) negation that FEEL leaves null for a missing status");
 });

package/app/planFanoutPreflight.test.ts

@@ -66,8 +66,15 @@ test("a never-green producer escalates (bounded) without wedging: probe timeout
   assert(hasFlow("be_pf_sla", "pf_end"), "an elapsed escalation SLA settles the preflight instead of wedging");
 });
 
-test("the bound resolvedArtifacts version rides the implement task's appendPrompt", () => {
-  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="implement-task"[\s\S]*?<\/bpmn:serviceTask>/);
-  assert(task, "implement-task must exist");
-  assertStringIncludes(task![0], "resolvedArtifacts", "the bound pkg@version is threaded into the slice prompt");
+test("the bound resolvedArtifacts version rides the implement cell's appendPrompt", () => {
+  // The per-wave implement/escalation segment is composed into `implement-cell` (ADR 0006 S4), so the
+  // bound `pkg@version`s ride the MI `implement-cell` callActivity's ioMapping into the cell, whose
+  // `implement-task` threads them into the slice prompt's appendPrompt.
+  const call = flat.match(/<bpmn:callActivity\b[^>]*\bid="implement-cell-call"[\s\S]*?<\/bpmn:callActivity>/);
+  assert(call, "the implement-cell callActivity must exist");
+  assertStringIncludes(call![0], "resolvedArtifacts", "the bound pkg@version is threaded into the cell's slice prompt");
+  const cell = readFileSync("resources/processes/implement-cell.bpmn", "utf8").replace(/\s+/g, " ");
+  const task = cell.match(/<bpmn:serviceTask\b[^>]*\bid="implement-task"[\s\S]*?<\/bpmn:serviceTask>/);
+  assert(task, "implement-cell must own the implement-task");
+  assertStringIncludes(task![0], "resolvedArtifacts", "the cell's implement-task appendPrompt consumes the bound pkg@version");
 });

package/app/pollUserTasks.test.ts

@@ -161,6 +161,69 @@ test("pollUserTasks: projects a feature-escalation that lands on a plan-fanout p
   assertEquals(byKey["ut-embedded-feat"].question, "the agent returned no machine-readable result — enrol the PR?");
 });
 
+test("pollUserTasks: projects a readiness-escalation-pf preflight task on a feature run (issue #674)", async () => {
+  // The leading readiness preflight (feature.bpmn `pf_*` embedded subprocess) parks on the run's OWN
+  // engine instance when it times out before its ReadinessProbe goes green. Before #674 the element id
+  // was absent from USER_TASK_KIND_LABELS, so `contextFor`'s leak guard dropped it and the parked run
+  // was invisible + uncompletable in the Tasks surface. It must now project as an "Upstream readiness
+  // stalled" row on the feature subject, carrying the run's wait rollup as the question.
+  const { data, stores } = memData({
+    feature_runs: [
+      {
+        feature_key: "o/r#674",
+        status: "running",
+        process_key: "fp-674",
+        issue_url: "https://github.com/o/r/issues/674",
+        title: "Ship the widget",
+        delivery_label: "waiting on @scope/upstream@1.2.0 · re-checks every 30s",
+      },
+    ],
+  });
+  const engine = fakeEngine({ "fp-674": [{ userTaskKey: "ut-readiness-pf", elementId: "readiness-escalation-pf", formKey: "26" }] });
+
+  await pollUserTasks(data, engine);
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["ut-readiness-pf"]);
+  assertEquals(byKey["ut-readiness-pf"].element_id, "readiness-escalation-pf");
+  assertEquals(byKey["ut-readiness-pf"].kind_label, "Upstream readiness stalled");
+  assertEquals(byKey["ut-readiness-pf"].subject_type, "feature");
+  assertEquals(byKey["ut-readiness-pf"].subject_key, "o/r#674");
+  assertEquals(byKey["ut-readiness-pf"].subject_title, "Ship the widget");
+  assertEquals(byKey["ut-readiness-pf"].question, "waiting on @scope/upstream@1.2.0 · re-checks every 30s");
+  assertEquals(byKey["ut-readiness-pf"].form_key, "26");
+});
+
+test("pollUserTasks: projects a readiness-escalation wait-gate task on a plan, with the wait-gate label as question (issue #674)", async () => {
+  // The standalone inter-epic wait-gate cell (readiness-gate.bpmn / wait-gate.bpmn) parks a dependent
+  // epic on `readiness-escalation` when its bounded capability wait elapses. It surfaces on the plan
+  // subject; the question derivation leans on the wait-gate projection (`plans.wait_gate_label`).
+  const { data, stores } = memData({
+    plans: [
+      {
+        plan_key: "o/r#700",
+        status: "dispatched",
+        process_key: "pp-700",
+        issue_url: "https://github.com/o/r/issues/700",
+        title: "Dependent epic",
+        wait_gate: "escalated",
+        wait_gate_label: "escalated · still waiting on @scope/producer@2.0.0 after 24h",
+      },
+    ],
+  });
+  const engine = fakeEngine({ "pp-700": [{ userTaskKey: "ut-readiness", elementId: "readiness-escalation" }] });
+
+  await pollUserTasks(data, engine);
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["ut-readiness"]);
+  assertEquals(byKey["ut-readiness"].element_id, "readiness-escalation");
+  assertEquals(byKey["ut-readiness"].kind_label, "Readiness escalation");
+  assertEquals(byKey["ut-readiness"].subject_type, "plan");
+  assertEquals(byKey["ut-readiness"].subject_key, "o/r#700");
+  assertEquals(byKey["ut-readiness"].question, "escalated · still waiting on @scope/producer@2.0.0 after 24h");
+});
+
 test("pollUserTasks: projects a merge-loop wait-merge-answer escalation into user_tasks as \"PR merge\"", async () => {
   // During the merge phase a PR's process_key points at its merge-loop instance; the merge escalation
   // parks on a native `wait-merge-answer` userTask (#256) and writes the SAME `escalations` row the

package/app/service.ts

@@ -99,6 +99,9 @@ import {
   PR_WAIT_ANSWER_ELEMENT,
   PR_WAIT_MERGE_ANSWER_ELEMENT,
   prEscalations,
+  READINESS_ESCALATION_ELEMENT,
+  READINESS_ESCALATION_PF_ELEMENT,
+  readinessEscalationQuestion,
   reconcileUserTasks,
   TRIAL_MERGE_ELEMENT,
   toOpenEscalation,
@@ -2652,15 +2655,19 @@ export async function pollUserTasks(
     url?: string | null;
     deliveryLabel?: string | null;
     conformanceSummary?: string | null;
+    /** The subject's at-a-glance "waiting on <capability> · …" rollup, denormalised for the readiness
+     *  escalation question (issue #674): the wait-gate projection on `plans.wait_gate_label`, or the
+     *  feature run's `delivery_label` for the inline preflight. */
+    waitGateLabel?: string | null;
   }
   const subjectByInstance = new Map<string, Subject>();
   for (const run of await featureRuns(data).all()) {
     if (run.process_key) {
-      subjectByInstance.set(run.process_key, { type: "feature", key: run.feature_key, title: run.title, url: run.issue_url, deliveryLabel: run.delivery_label });
+      subjectByInstance.set(run.process_key, { type: "feature", key: run.feature_key, title: run.title, url: run.issue_url, deliveryLabel: run.delivery_label, waitGateLabel: run.delivery_label });
     }
   }
   for (const plan of await plans(data).all()) {
-    if (plan.process_key) subjectByInstance.set(plan.process_key, { type: "plan", key: plan.plan_key, title: plan.title, url: plan.issue_url });
+    if (plan.process_key) subjectByInstance.set(plan.process_key, { type: "plan", key: plan.plan_key, title: plan.title, url: plan.issue_url, waitGateLabel: plan.wait_gate_label });
   }
   for (const pr of await prs(data).all()) {
     if (pr.process_key) subjectByInstance.set(pr.process_key, { type: "pr", key: pr.pr_key, title: pr.title, url: pr.url });
@@ -2687,6 +2694,8 @@ export async function pollUserTasks(
     [PLAN_REVIEW_ELEMENT]: "plan",
     [TRIAL_MERGE_ELEMENT]: "plan",
     [CONFORMANCE_ESCALATION_ELEMENT]: "plan",
+    [READINESS_ESCALATION_PF_ELEMENT]: "feature",
+    [READINESS_ESCALATION_ELEMENT]: "plan",
     [PR_WAIT_ANSWER_ELEMENT]: "pr",
     [PR_WAIT_MERGE_ANSWER_ELEMENT]: "pr",
   };
@@ -2744,6 +2753,13 @@ export async function pollUserTasks(
       case CONFORMANCE_ESCALATION_ELEMENT:
         question = conformanceEscalationQuestion(subj ? { summary: subj.conformanceSummary } : undefined);
         break;
+      case READINESS_ESCALATION_PF_ELEMENT:
+      case READINESS_ESCALATION_ELEMENT:
+        // The leading readiness/capability gate stalled: surface WHAT it is waiting on. The wait-gate
+        // projection already rendered that clause on the subject row (`plans.wait_gate_label`, or the
+        // feature preflight's `delivery_label`), with a static readiness-stalled fallback (#674).
+        question = readinessEscalationQuestion(subj?.waitGateLabel ?? null);
+        break;
     }
     return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? null, question, processKey: processInstanceKey, formKey: resolvedFormKey };
   };
@@ -2766,22 +2782,36 @@ export async function pollUserTasks(
       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 "").
+    // Reduced-capability fallback (no raw-REST surface): typed-seam per-active-subject scan. The typed
+    // seam now carries the parent/root keys (`@nanobpm/urban` ≥ 0.90 / `@nanobpm/engine-wasm` ≥ 0.8.6,
+    // Magikcraft/nano-bpm#977), so — unlike the pre-#646 tracked-only path — a task parked inside a
+    // callActivity CHILD instance (the shared `human-escalation`/`implement-cell` cells, ADR 0006 S4)
+    // correlates back to this tracked subject too: each subject instance is scanned BOTH directly (its
+    // own top-level escalations) AND across its whole callActivity hierarchy via the `rootProcessInstanceKey`
+    // filter (its native-child cell escalations), so an `implement-cell` → `human-escalation` grandchild
+    // escalation surfaces on this path exactly as it does on the raw-REST sweep (issue #633/#646). Deduped
+    // by `userTaskKey` in `project`, so the direct + hierarchy passes never double-project a shared task.
     const seen = new Set<string>();
     const scanInstance = async (processKey: string | null | undefined) => {
       if (!processKey || seen.has(processKey)) return;
       seen.add(processKey);
-      let tasks: { userTaskKey: string; elementId?: string; formKey?: string }[];
+      let direct: { userTaskKey: string; elementId?: string; formKey?: string }[];
+      let hierarchy: { userTaskKey: string; elementId?: string; processInstanceKey?: string; rootProcessInstanceKey?: string; formKey?: string }[];
       try {
-        tasks = await engine.openUserTasks({ processInstanceKey: processKey });
+        [direct, hierarchy] = await Promise.all([
+          engine.openUserTasks({ processInstanceKey: processKey }),
+          engine.openUserTasks({ rootProcessInstanceKey: processKey }),
+        ]);
       } catch (err) {
         console.error(`[poller] user tasks (${processKey}): ${err}`);
         return;
       }
-      for (const t of tasks) await project(t.elementId, t.userTaskKey, processKey, "", t.formKey ?? "");
+      // Direct tasks park on the subject's OWN instance, so their process/root instance IS `processKey`.
+      for (const t of direct) await project(t.elementId, t.userTaskKey, processKey, processKey, t.formKey ?? "");
+      // Hierarchy tasks carry their own (child) `processInstanceKey` and the shared `rootProcessInstanceKey`
+      // (= this subject) the engine reports, so `contextFor` correlates the child-instance task to the
+      // tracked subject via the root rather than stranding it as an orphan.
+      for (const t of hierarchy) await project(t.elementId, t.userTaskKey, t.processInstanceKey ?? processKey, t.rootProcessInstanceKey ?? 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);
@@ -2851,27 +2881,32 @@ export async function pollUserTasks(
     // 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)));
+    // `desired`). The typed seam now carries the parent/root keys (`@nanobpm/urban` ≥ 0.90, #646), so BOTH
+    // surfaces walk the hierarchy: the raw-REST surface enumerates descendant instances, and the
+    // reduced-capability seam (no `rest`) confirms via the `rootProcessInstanceKey` filter — a
+    // root-scoped `openUserTasks` reports every open task across the run's whole tree in one query. Any
+    // 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).
     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;
+    try {
+      if (rest) {
+        const confirmInstances = [run.process_key, ...(await searchDescendantInstanceKeys(rest.base, rest.headers, run.process_key))];
+        for (const instanceKey of confirmInstances) {
+          const openTasks = await engine.openUserTasks({ processInstanceKey: instanceKey });
+          if (openTasks.some((t) => t.elementId === FEATURE_ESCALATION_ELEMENT || t.elementId === HUMAN_ESCALATION_ELEMENT)) {
+            stillParked = true;
+            break;
+          }
+        }
+      } else {
+        // Reduced path: one root-scoped query covers the parent AND every callActivity descendant.
+        const openTasks = await engine.openUserTasks({ rootProcessInstanceKey: run.process_key });
+        stillParked = openTasks.some((t) => t.elementId === FEATURE_ESCALATION_ELEMENT || t.elementId === HUMAN_ESCALATION_ELEMENT);
       }
+    } catch (err) {
+      console.error(`[poller] escalated-run self-heal (${run.feature_key} @ ${run.process_key}): ${err}`);
+      queryErrored = true;
     }
     if (queryErrored || stillParked) continue;
     await featureRuns(data).update(run.feature_key, { status: "running", updated_at: at });