@nanobpm/nano-workforce 0.111.0 → 0.112.0

package/app/github.test.ts

@@ -3,7 +3,8 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
+import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol, type RequiredCheck } from "./mergeProtocol.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -440,6 +441,8 @@ function prState(over: Partial<PrState>): PrState {
     failingChecks: 0,
     failingCheckNames: [],
     presentCheckNames: [],
+    pendingCheckNames: [],
+    checkConclusions: {},
     totalChecks: 0,
     isDraft: false,
     headRefOid: null,
@@ -463,3 +466,224 @@ test("classifyPrLiveness: a closed-not-merged PR is terminal (abandon)", () => {
 test("classifyPrLiveness: a null read (transport hiccup) is unknown — never abandons blind", () => {
   assertEquals(classifyPrLiveness(null), "unknown");
 });
+
+// ── classifyMergeability: protocol-aware required-checks backstop (issue #392) ────────────────────
+//
+// The merge poller must NOT merge a PR whose DECLARED-required check is red, even on a repo that
+// under-specifies its GitHub-required checks (so GitHub reports the PR as UNSTABLE, i.e. "only
+// non-required checks failing" from GitHub's view). `classifyMergeability` now intersects the repo's
+// merge-protocol `requiredChecks[]`/`waitForChecks` against the head's latest-run-per-check
+// conclusions (via `latestRunPerCheck`, preserving the #348 CANCELLED-supersede semantics) as an
+// independent backstop that runs BEFORE the `mergeStateStatus` switch. These are pure unit tests.
+
+// Build a `PrState` with sensible defaults; `over` supplies the fields a case cares about. `over`
+// may pass a `rollup` shorthand (name → conclusion) that we compile into the exact per-check fields
+// `classifyMergeability` reads (present/pending/conclusions), mirroring what `fetchPrState` derives.
+function mergePrState(over: Partial<PrState> & { rollup?: { name: string; conclusion: string }[] } = {}): PrState {
+  const { rollup, ...rest } = over;
+  const base: PrState = {
+    merged: false,
+    state: "open",
+    mergeStateStatus: "CLEAN",
+    failingChecks: 0,
+    failingCheckNames: [],
+    totalChecks: 0,
+    presentCheckNames: [],
+    pendingCheckNames: [],
+    checkConclusions: {},
+    isDraft: false,
+    headRefOid: "abc123",
+  };
+  if (rollup) {
+    const bad = new Set(["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "ERROR"]);
+    const pendingStates = new Set(["", "PENDING", "QUEUED", "IN_PROGRESS", "EXPECTED", "WAITING"]);
+    const present: string[] = [];
+    const pending: string[] = [];
+    const failing: string[] = [];
+    const conclusions: Record<string, string> = {};
+    for (const c of rollup) {
+      const v = c.conclusion.toUpperCase();
+      present.push(c.name);
+      conclusions[c.name] = pendingStates.has(v) ? "" : v;
+      if (pendingStates.has(v)) pending.push(c.name);
+      else if (bad.has(v)) failing.push(c.name);
+    }
+    base.presentCheckNames = present;
+    base.pendingCheckNames = pending;
+    base.checkConclusions = conclusions;
+    base.failingCheckNames = failing;
+    base.failingChecks = failing.length;
+    base.totalChecks = rollup.length;
+  }
+  return { ...base, ...rest };
+}
+
+function reqChecks(...names: string[]): RequiredCheck[] {
+  return names.map((name) => ({ name, acceptedConclusions: ["success"] }));
+}
+
+function protocolWith(over: Partial<MergeProtocol>): MergeProtocol {
+  return { ...DEFAULT_MERGE_PROTOCOL, ...over };
+}
+
+interface MergeCase {
+  name: string;
+  state: Partial<PrState> & { rollup?: { name: string; conclusion: string }[] };
+  protocol?: MergeProtocol;
+  want: Mergeability;
+}
+
+const MERGE_CASES: MergeCase[] = [
+  // The exact defect: UNSTABLE + a red DECLARED-required check used to classify `ready` and merge.
+  {
+    name: "UNSTABLE + red declared-required check -> blocked (the #392 defect)",
+    state: { mergeStateStatus: "UNSTABLE", rollup: [{ name: "test (22.x, simple)", conclusion: "FAILURE" }] },
+    protocol: protocolWith({ requiredChecks: [{ name: "test (22.x, simple)", acceptedConclusions: ["success"] }] }),
+    want: "blocked",
+  },
+  {
+    name: "CLEAN + red declared-required check -> blocked (backstop runs before the switch)",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "FAILURE" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "blocked",
+  },
+  {
+    name: "declared-required check pending -> waiting",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "IN_PROGRESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "waiting",
+  },
+  {
+    name: "declared-required check absent from head -> waiting (absence is not a pass)",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "lint", conclusion: "SUCCESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "waiting",
+  },
+  {
+    name: "declared-required check passing, CLEAN -> ready",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "SUCCESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "ready",
+  },
+  {
+    name: "declared-required check passing, UNSTABLE -> ready (falls through to the switch)",
+    state: { mergeStateStatus: "UNSTABLE", rollup: [{ name: "build", conclusion: "SUCCESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "ready",
+  },
+  {
+    name: "non-required check failing (not declared-required), UNSTABLE -> ready (today's behaviour)",
+    state: {
+      mergeStateStatus: "UNSTABLE",
+      rollup: [{ name: "build", conclusion: "SUCCESS" }, { name: "flaky-optional", conclusion: "FAILURE" }],
+    },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "ready",
+  },
+  {
+    name: "CANCELLED superseded by a newer green run on a required check -> ready (#348 semantics)",
+    // `prState`'s rollup shorthand keeps one conclusion per name (latest wins); model the superseded
+    // + re-run by asserting the green outcome the rollup helpers collapse to.
+    state: { mergeStateStatus: "UNSTABLE", rollup: [{ name: "engine-core", conclusion: "SUCCESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("engine-core") }),
+    want: "ready",
+  },
+  {
+    name: "acceptedConclusions beyond [success] honoured: NEUTRAL accepted -> ready",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "NEUTRAL" }] },
+    protocol: protocolWith({ requiredChecks: [{ name: "build", acceptedConclusions: ["success", "neutral"] }] }),
+    want: "ready",
+  },
+  {
+    name: "acceptedConclusions [success] does NOT accept a NEUTRAL required conclusion -> blocked",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "NEUTRAL" }] },
+    protocol: protocolWith({ requiredChecks: [{ name: "build", acceptedConclusions: ["success"] }] }),
+    want: "blocked",
+  },
+  {
+    name: "waitForChecks:true + pending required check -> waiting even when CLEAN",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "QUEUED" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build"), waitForChecks: true }),
+    want: "waiting",
+  },
+];
+
+for (const c of MERGE_CASES) {
+  test(`classifyMergeability: ${c.name}`, () => {
+    assertEquals(classifyMergeability(mergePrState(c.state), c.protocol), c.want);
+  });
+}
+
+// Empty requiredChecks (the DEFAULT protocol) — behaviour must be IDENTICAL to today across every
+// mergeStateStatus, whether a protocol is passed or omitted entirely.
+const DEFAULT_BEHAVIOUR: { status: string; failingChecks?: number; want: Mergeability }[] = [
+  { status: "CLEAN", want: "ready" },
+  { status: "HAS_HOOKS", want: "ready" },
+  { status: "UNSTABLE", want: "ready" },
+  { status: "BEHIND", want: "ready" },
+  { status: "DIRTY", want: "conflict" },
+  { status: "BLOCKED", failingChecks: 1, want: "blocked" },
+  { status: "BLOCKED", failingChecks: 0, want: "waiting" },
+  { status: "UNKNOWN", want: "waiting" },
+  { status: "", want: "waiting" },
+];
+
+for (const c of DEFAULT_BEHAVIOUR) {
+  test(`classifyMergeability: empty requiredChecks keeps today's behaviour (${c.status || "''"} -> ${c.want})`, () => {
+    const s = prState({ mergeStateStatus: c.status, failingChecks: c.failingChecks ?? 0 });
+    // Explicit default protocol and omitted-protocol must agree.
+    assertEquals(classifyMergeability(s, DEFAULT_MERGE_PROTOCOL), c.want);
+    assertEquals(classifyMergeability(s), c.want);
+  });
+}
+
+// Token mode: the transport can't enumerate checks (`failingChecks === -1`, empty per-check lists),
+// so even a repo that declares requiredChecks must fall through to today's `mergeStateStatus`
+// behaviour — the backstop must NEVER newly block or wait when checks are unenumerable.
+const TOKEN_MODE: { status: string; want: Mergeability }[] = [
+  { status: "CLEAN", want: "ready" },
+  { status: "UNSTABLE", want: "ready" },
+  { status: "BLOCKED", want: "waiting" }, // failingChecks<0 → conservative wait, exactly as before
+  { status: "DIRTY", want: "conflict" },
+  { status: "UNKNOWN", want: "waiting" },
+];
+
+for (const c of TOKEN_MODE) {
+  test(`classifyMergeability: token mode falls through, never newly blocks (${c.status} -> ${c.want})`, () => {
+    const s = prState({
+      mergeStateStatus: c.status,
+      failingChecks: -1,
+      totalChecks: -1,
+      presentCheckNames: [],
+      pendingCheckNames: [],
+      checkConclusions: {},
+    });
+    const protocol = protocolWith({ requiredChecks: reqChecks("build"), waitForChecks: true });
+    assertEquals(classifyMergeability(s, protocol), c.want);
+  });
+}
+
+// `checkConclusions` must report a terminal conclusion per check but normalise a STILL-IN-FLIGHT run
+// to "" for BOTH rollup shapes — a CheckRun whose `status` is not COMPLETED, and a legacy
+// StatusContext whose `state` is PENDING/EXPECTED — so a caller never mistakes a pending
+// status-context's upper-cased `state` (e.g. "PENDING") for a terminal conclusion.
+test("checkConclusions: in-flight runs map to '' for both CheckRun and StatusContext shapes", () => {
+  const got = checkConclusions([
+    { name: "ci-success", status: "COMPLETED", conclusion: "SUCCESS" },
+    { name: "ci-failure", status: "COMPLETED", conclusion: "FAILURE" },
+    { name: "ci-running", status: "IN_PROGRESS" }, // CheckRun in flight -> ""
+    { name: "ci-queued", status: "QUEUED" }, // CheckRun queued -> ""
+    { context: "legacy-pending", state: "PENDING" }, // StatusContext in flight -> ""
+    { context: "legacy-expected", state: "EXPECTED" }, // StatusContext in flight -> ""
+    { context: "legacy-error", state: "ERROR" }, // StatusContext terminal -> preserved
+  ]);
+  assertEquals(got, {
+    "ci-success": "SUCCESS",
+    "ci-failure": "FAILURE",
+    "ci-running": "",
+    "ci-queued": "",
+    "legacy-pending": "",
+    "legacy-expected": "",
+    "legacy-error": "ERROR",
+  });
+});

package/app/github.ts

@@ -11,6 +11,11 @@
 // The poller is app-side host glue (main.ts), so host-specific subprocess I/O is allowed here.
 // Cross-runtime: runs under Node (`node:child_process`).
 
+// Type-only import (erased at runtime, so no runtime cycle with mergeProtocol.ts, which imports
+// `fetchRepoFile` from here): `classifyMergeability` reads a repo's declared required checks to gate
+// a merge independently of GitHub branch protection.
+import type { MergeProtocol } from "./mergeProtocol.ts";
+
 /** A GitHub pull-request review, narrowed to the fields the poller needs. */
 export interface GhReview {
   id: number;
@@ -502,6 +507,17 @@ export interface PrState {
    * unrelated always-on check (e.g. Mergify's "Merge Queue") must not read as "the required run
    * already happened". */
   presentCheckNames: string[];
+  /** Names of every head check still in flight (queued/in progress, not yet concluded and not a hard
+  * failure), derived over the newest run per check (`pendingCheckNames`). Empty in token mode (the
+  * REST fallback can't enumerate checks). Lets `classifyMergeability` hold a merge when a
+  * declared-required check has not yet concluded, without re-deriving conclusions by hand. */
+  pendingCheckNames: string[];
+  /** The newest concluded conclusion per head check (name → uppercase conclusion, e.g. `SUCCESS` /
+  * `FAILURE` / `NEUTRAL` / `SKIPPED`), derived over `latestRunPerCheck` so a `CANCELLED` run
+  * superseded by a newer green run on the same head reports the green result (#348). A still-pending
+  * run maps to `""` (it has no conclusion yet — use `pendingCheckNames`). Empty in token mode. Lets
+  * `classifyMergeability` honour a required check's `acceptedConclusions` precisely. */
+  checkConclusions: Record<string, string>;
   /** Whether the PR is a draft (a fresh head run is produced by marking it ready, not reopen). */
   isDraft: boolean;
   /** Current head commit. Used to scope one-shot merge-protocol nudges to a landing attempt. */
@@ -633,6 +649,29 @@ export function allCheckNames(rollup: RollupEntry[]): string[] {
   return names;
 }
 
+/** The ground-truth conclusion of each head check, keyed by check name, derived over the **newest run
+ * per check** (`latestRunPerCheck`) so a `CANCELLED` run superseded by a newer green run on the
+ * identical head SHA reports the green result, not the stale cancellation (issue #348). The value is
+ * the run's `conclusion` (CheckRun) or `state` (legacy StatusContext), upper-cased; a still-in-flight
+ * run that has not concluded maps to `""` (it has no conclusion — `pendingCheckNames` tracks those).
+ * In-flight is normalised to `""` for BOTH shapes: a CheckRun whose `status` is not `COMPLETED`, and a
+ * legacy StatusContext whose `state` is `PENDING`/`EXPECTED`, so a caller never mistakes a pending
+ * status-context's `PENDING`/`EXPECTED` `state` for a terminal conclusion.
+ * Lets `classifyMergeability` intersect a repo's declared `requiredChecks` against actual head
+ * conclusions and honour each check's `acceptedConclusions` without re-deriving per-run state. */
+export function checkConclusions(rollup: RollupEntry[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const c of latestRunPerCheck(rollup)) {
+    const status = (c.status || "").toUpperCase();
+    const state = (c.state || "").toUpperCase();
+    // A still-in-flight run has no terminal conclusion — normalise both shapes to "" (mirrors
+    // `pendingCheckNames`): CheckRun status != COMPLETED, or legacy StatusContext state PENDING/EXPECTED.
+    const inFlight = status !== "" ? status !== "COMPLETED" : state === "PENDING" || state === "EXPECTED";
+    out[checkKey(c)] = inFlight ? "" : (c.conclusion || c.state || "").toUpperCase();
+  }
+  return out;
+}
+
 /** True when `err` is GitHub reporting that a ref which parsed as `owner/repo#N` is not a pull
  * request — either it's an issue (issues and PRs share GitHub's number space, so an issue number
  * is indistinguishable from a PR number by shape alone) or the number does not exist. Both
@@ -682,6 +721,8 @@ export async function fetchPrState(
       failingCheckNames: names,
       totalChecks: rollup.length,
       presentCheckNames: allCheckNames(rollup),
+      pendingCheckNames: pendingCheckNames(rollup),
+      checkConclusions: checkConclusions(rollup),
       isDraft: !!j.isDraft,
       headRefOid: j.headRefOid ?? null,
     };
@@ -713,6 +754,8 @@ export async function fetchPrState(
     failingCheckNames: [], // …and the CI-fix agent gets no per-check list in token mode
     totalChecks: -1, // …and the fresh-head-run remedy stays conservative (never reopens blind)
     presentCheckNames: [], // …can't enumerate checks in token mode → no required-check presence signal
+    pendingCheckNames: [], // …no per-check pending signal either → classifier degrades to today's switch
+    checkConclusions: {}, // …no per-check conclusions → protocol-aware gate falls through in token mode
     isDraft: !!j.draft,
     headRefOid: j.head?.sha ?? null,
   };
@@ -915,11 +958,68 @@ export async function baseBranchLanded(
  * verdict; `waiting` means re-poll later. */
 export type Mergeability = "ready" | "waiting" | "conflict" | "blocked";
 
-export function classifyMergeability(s: PrState): Mergeability {
+/** Intersect a repo's declared `requiredChecks` against the head's actual per-check conclusions —
+ * an INDEPENDENT backstop that runs BEFORE the `mergeStateStatus` switch, so nwf never merges a red
+ * required check even on a repo that has NOT wired that check as a GitHub-required status check
+ * (issue #392). Returns:
+ *   • `"blocked"` — a declared-required check is present, concluded, and its conclusion is NOT in that
+ *      check's `acceptedConclusions` (a hard failure like `FAILURE`, or any other unaccepted terminal
+ *      conclusion) → route to fix-ci, do not merge.
+ *   • `"waiting"` — a declared-required check is still pending, or absent from the head entirely
+ *      (not-yet-run counts as pending, NOT as pass): a declared-required check that has not
+ *      concluded is never mergeable.
+ *   • `"pass"` — every declared-required check is present and its conclusion accepted → fall through to
+ *      today's `mergeStateStatus` logic (GitHub branch protection stays the primary gate).
+ * Degrades safely: with no declared `requiredChecks`, or in token mode where checks can't be
+ * enumerated (`failingChecks < 0`, so the per-check lists are empty), it returns `"pass"` and never
+ * newly blocks or waits — repos keep exactly today's behaviour. */
+function requiredChecksVerdict(s: PrState, protocol?: MergeProtocol): "blocked" | "waiting" | "pass" {
+  const required = protocol?.requiredChecks ?? [];
+  if (required.length === 0) return "pass";
+  // Token mode: the transport can't enumerate checks (`failingChecks === -1`), so the per-check lists
+  // are empty and absence is indistinguishable from not-yet-run. Do NOT newly block/wait — fall
+  // through to today's `mergeStateStatus` behaviour. (A real gh-mode head with no checks yet reports
+  // `failingChecks === 0`, so absence there is correctly treated as not-yet-run below.)
+  if (s.failingChecks < 0) return "pass";
+  const present = new Set(s.presentCheckNames);
+  const pending = new Set(s.pendingCheckNames);
+  let anyBlocked = false;
+  let anyPending = false;
+  for (const rc of required) {
+    // Absent from the head, or still in flight → not-yet-run → wait (never treat absence as pass).
+    if (!present.has(rc.name) || pending.has(rc.name)) {
+      anyPending = true;
+      continue;
+    }
+    const conclusion = (s.checkConclusions[rc.name] ?? "").toUpperCase();
+    if (conclusion === "") {
+      // Present but no terminal conclusion yet (and not flagged pending) — treat conservatively as
+      // not-yet-concluded rather than as a pass.
+      anyPending = true;
+      continue;
+    }
+    const accepted = rc.acceptedConclusions.map((a) => a.toUpperCase());
+    if (accepted.includes(conclusion)) continue; // satisfied
+    anyBlocked = true; // present, concluded, NOT accepted → a red required check
+  }
+  // A failing required check outranks a pending one: it needs fix-ci now, not more waiting.
+  if (anyBlocked) return "blocked";
+  if (anyPending) return "waiting";
+  return "pass";
+}
+
+export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Mergeability {
+  // Protocol-aware backstop FIRST (issue #392): honour the repo's declared `requiredChecks`
+  // against the actual head rollup, so an `UNSTABLE` PR with a red DECLARED-required
+  // check is no longer blindly `ready`. This never weakens GitHub branch protection (the switch
+  // below still gates) — it only tightens merges on repos that under-specify their required checks.
+  const gate = requiredChecksVerdict(s, protocol);
+  if (gate === "blocked") return "blocked";
+  if (gate === "waiting") return "waiting";
   switch (s.mergeStateStatus) {
     case "CLEAN":
     case "HAS_HOOKS":
-    case "UNSTABLE": // only non-required checks failing — still mergeable
+    case "UNSTABLE": // only non-required checks failing — still mergeable (no DECLARED-required red)
     case "BEHIND": // out of date; a queue rebases, a direct merge is still allowed
       return "ready";
     case "DIRTY":

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);
+});