@nanobpm/nano-workforce 0.111.1 → 0.113.0

package/app/deliveryHuman.ts

@@ -0,0 +1,371 @@
+// nano-workforce — the `human` delivery-graph node (ADR 0005, slice S3). A `human` node promotes
+// ADR 0002's user-task+form machinery from an *exception* (something broke) to a *scheduled node* (a
+// planned "now do X" stop that BLOCKS its dependents, is answerable by a human OR an agent — ADR 0046
+// — is SLA-bounded so it nags and cannot silently wedge the graph, and can EMIT a typed fact its form
+// captures which late-binds downstream). It is the emit-side of #263's emit-vs-poll dual: a *human*
+// emitter is the same shape as an automated one (the `capability`/`pr` probe's `resolvedArtifact`
+// bind), which is what unifies human and automated steps in one graph.
+//
+// This module owns the PURE, side-effect-free machinery the compiler (S1, author-time) and the
+// runner (S4, runtime) reuse — it never itself creates a user task or completes one. Execution stays
+// engine-native (Decision 2): the human node's body is the deployed `delivery-human` `bpmn:userTask`
+// (`resources/processes/delivery-human.bpmn`, an SLA-bounded scheduled user task), completion routes
+// through the ONE canonical completer (`completeEscalationAsAgent`/`completeEscalationAsHuman`,
+// `app/agentCompletion.ts`) because `DELIVERY_HUMAN_ELEMENT` is registered in
+// `ESCALATION_TASK_ELEMENTS`, and the emitted fact threads downstream via the #289 brief-appender /
+// bound-output pattern (`renderResolvedDepsBrief` / the `caps-resolved` → `appendPrompt` recipe).
+//
+// The three pure concerns:
+//   1. FORM RESOLUTION — specific-else-generic (Decision 4): an explicit `human.formKey` on the node,
+//      else a form SELECTED by node category (derived from the node's typed emits), else a GENERIC
+//      fallback form that STILL captures a typed emitted fact — so every human node can emit even with
+//      no bespoke form. A runtime agent-form-router is a GATED exception: it fires ONLY when a node
+//      activates with no statically resolvable form (multiple heterogeneous emits, no explicit/bespoke
+//      form), never in the common path — the same "deterministic default, agent judgment as the escape
+//      hatch" grain as the capability probe's empirical verifier.
+//   2. TYPED EMIT — validate + coerce the completed form output against the node's declared `emits[]`
+//      (Decision 3/4 — binds are validated, not stringly), producing the typed facts the node hands
+//      forward. A "click done" node declares no emits — the degenerate no-emit case.
+//   3. LATE-BINDING — render the emitted facts into a downstream node's brief (`renderHumanEmitBrief`,
+//      mirroring `renderResolvedDepsBrief`) and into a qualified bind map keyed `<nodeId>.<fact>`
+//      (`humanEmitBind`, mirroring the probe `bind`) so a downstream `capability`/`npm`/`pr` edge
+//      binds and pins exactly the value the human handed forward.
+import type { DeliveryFact, DeliveryNodeHuman } from "../nano-generated/api-io.d.ts";
+import { DELIVERY_FACT_TYPES, type DeliveryFactType, FACT_NAME_MAX_LENGTH, FACT_NAME_PATTERN } from "./deliveryGraph.ts";
+
+/** The single BPMN `bpmn:userTask` element id every `human` delivery-graph node schedules its work
+ *  as (`resources/processes/delivery-human.bpmn`). One reusable engine-native body, instantiated once
+ *  per human node (mirroring the one `readiness-gate` process instantiated per `wait` node). It is
+ *  registered in `ESCALATION_TASK_ELEMENTS` (`app/agentCompletion.ts`) so a human OR an agent
+ *  (ADR 0046) can complete it through the ONE canonical `complete-user-task` / `agent-complete` door,
+ *  and in `USER_TASK_KIND_LABELS` (`app/userTasks.ts`) so it surfaces on the Tasks inbox. */
+export const DELIVERY_HUMAN_ELEMENT = "delivery-human-task";
+
+/** The GENERIC fallback form (Decision 4, step 3): captures ONE typed value into the node's single
+ *  declared emitted fact, so a human node with no explicit/category form can STILL emit downstream. */
+export const GENERIC_HUMAN_FORM = "delivery-human-generic";
+
+/** The "click done" category form: a degenerate no-emit acknowledgement ("now do X" → done). */
+export const HUMAN_ACK_FORM = "delivery-human-ack";
+
+/** The manual-publish category form: captures a `resolvedArtifact` (`pkg@version`) — the motivating
+ *  case where a human hands a just-published version forward to a downstream `capability`/`npm`/`pr`
+ *  edge. */
+export const HUMAN_PUBLISH_FORM = "delivery-human-publish";
+
+/** A human node's derived CATEGORY — a coarse classification of what the node emits, used to SELECT a
+ *  bespoke form (Decision 4, step 2) without the author naming one. Derived from the node's typed
+ *  `emits[]` so the same typed-fact declaration that drives late-binding also drives form selection —
+ *  one source of truth, no second author-facing knob (the frozen S0 `human` config carries only
+ *  `formKey`/`prompt`). `null` ⇒ no bespoke category form applies (fall through to generic/router). */
+export type HumanNodeCategory = "ack" | "publish";
+
+/** Category → its bespoke form. Kept as the single source of truth for "which form a category selects"
+ *  so {@link resolveHumanForm} and any preview/compile step agree. */
+export const HUMAN_CATEGORY_FORMS: Readonly<Record<HumanNodeCategory, string>> = {
+  ack: HUMAN_ACK_FORM,
+  publish: HUMAN_PUBLISH_FORM,
+};
+
+/** How a human node's form was resolved. `explicit` — the node named a `human.formKey`; `category` —
+ *  a form was selected by the node's derived category; `generic` — the typed-emit-capturing fallback;
+ *  `agent-router` — NOTHING statically resolved, so a runtime agent must pick/assemble one (the gated
+ *  exception). */
+export type HumanFormSource = "explicit" | "category" | "generic" | "agent-router";
+
+/** The resolved form for a human node (Decision 4). `formKey` is the `.form` to attach — `null` ONLY
+ *  for `agent-router`, where the runtime supplies it. `category` records the derived category when one
+ *  applied. `reason` is a human-readable one-liner for the compiled preview. */
+export interface HumanFormResolution {
+  readonly source: HumanFormSource;
+  readonly formKey: string | null;
+  readonly category: HumanNodeCategory | null;
+  readonly emits: readonly DeliveryFact[];
+  readonly reason: string;
+}
+
+/** A typed fact a completed human node hands forward — its declared `name`/`type` plus the validated,
+ *  canonically-serialised `value` (a string, like the probe `bind`, so it threads uniformly into
+ *  prompts, messages, and qualified bind maps). */
+export interface BoundFact {
+  readonly name: string;
+  readonly type: DeliveryFactType;
+  readonly value: string;
+}
+
+/** The outcome of binding a completed form's output to a node's declared emits: the typed `facts` in
+ *  declaration order plus any path-qualified `errors` (a missing/ill-typed declared fact). An empty
+ *  `emits` yields `{ facts: [], errors: [] }` — the degenerate no-emit "click done" case. */
+export interface HumanEmitResult {
+  readonly facts: readonly BoundFact[];
+  readonly errors: readonly string[];
+}
+
+/** Narrow an untyped value to a plain object so its fields can be read defensively. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** True when `value` is one of the closed set of delivery fact types (a type guard, so the pure
+ *  form/emit logic narrows without an `as` assertion). */
+function isDeliveryFactType(value: unknown): value is DeliveryFactType {
+  return typeof value === "string" && DELIVERY_FACT_TYPES.some((t) => t === value);
+}
+
+/** Normalise a human node's `emits[]` to the well-formed, typed declarations, dropping anything the
+ *  S0 validator would already have rejected (a non-record entry, a blank name, a name that is not a
+ *  dot-free identifier within the 128-char cap, a duplicate name, or an unknown type) so the pure
+ *  form/emit logic never trips on a malformed declaration — the graph is validated upstream by
+ *  `validateDeliveryGraph`, this is defence in depth. Fact-name pattern/length are the SAME canonical
+ *  constants the validator enforces (`FACT_NAME_PATTERN`/`FACT_NAME_MAX_LENGTH`), so a dotted /
+ *  over-long / duplicate name can't slip through here and make `<nodeId>.<fact>` binding ambiguous. */
+export function normalizeEmits(node: Pick<DeliveryNodeHuman, "emits">): DeliveryFact[] {
+  const raw = node.emits;
+  if (!Array.isArray(raw)) return [];
+  const facts: DeliveryFact[] = [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    if (!isRecord(entry)) continue;
+    const name = entry.name;
+    const type = entry.type;
+    if (typeof name !== "string" || name.length === 0) continue;
+    if (name.length > FACT_NAME_MAX_LENGTH || !FACT_NAME_PATTERN.test(name)) continue;
+    if (seen.has(name)) continue;
+    if (!isDeliveryFactType(type)) continue;
+    seen.add(name);
+    facts.push({ name, type, ...(typeof entry.description === "string" ? { description: entry.description } : {}) });
+  }
+  return facts;
+}
+
+/** Derive a human node's CATEGORY from its typed emits (Decision 4, step 2), or `null` when no bespoke
+ *  category form applies:
+ *   - `ack` — the node emits NOTHING (a "click done" acknowledgement).
+ *   - `publish` — the node emits EXACTLY ONE `artifact` fact (a `pkg@version` handle — the manual-
+ *     publish-hands-a-version-forward case), which the bespoke publish form captures as a
+ *     `resolvedArtifact`. A lone `version` (a BARE version, e.g. `1.4.0`) does NOT map here: the
+ *     publish form captures a `pkg@version` into `resolvedArtifact`, which fails `version` coercion in
+ *     {@link bindHumanEmits} — so a single `version` falls through to the generic single-value form
+ *     (which captures a bare `value`, validated against the `version` type).
+ *   - `null` — a single non-artifact scalar/url/version fact (the generic fallback captures it), OR
+ *     two-or-more facts (no bespoke or generic single-value form can hold them → the agent-router
+ *     territory).
+ *  Kept coarse ON PURPOSE: bespoke category forms are a deterministic convenience, not an open
+ *  taxonomy; anything they don't cover falls through to the generic fallback or the gated router. */
+export function deriveHumanCategory(emits: readonly DeliveryFact[]): HumanNodeCategory | null {
+  if (emits.length === 0) return "ack";
+  if (emits.length === 1 && emits[0].type === "artifact") return "publish";
+  return null;
+}
+
+/** Resolve which form a human node uses, specific-else-generic (ADR 0005 Decision 4). Preference:
+ *    1. `explicit`     — the node carries a non-blank `human.formKey`.
+ *    2. `category`     — the node's derived category selects a bespoke form ({@link deriveHumanCategory}).
+ *    3. `generic`      — the node emits ≤1 fact, captured by the generic typed-emit fallback form.
+ *    4. `agent-router` — NOTHING statically resolved (≥2 heterogeneous emits, no explicit/bespoke
+ *                        form): a runtime agent must pick/assemble a form. This is the GATED escape
+ *                        hatch — it fires ONLY here, never in the common path.
+ *  Pure and total (never throws): the graph is shape/semantic-validated upstream, and malformed emits
+ *  are normalised away, so this always returns a resolution. Author-time callers (the S1 compiler)
+ *  attach `formKey` deterministically so the resolved form is visible in the preview; only the
+ *  `agent-router` case defers to runtime. */
+export function resolveHumanForm(node: Pick<DeliveryNodeHuman, "emits" | "human">): HumanFormResolution {
+  const emits = normalizeEmits(node);
+  const explicit = node.human?.formKey;
+  if (typeof explicit === "string" && explicit.trim().length > 0) {
+    return {
+      source: "explicit",
+      formKey: explicit.trim(),
+      category: null,
+      emits,
+      reason: `explicit form "${explicit.trim()}" attached on the node`,
+    };
+  }
+  const category = deriveHumanCategory(emits);
+  if (category !== null) {
+    return {
+      source: "category",
+      formKey: HUMAN_CATEGORY_FORMS[category],
+      category,
+      emits,
+      reason:
+        category === "ack"
+          ? "no emitted fact — the generic acknowledgement (click-done) form"
+          : `emits a single ${emits[0].type} fact — the manual-publish form (captures a resolvedArtifact)`,
+    };
+  }
+  if (emits.length <= 1) {
+    return {
+      source: "generic",
+      formKey: GENERIC_HUMAN_FORM,
+      category: null,
+      reason: `emits a single ${emits[0].type} fact — the generic typed-emit fallback form`,
+      emits,
+    };
+  }
+  return {
+    source: "agent-router",
+    formKey: null,
+    category: null,
+    emits,
+    reason:
+      `emits ${emits.length} typed facts and carries no explicit/bespoke form — no static form can ` +
+      "capture them, so a runtime agent-form-router must assemble one (the gated exception)",
+  };
+}
+
+/** True when a human node resolves to the gated runtime agent-form-router — i.e. nothing statically
+ *  resolved. A thin predicate over {@link resolveHumanForm} so callers can branch without re-deriving. */
+export function needsAgentFormRouter(node: Pick<DeliveryNodeHuman, "emits" | "human">): boolean {
+  return resolveHumanForm(node).source === "agent-router";
+}
+
+/** The canonical form-field keys a bespoke/generic form captures its single typed value under, tried
+ *  (in addition to the fact's own name) when binding a single-fact node's output. The generic form
+ *  captures `value`; the publish form captures `resolvedArtifact`. */
+const CANONICAL_VALUE_KEYS = ["resolvedArtifact", "value"] as const;
+
+/** The ONE accepted shape of a bare version string (an optional `v` then a digit-led `[\w.+-]` run,
+ *  e.g. `1.4.0`, `v2.0.0-rc.1`). The single source of truth shared by the `version` fact type AND the
+ *  version segment of an `artifact` handle — so a `pkg@version` artifact validates its version the
+ *  same way a bare `version` does, with no second notion of "valid version" to drift. */
+const VERSION_PATTERN = /^v?\d[\w.+-]*$/;
+
+/** Coerce + validate one raw form value against a declared fact type, returning the canonical string
+ *  serialisation or an error message. Typed so a bind is validated, not stringly (Decision 3/4): an
+ *  `artifact` must be `pkg@version` (with a well-formed version segment), a `version` a bare version, a
+ *  `url` a parseable location, a `number` finite, a `boolean` a real boolean. */
+function coerceFactValue(type: DeliveryFactType, raw: unknown): { value: string } | { error: string } {
+  switch (type) {
+    case "string": {
+      if (typeof raw !== "string" || raw.trim() === "") return { error: "expected a non-empty string" };
+      // Return the trimmed value, mirroring the other string-like types (version/artifact/url) so the
+      // canonical serialisation does not depend on incidental surrounding whitespace.
+      return { value: raw.trim() };
+    }
+    case "number": {
+      const n = typeof raw === "number" ? raw : typeof raw === "string" && raw.trim() !== "" ? Number(raw) : Number.NaN;
+      if (!Number.isFinite(n)) return { error: "expected a finite number" };
+      return { value: String(n) };
+    }
+    case "boolean": {
+      if (typeof raw === "boolean") return { value: String(raw) };
+      // Trim before validating, mirroring the other string-like types (version/artifact/url) so a
+      // boolean captured via the generic textfield (e.g. " true ") is not needlessly brittle.
+      const trimmed = typeof raw === "string" ? raw.trim() : raw;
+      if (trimmed === "true" || trimmed === "false") return { value: trimmed };
+      return { error: "expected a boolean (true/false)" };
+    }
+    case "version": {
+      if (typeof raw !== "string" || !VERSION_PATTERN.test(raw.trim())) {
+        return { error: "expected a version string (e.g. 1.4.0)" };
+      }
+      return { value: raw.trim() };
+    }
+    case "artifact": {
+      if (typeof raw !== "string") return { error: "expected a pkg@version artifact handle" };
+      const at = raw.trim().lastIndexOf("@");
+      const name = raw.trim().slice(0, at);
+      const version = raw.trim().slice(at + 1);
+      if (at <= 0 || name.length === 0 || version.length === 0 || !VERSION_PATTERN.test(version)) {
+        return { error: "expected a pkg@version artifact handle (e.g. @nanobpm/urban@0.54.0)" };
+      }
+      return { value: raw.trim() };
+    }
+    case "url": {
+      if (typeof raw !== "string" || raw.trim() === "") return { error: "expected a URL" };
+      try {
+        new URL(raw.trim());
+      } catch {
+        return { error: "expected a valid URL (with a scheme)" };
+      }
+      return { value: raw.trim() };
+    }
+    default:
+      return { error: `unknown fact type "${type}"` };
+  }
+}
+
+/** Bind a completed human node's form `output` to its declared `emits[]` (Decision 3/4). For each
+ *  declared fact, read its value from the output — preferring the fact's own `name` key, then, for a
+ *  single-fact node, the canonical capture keys the generic/publish forms use (`resolvedArtifact` /
+ *  `value`) — and validate/coerce it against the fact's type. Returns the typed facts in declaration
+ *  order plus one error per missing/ill-typed declared fact. A node with no declared emits yields no
+ *  facts and no errors (the degenerate "click done" case) regardless of what the form captured.
+ *
+ *  This is the typed-emit contract the runner (S4) enforces on completion before threading the facts
+ *  downstream via {@link humanEmitBind} / {@link renderHumanEmitBrief} — the emit-side of #263. */
+export function bindHumanEmits(
+  emits: readonly DeliveryFact[],
+  output: Record<string, unknown> | null | undefined,
+): HumanEmitResult {
+  const out = isRecord(output) ? output : {};
+  const facts: BoundFact[] = [];
+  const errors: string[] = [];
+  const single = emits.length === 1;
+  for (const fact of emits) {
+    let raw = out[fact.name];
+    if (raw === undefined && single) {
+      for (const key of CANONICAL_VALUE_KEYS) {
+        if (out[key] !== undefined) {
+          raw = out[key];
+          break;
+        }
+      }
+    }
+    if (raw === undefined || raw === null) {
+      errors.push(`emits.${fact.name}: no value captured for the declared ${fact.type} fact`);
+      continue;
+    }
+    const coerced = coerceFactValue(fact.type, raw);
+    if ("error" in coerced) {
+      errors.push(`emits.${fact.name}: ${coerced.error}`);
+      continue;
+    }
+    facts.push({ name: fact.name, type: fact.type, value: coerced.value });
+  }
+  return { facts, errors };
+}
+
+/** Build the qualified bind map a human node's emitted facts publish downstream, keyed exactly as a
+ *  delivery edge references them — `<nodeId>.<fact>` (mirroring the probe `bind: Record<string,string>`
+ *  and the `capability` kind's `resolvedArtifact`). A downstream edge `from: "<nodeId>.<fact>"` binds
+ *  and PINS the human-handed value from this map. Empty for a no-emit node. */
+export function humanEmitBind(nodeId: string, facts: readonly BoundFact[]): Record<string, string> {
+  const bind: Record<string, string> = {};
+  for (const fact of facts) bind[`${nodeId}.${fact.name}`] = fact.value;
+  return bind;
+}
+
+/** Neutralise a human-submitted value before it is embedded in a Markdown inline-code span in the
+ *  brief. A raw backtick would terminate the span (corrupting the brief and letting free-form form
+ *  text inject unintended prompt content into the downstream agent's prompt), and a newline would
+ *  break the span; collapse both. Display-only — the authoritative value published downstream via
+ *  {@link humanEmitBind} is untouched, so the pinned contract is unaffected. */
+function inlineCodeSafe(value: string): string {
+  return value.replace(/`/g, "'").replace(/\r?\n/g, " ");
+}
+
+/** Render the "human-emitted facts" brief appended to a downstream node's prompt once a human node
+ *  completes and hands its typed facts forward (#289 §3), mirroring `renderResolvedDepsBrief`. It pins
+ *  each `name → value` the human declared + captured so a downstream agent/edge consumes EXACTLY that
+ *  value — no re-derivation, no human re-entry. Returns "" for a no-emit node so callers concatenate
+ *  unconditionally (the same `if X = null then "" else X` FEEL convention as the other briefs). */
+export function renderHumanEmitBrief(facts: readonly BoundFact[]): string {
+  if (facts.length === 0) return "";
+  const lines = [
+    "",
+    "",
+    "---",
+    "",
+    "**Human-emitted facts (authoritative — a scheduled human step handed these forward):**",
+    "",
+    "A `human` node upstream captured and emitted the typed values below. Consume/pin exactly these —",
+    "do NOT re-derive, float, or re-request them:",
+    "",
+  ];
+  for (const fact of facts) lines.push(`- \`${fact.name}\` (${fact.type}) → \`${inlineCodeSafe(fact.value)}\``);
+  lines.push("");
+  lines.push("These are the contract the human handed forward; a different value is a different run.");
+  return lines.join("\n");
+}

package/app/escalationTaxonomy.test.ts

@@ -80,7 +80,7 @@ test("merge-protocol: only a `ui` land method is decision-required; the rest are
   }
 });
 
-// --- task (plan-fanout w_gw "escalated?") ---
+// --- task (plan-fanout w_gw "clean terminal?" — the implement-stage escalation net, #360) ---
 
 test("task: status=escalated with an answerable question is decision-required; blank is none", () => {
   assertEquals(classifyEscalation({ kind: "task", question: "which approach?" }), "decision-required");

package/app/escalationTaxonomy.ts

@@ -39,8 +39,10 @@ export type EscalationKind =
   | "dead-end-base"
   // `mergeProtocol` (app/mergeProtocol.ts) — the repo's declared land method.
   | "merge-protocol"
-  // plan-fanout `w_gw` "escalated?" gateway — an implementation agent reported
-  // `status = "escalated"` with a question.
+  // 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.
   | "task";
 
 /** Everything the classifier may need from any raise site. Each field is consumed only by the

package/app/planFanoutCleanTerminal.test.ts

@@ -0,0 +1,40 @@
+// 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.
+//
+// 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 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] ?? "";
+
+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("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("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");
+});

package/app/pollUserTasks.test.ts

@@ -131,6 +131,36 @@ test("pollUserTasks: projects feature / plan-review / trial-merge / PR-wait esca
   assertEquals(byKey["ut-pr"].subject_title, "Resolve the reviews");
 });
 
+test("pollUserTasks: projects a feature-escalation that lands on a plan-fanout plan instance (issue #358)", async () => {
+  // plan-fanout embeds each wave slice as a multi-instance `implement` subprocess, so a slice that
+  // escalates parks on the `feature-escalation` user task on the PLAN-ROOT process instance — never on
+  // a standalone `feature_runs` instance. The feature scan above only walks `feature_runs`, so before
+  // #358 the plan scan's hardcoded {plan-review, trial-merge} whitelist silently dropped it and the
+  // escalation was invisible in the Tasks inbox (the instance-19153 orphan). The plan scan must project
+  // EVERY open user-task element in the canonical registry, keyed to the epic (plan) subject, sourcing
+  // the question from the `feature_escalations` audit log the escalate arm writes (keyed by plan_key).
+  const { data, stores } = memData({
+    plans: [
+      { plan_key: "o/r#64", status: "dispatched", process_key: "pp-64", issue_url: "https://github.com/o/r/issues/64", title: "Learn BPMN scaffold" },
+    ],
+    feature_escalations: [
+      { id: 1, feature_key: "o/r#64", question: "the agent returned no machine-readable result — enrol the PR?", created_at: "2025-01-01T00:00:00.000Z", job_key: "j1" },
+    ],
+  });
+  const engine = fakeEngine({ "pp-64": [{ userTaskKey: "ut-embedded-feat", elementId: "feature-escalation" }] });
+
+  await pollUserTasks(data, engine);
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["ut-embedded-feat"]);
+  assertEquals(byKey["ut-embedded-feat"].element_id, "feature-escalation");
+  assertEquals(byKey["ut-embedded-feat"].kind_label, "Feature escalation");
+  assertEquals(byKey["ut-embedded-feat"].subject_type, "plan");
+  assertEquals(byKey["ut-embedded-feat"].subject_key, "o/r#64");
+  assertEquals(byKey["ut-embedded-feat"].subject_title, "Learn BPMN scaffold");
+  assertEquals(byKey["ut-embedded-feat"].question, "the agent returned no machine-readable result — enrol the PR?");
+});
+
 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
@@ -328,3 +358,181 @@ test("pollUserTasks: an instance whose only task is COMPLETED surfaces no row",
 
   assertEquals(stores.user_tasks ?? [], []);
 });
+
+// ── Engine-first sweep (issue #358) ────────────────────────────────────────────────────────────────
+// When the raw-REST surface is available (production always supplies it), the projection's source of
+// truth for WHICH escalations are open is the ENGINE, not the tracked subject set: every open escalation
+// the engine reports is surfaced — even on an instance NO tracked subject row references (an
+// orphaned/untracked instance, the reported 19153 case) — enriched by a subject row when one exists and
+// by a per-kind fallback when it does not. These drive the sweep over a stubbed Camunda-8
+// `/v2/user-tasks/search`, the raw surface that (unlike the typed `openUserTasks` seam) carries each
+// task's `processInstanceKey`.
+
+/** 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 };
+
+/** 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
+ *  call is loud. Returns a restore fn. */
+function stubUserTaskSearch(tasks: RawTask[]): () => 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("/user-tasks/search")) return new Response("not found", { status: 404 });
+    const body = JSON.parse(init?.body ?? "{}");
+    const from: number = body?.page?.from ?? 0;
+    const limit: number = body?.page?.limit ?? 100;
+    return new Response(JSON.stringify({ items: tasks.slice(from, from + limit) }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as typeof fetch;
+  return () => {
+    globalThis.fetch = orig;
+  };
+}
+
+const REST = { restAddress: "http://engine.test/v2" };
+
+test("pollUserTasks (engine-first): surfaces an escalation on an UNTRACKED/orphaned instance — the 19153 case (issue #358)", async () => {
+  // No `feature_runs`/`plans`/`pull_requests` row references instance 19153, yet the engine reports its
+  // `feature-escalation` (key 27337) open. Before #358 the subject-tracking-gated scan dropped it and the
+  // operator could never see nor answer it. The engine-first sweep surfaces it, keyed to a stable
+  // non-blank fallback subject (the instance) so the row renders and stays answerable.
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "27337", elementId: "feature-escalation", processInstanceKey: "19153", 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), ["27337"]);
+  assertEquals(byKey["27337"].element_id, "feature-escalation");
+  assertEquals(byKey["27337"].kind_label, "Feature escalation");
+  assertEquals(byKey["27337"].subject_type, "feature");
+  assertEquals(byKey["27337"].subject_key, "19153"); // fallback to the instance — non-blank so it renders
+  assertEquals(byKey["27337"].subject_title, "19153");
+  assertEquals(byKey["27337"].question, null); // no tracked audit source for an orphan → null, still listed
+});
+
+test("pollUserTasks (engine-first): orphaned plan-review and PR-wait escalations are surfaced too (issue #358)", async () => {
+  // Same failure class across aggregates: a `plan-review-decision` with no `plans` row and a `wait-answer`
+  // with no `pull_requests` row are each surfaced, bucketed to the aggregate their kind implies.
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-orphan-plan", elementId: "plan-review-decision", processInstanceKey: "pi-1", state: "CREATED" },
+    { userTaskKey: "ut-orphan-pr", elementId: "wait-answer", processInstanceKey: "pi-2", 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).sort(), ["ut-orphan-plan", "ut-orphan-pr"]);
+  assertEquals(byKey["ut-orphan-plan"].subject_type, "plan");
+  assertEquals(byKey["ut-orphan-plan"].subject_key, "pi-1");
+  assertEquals(byKey["ut-orphan-pr"].subject_type, "pr");
+  assertEquals(byKey["ut-orphan-pr"].kind_label, "PR review");
+});
+
+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: [
+      { 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" },
+    ],
+    plans: [
+      { plan_key: "o/r#20", status: "dispatched", process_key: "pp-20", issue_url: "https://github.com/o/r/issues/20", title: "Broaden the epic scope" },
+    ],
+    plan_reviews: [
+      { plan_key: "o/r#20", epoch: 0, round: 1, approved: 0, findings: "scope too broad", created_at: "2025-01-02T00:00:00.000Z" },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-feat", elementId: "feature-escalation", processInstanceKey: "fp-10", state: "CREATED" },
+    { userTaskKey: "ut-plan", elementId: "plan-review-decision", processInstanceKey: "pp-20", 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).sort(), ["ut-feat", "ut-plan"]);
+  assertEquals(byKey["ut-feat"].subject_key, "o/r#10");
+  assertEquals(byKey["ut-feat"].subject_title, "Add the framework selector");
+  assertEquals(byKey["ut-feat"].question, "which framework?");
+  assertEquals(byKey["ut-plan"].subject_title, "Broaden the epic scope");
+  assertEquals(byKey["ut-plan"].question, "scope too broad");
+});
+
+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
+  // the wire `state` filter is ignored.
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-internal", elementId: "some-internal-task", processInstanceKey: "pi-9", state: "CREATED" },
+    { userTaskKey: "ut-done", elementId: "feature-escalation", processInstanceKey: "pi-8", state: "COMPLETED" },
+    { userTaskKey: "ut-live", elementId: "feature-escalation", processInstanceKey: "pi-7", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const keys = (stores.user_tasks ?? []).map((r) => r.user_task_key);
+  assertEquals(keys, ["ut-live"]);
+});
+
+test("pollUserTasks (engine-first): an answered task (no longer open) is deleted on the next pass", async () => {
+  // Feed the engine-derived desired set to the unchanged reconcile: a persisted row whose task the engine
+  // no longer reports open is deleted, so `showCount` tracks live work — identical to the scan path.
+  const { data, stores } = memData({
+    user_tasks: [
+      { user_task_key: "ut-gone", element_id: "wait-answer", kind_label: "PR review", subject_type: "pr", subject_key: "o/r#30", subject_url: null, question: null, process_key: "rp-30", created_at: "2025-01-01T00:00:00.000Z", updated_at: "2025-01-01T00:00:00.000Z" },
+    ],
+  });
+  const restore = stubUserTaskSearch([]); // engine reports nothing open
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  assertEquals(stores.user_tasks, []);
+});
+
+test("pollUserTasks (engine-first): pages through a large open set (no first-page truncation)", async () => {
+  // Open escalations are normally few, but the sweep must page defensively so a large set is not silently
+  // truncated to the first page. 150 open escalations across a 100-item page size → all 150 projected.
+  const { data, stores } = memData({});
+  const tasks: RawTask[] = Array.from({ length: 150 }, (_, i) => ({
+    userTaskKey: `ut-${i}`,
+    elementId: "feature-escalation",
+    processInstanceKey: `pi-${i}`,
+    state: "CREATED",
+  }));
+  const restore = stubUserTaskSearch(tasks);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  assertEquals((stores.user_tasks ?? []).length, 150);
+});