@nanobpm/nano-workforce 0.99.0 → 0.100.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.100.0](https://github.com/nanobpm/nano-workforce/compare/v0.99.1...v0.100.0) (2026-08-19)
+
+
+### Features
+
+* retire interim feature-run escalation/blocked surface ([#339](https://github.com/nanobpm/nano-workforce/issues/339)) ([525d0f7](https://github.com/nanobpm/nano-workforce/commit/525d0f7a7f9661f640899e4bdf1b32052cff4ed9)), closes [#305](https://github.com/nanobpm/nano-workforce/issues/305) [#310](https://github.com/nanobpm/nano-workforce/issues/310) [#332](https://github.com/nanobpm/nano-workforce/issues/332) [#332](https://github.com/nanobpm/nano-workforce/issues/332)
+
+## [0.99.1](https://github.com/nanobpm/nano-workforce/compare/v0.99.0...v0.99.1) (2026-08-19)
+
+
+### Bug Fixes
+
+* **convergence-loop:** route every escalation arm through gw-escalated ([#333](https://github.com/nanobpm/nano-workforce/issues/333)) ([#340](https://github.com/nanobpm/nano-workforce/issues/340)) ([0ad7a5c](https://github.com/nanobpm/nano-workforce/commit/0ad7a5c08a659a0ca26dc48def8c024d21a3a53a)), closes [#329](https://github.com/nanobpm/nano-workforce/issues/329)
+
 # [0.99.0](https://github.com/nanobpm/nano-workforce/compare/v0.98.1...v0.99.0) (2026-08-19)
 
 

package/app/agentCompletion.test.ts

@@ -62,11 +62,15 @@ function memData(stores: Record<string, { rows: any[]; key: string }>) {
   } as any;
 }
 
-/** A stub engine recording every `completeUserTask`, with a seeded set of open user tasks. */
+/** A stub engine recording every `completeUserTask`, with a seeded set of open user tasks. The
+ *  completers resolve tasks via `openUserTasks` (CREATED only), so the fixture exposes it; a legacy
+ *  `searchUserTasks` (ANY state) is also present to prove the completer does NOT reach for it. */
 function fakeEngine(openTasks: Array<{ userTaskKey: string; elementId?: string }>) {
   const completed: Array<{ userTaskKey: string; variables?: Record<string, unknown> }> = [];
   const engine = {
-    searchUserTasks: (_filter?: Record<string, unknown>) => Promise.resolve(openTasks),
+    openUserTasks: (_filter?: Record<string, unknown>) => Promise.resolve(openTasks),
+    searchUserTasks: (_filter?: Record<string, unknown>) =>
+      Promise.reject(new Error("completer must resolve via openUserTasks, not searchUserTasks")),
     completeUserTask: (userTaskKey: string, variables?: Record<string, unknown>) => {
       completed.push({ userTaskKey, variables });
       return Promise.resolve();
@@ -118,7 +122,7 @@ test("agent completer refuses a non-escalation user task (scoped to the migrated
   });
 
   assertEquals(r.ok, false);
-  assertEquals(r.reason, "not an escalation task");
+  assertEquals(r.reason, "not a completable task");
   assertEquals(completed.length, 0, "a non-escalation task is never completed");
   assertEquals(stores.task_completions.rows.length, 0, "and no attribution row is written");
 });
@@ -137,10 +141,40 @@ test("agent completer is a no-op for an unknown userTaskKey", async () => {
   });
 
   assertEquals(r.ok, false);
-  assertEquals(r.reason, "no open escalation task");
+  assertEquals(r.reason, "no open completable task");
   assertEquals(completed.length, 0);
 });
 
+test("completer resolves only OPEN tasks — a completed/canceled task's key is a 404-style no-op, not a doomed re-completion", async () => {
+  // A looping instance keeps COMPLETED/CANCELED user tasks alongside the live one. If the completer
+  // matched by key against ANY-state tasks (`searchUserTasks`), a stale key would drive a re-completion
+  // that the engine rejects with a 5xx instead of the intended "no open task" no-op. The completer must
+  // query `openUserTasks` (CREATED only), so a key that exists only as a non-open task does not match.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const completed: Array<{ userTaskKey: string }> = [];
+  const engine = {
+    // No open tasks…
+    openUserTasks: () => Promise.resolve([]),
+    // …even though a completed task with this key exists in the full (any-state) search.
+    searchUserTasks: () => Promise.resolve([{ userTaskKey: "ut-done", elementId: "feature-escalation" }]),
+    completeUserTask: (userTaskKey: string) => {
+      completed.push({ userTaskKey });
+      return Promise.resolve();
+    },
+  } as any;
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-done",
+    operatorId: "alice",
+    variables: { resolution: "abandon" },
+  });
+
+  assertEquals(r.ok, false);
+  assertEquals(r.reason, "no open completable task");
+  assertEquals(completed.length, 0, "a non-open key never drives a doomed re-completion");
+});
+
 test("a HUMAN operator completes a feature escalation via the SAME attributed resume path (issue #210)", async () => {
   const stores = { task_completions: { rows: [] as any[], key: "id" } };
   const data = memData(stores);
@@ -166,6 +200,35 @@ test("a HUMAN operator completes a feature escalation via the SAME attributed re
   assertEquals(row.reversible, 0, "a human completion is the authority (not reversible)");
 });
 
+test("feature-blocked is HUMAN-completable but NOT agent-completable (issue #332)", async () => {
+  // Issue #332 folded the bespoke `acknowledge-blocked` door onto the canonical human completer, so a
+  // HUMAN operator retires a blocked run through `completeEscalationAsHuman`. It stays OUTSIDE the agent
+  // surface (`ESCALATION_TASK_ELEMENTS`) — an agent must never acknowledge a blocked run on a human's
+  // behalf — so the agent completer refuses it.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-b", elementId: "feature-blocked" }]);
+
+  const asAgent = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-b",
+    agentId: "bot",
+    variables: { note: "n" },
+  });
+  assertEquals(asAgent.ok, false, "the agent completer refuses feature-blocked");
+  assertEquals(asAgent.reason, "not a completable task");
+  assertEquals(completed.length, 0);
+
+  const asHuman = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-b",
+    operatorId: "alice",
+    variables: { note: "reassigned to a human" },
+  });
+  assertEquals(asHuman.ok, true, "the human completer retires feature-blocked");
+  assertEquals(asHuman.elementId, "feature-blocked");
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].variables, { note: "reassigned to a human" });
+});
+
 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);
@@ -177,7 +240,7 @@ test("human completer refuses a non-escalation user task and is a no-op for an u
     variables: { resolution: "abandon" },
   });
   assertEquals(notEsc.ok, false);
-  assertEquals(notEsc.reason, "not an escalation task");
+  assertEquals(notEsc.reason, "not a completable task");
 
   const missing = await completeEscalationAsHuman(data, engine, {
     userTaskKey: "ut-missing",
@@ -185,7 +248,7 @@ test("human completer refuses a non-escalation user task and is a no-op for an u
     variables: { resolution: "abandon" },
   });
   assertEquals(missing.ok, false);
-  assertEquals(missing.reason, "no open escalation task");
+  assertEquals(missing.reason, "no open completable task");
 
   assertEquals(completed.length, 0, "neither refusal completes a task");
   assertEquals(stores.task_completions.rows.length, 0, "and no attribution row is written");
@@ -455,3 +518,26 @@ test("validateEscalationVariables derives its contract from the canonical .form
   // an element with no linked form contract is not enforced
   assertEquals(validateEscalationVariables("some-other-task", { whatever: 1 }), null);
 });
+
+test("feature-escalation demands non-blank answer on the answer path, but not on the hidden abandon path", async () => {
+  // resolution=answer shows the conditional `answer` field, which is required → blank/missing rejected.
+  assert(
+    validateEscalationVariables("feature-escalation", { resolution: "answer" }) !== null,
+    "resolution=answer with no guidance is rejected",
+  );
+  assert(
+    validateEscalationVariables("feature-escalation", { resolution: "answer", answer: "   " }) !== null,
+    "resolution=answer with whitespace-only guidance is rejected",
+  );
+  assertEquals(
+    validateEscalationVariables("feature-escalation", { resolution: "answer", answer: "use v2" }),
+    null,
+    "resolution=answer with real guidance passes",
+  );
+  // resolution=abandon HIDES the `answer` field, so its required-ness is not enforced.
+  assertEquals(
+    validateEscalationVariables("feature-escalation", { resolution: "abandon" }),
+    null,
+    "the abandon path does not demand the hidden answer field",
+  );
+});

package/app/agentCompletion.ts

@@ -71,6 +71,23 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
   "wait-merge-answer", // PR merge-loop escalation (merge-loop.bpmn) — same native user-task path (#256)
 ]);
 
+/** The `feature-blocked` operator user-task element id (feature.bpmn) — the native wait a run parks on
+ *  when the agent reports a `blocked` outcome. Unlike an escalation it is NOT agent-answerable (only a
+ *  human operator retires a blocked run), so it lives OUTSIDE `ESCALATION_TASK_ELEMENTS` — the agent
+ *  completer (`completeEscalationAsAgent`) must never touch it — but it IS a human-completable decision
+ *  on the Tasks inbox, so the HUMAN completer accepts it (issue #332 folded the bespoke
+ *  `acknowledge-blocked` door onto the one canonical `complete-user-task` door). */
+export const FEATURE_BLOCKED_TASK_ELEMENT = "feature-blocked";
+
+/** 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`
+ *  acknowledgement. The AGENT completer stays scoped to `ESCALATION_TASK_ELEMENTS` (no `feature-blocked`),
+ *  so widening the human surface never lets an agent retire a blocked run. */
+export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
+  ...ESCALATION_TASK_ELEMENTS,
+  FEATURE_BLOCKED_TASK_ELEMENT,
+]);
+
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
  *  BPMN `zeebe:formDefinition formId`). Kept beside `ESCALATION_TASK_ELEMENTS` so the completer
  *  validates against the SAME `.form` the task inbox renders — one contract, no second field list. */
@@ -80,36 +97,74 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "trial-merge-decision": "trial-merge-decision",
   "wait-answer": "pr-escalation",
   "wait-merge-answer": "pr-escalation",
+  "feature-blocked": "feature-blocked",
 };
 
+/** A field's `conditional.hide` rule, parsed from the FEEL subset the `.form` files use
+ *  (`=<ref> != "<value>"` / `=<ref> == "<value>"`). A required field is only enforced when it is
+ *  actually shown, so an "answer only when resolution=answer" field is not demanded on the abandon
+ *  path. */
+interface HideRule {
+  ref: string;
+  op: "==" | "!=";
+  value: string;
+}
+
 interface FormContract {
   /** Field keys marked `validate.required` in the `.form`. */
   required: string[];
   /** `select` field key → its allowed `values`. */
   allowed: Record<string, string[]>;
+  /** Field key → its `conditional.hide` rule (only for fields whose visibility is conditional). */
+  hideWhen: Record<string, HideRule>;
 }
 
 const formContractCache = new Map<string, FormContract>();
 
-/** Derive a `.form`'s required-field + select allowed-value contract, cached per formId. The `.form`
- *  files (`resources/forms/*.form`, deployed via nano.app.json) are the CANONICAL contract, so this
- *  reads them rather than re-encoding the field lists — no drift surface. */
+/** Parse the `.form` FEEL subset used by `conditional.hide` — `=<ref> (!=|==) "<value>"` — into a
+ *  structured rule, or `null` for anything outside that subset (treated as "always shown", so a
+ *  required field is never silently skipped by an unrecognised expression). */
+function parseHide(expr: string | undefined): HideRule | null {
+  if (!expr) return null;
+  const m = /^=\s*([A-Za-z_$][\w$]*)\s*(==|!=)\s*"([^"]*)"\s*$/.exec(expr);
+  if (!m) return null;
+  const op = m[2] === "==" ? "==" : "!=";
+  return { ref: m[1], op, value: m[3] };
+}
+
+/** Whether a `conditional.hide` rule hides its field given the submitted `variables`. */
+function isHidden(rule: HideRule, variables: Record<string, unknown>): boolean {
+  const actual = String(variables[rule.ref] ?? "");
+  return rule.op === "!=" ? actual !== rule.value : actual === rule.value;
+}
+
+/** Derive a `.form`'s required-field + select allowed-value + conditional-visibility contract, cached
+ *  per formId. The `.form` files (`resources/forms/*.form`, deployed via nano.app.json) are the
+ *  CANONICAL contract, so this reads them rather than re-encoding the field lists — no drift surface. */
 function formContract(formId: string): FormContract {
   const cached = formContractCache.get(formId);
   if (cached) return cached;
   const raw: {
-    components?: { key?: string; validate?: { required?: boolean }; values?: { value?: string }[] }[];
+    components?: {
+      key?: string;
+      validate?: { required?: boolean };
+      values?: { value?: string }[];
+      conditional?: { hide?: string };
+    }[];
   } = JSON.parse(readFileSync(new URL(`../resources/forms/${formId}.form`, import.meta.url), "utf8"));
   const required: string[] = [];
   const allowed: Record<string, string[]> = {};
+  const hideWhen: Record<string, HideRule> = {};
   for (const c of raw.components ?? []) {
     if (!c.key) continue;
     if (c.validate?.required) required.push(c.key);
     if (c.values?.length) {
       allowed[c.key] = c.values.map((v) => v.value ?? "").filter((v) => v !== "");
     }
+    const hide = parseHide(c.conditional?.hide);
+    if (hide) hideWhen[c.key] = hide;
   }
-  const contract: FormContract = { required, allowed };
+  const contract: FormContract = { required, allowed, hideWhen };
   formContractCache.set(formId, contract);
   return contract;
 }
@@ -117,18 +172,23 @@ function formContract(formId: string): FormContract {
 /** Validate completion `variables` against the escalation's `.form` contract (required fields present
  *  + `select` values within the allowed set), so a completion can never resume the process with a
  *  missing/invalid decision (e.g. a `wait-answer` with no `answer`, or a `trial-merge-decision` with
- *  an `action` outside proceed/rebase/abandon). Returns a human-readable reason on violation, or
- *  `null` when the variables satisfy the contract. Derived from the canonical `.form` — the same
- *  contract the task inbox renders — so both the agent and human completers reject invalid input the
- *  exact same way, with one implementation. An element with no linked form contract is not enforced. */
+ *  an `action` outside proceed/rebase/abandon). A conditionally-shown required field is only enforced
+ *  when its `conditional.hide` rule leaves it visible — so a `feature-escalation` with
+ *  `resolution="answer"` demands a non-blank `answer` (re-dispatch guidance), but the `abandon` path,
+ *  which hides `answer`, does not. Returns a human-readable reason on violation, or `null` when the
+ *  variables satisfy the contract. Derived from the canonical `.form` — the same contract the task
+ *  inbox renders — so both the agent and human completers reject invalid input the exact same way,
+ *  with one implementation. An element with no linked form contract is not enforced. */
 export function validateEscalationVariables(
   elementId: string,
   variables: Record<string, unknown>,
 ): string | null {
   const formId = ESCALATION_FORM_BY_ELEMENT[elementId];
   if (!formId) return null;
-  const { required, allowed } = formContract(formId);
+  const { required, allowed, hideWhen } = formContract(formId);
   for (const key of required) {
+    const hide = hideWhen[key];
+    if (hide && isHidden(hide, variables)) continue;
     const v = variables[key];
     if (v === undefined || v === null || (typeof v === "string" && v.trim() === "")) {
       return `${elementId}: "${key}" is required`;
@@ -222,19 +282,24 @@ export interface AgentCompleteResult {
   elementId?: string;
 }
 
-/** Resolve a parked escalation user task by key: return its `elementId` if it is one of the migrated
- *  escalation tasks, or a failure reason otherwise. Shared by the agent and human completers so both
- *  refuse a non-escalation / missing target the exact same way (a key with no matching open
- *  escalation task is a 404-style no-op). */
+/** Resolve a parked escalation user task by key: return its `elementId` if it is one of the `allowed`
+ *  completable tasks, or a failure reason otherwise. Shared by the agent and human completers so both
+ *  refuse a non-completable / missing target the exact same way (a key with no matching open task is a
+ *  404-style no-op). The AGENT completer passes the default `ESCALATION_TASK_ELEMENTS`; the HUMAN
+ *  completer passes the wider `HUMAN_COMPLETABLE_ELEMENTS` (which also admits `feature-blocked`).
+ *  Queries `openUserTasks` (lifecycle-state `CREATED` only), NOT `searchUserTasks` (which returns
+ *  tasks in ANY state) — a looping instance keeps COMPLETED/CANCELED tasks whose key could otherwise
+ *  match and drive a doomed re-completion (a thrown 5xx) instead of the intended 404-style no-op. */
 async function resolveEscalationTask(
   engine: EngineClient,
   userTaskKey: string,
+  allowed: ReadonlySet<string> = ESCALATION_TASK_ELEMENTS,
 ): Promise<{ ok: true; elementId: string } | { ok: false; reason: string }> {
-  const open = await engine.searchUserTasks();
+  const open = await engine.openUserTasks();
   const match = open.find((t) => t.userTaskKey === userTaskKey);
-  if (!match) return { ok: false, reason: "no open escalation task" };
-  if (!match.elementId || !ESCALATION_TASK_ELEMENTS.has(match.elementId)) {
-    return { ok: false, reason: "not an escalation task" };
+  if (!match) return { ok: false, reason: "no open completable task" };
+  if (!match.elementId || !allowed.has(match.elementId)) {
+    return { ok: false, reason: "not a completable task" };
   }
   return { ok: true, elementId: match.elementId };
 }
@@ -275,7 +340,8 @@ export async function completeEscalationAsAgent(
  *  affordance resumes the process through the one implementation a human uses from the task inbox —
  *  no parallel completion path — while recording WHO answered in the `task_completions` ledger. A
  *  human completion is the authority (not reversible). A key with no matching open escalation task is
- *  a 404-style no-op. */
+ *  a 404-style no-op. The human surface is the wider `HUMAN_COMPLETABLE_ELEMENTS`, so it also retires a
+ *  `feature-blocked` acknowledgement (issue #332 folded the bespoke `acknowledge-blocked` door here). */
 export async function completeEscalationAsHuman(
   data: DataLayer,
   engine: EngineClient,
@@ -286,7 +352,7 @@ export async function completeEscalationAsHuman(
   const operatorId = input.operatorId.trim();
   if (!operatorId) return { ok: false, reason: "operatorId is required" };
 
-  const resolved = await resolveEscalationTask(engine, userTaskKey);
+  const resolved = await resolveEscalationTask(engine, userTaskKey, HUMAN_COMPLETABLE_ELEMENTS);
   if (!resolved.ok) return resolved;
 
   const invalid = validateEscalationVariables(resolved.elementId, input.variables);
@@ -301,44 +367,6 @@ export async function completeEscalationAsHuman(
   return { ok: true, completionId, userTaskKey, elementId: resolved.elementId };
 }
 
-/** The `feature-blocked` operator user-task element id (feature.bpmn). Unlike an escalation this is not
- *  an agent-answerable task — it is a blocked-run acknowledgement only a human operator retires — so it
- *  lives outside `ESCALATION_TASK_ELEMENTS` (the agent completer must never touch it) and has its own
- *  human-only completer below. */
-export const FEATURE_BLOCKED_TASK_ELEMENT = "feature-blocked";
-
-/** Complete the `feature-blocked` operator user task AS A HUMAN (issue #220). The blocked twin of
- *  `completeEscalationAsHuman`: it resolves the parked task by key, refuses anything that is not the
- *  `feature-blocked` task, and routes the operator's typed form variables (an optional `note`) through
- *  the SAME canonical `completeUserTaskAttributed` — so the nwf "Acknowledge blocked" affordance resumes
- *  the process (→ `pr.record-blocked-ack`, which settles the row to terminal `blocked`) through the one
- *  completion a human drives from the task inbox, recording WHO acknowledged in the `task_completions`
- *  ledger. A human completion is the authority (not reversible). A key with no matching open
- *  `feature-blocked` task is a 404-style no-op. */
-export async function completeBlockedAsHuman(
-  data: DataLayer,
-  engine: EngineClient,
-  input: { userTaskKey: string; variables: Record<string, unknown>; operatorId: string },
-): Promise<AgentCompleteResult> {
-  const userTaskKey = input.userTaskKey.trim();
-  if (!userTaskKey) return { ok: false, reason: "userTaskKey is required" };
-  const operatorId = input.operatorId.trim();
-  if (!operatorId) return { ok: false, reason: "operatorId is required" };
-
-  const open = await engine.searchUserTasks();
-  const match = open.find((t) => t.userTaskKey === userTaskKey);
-  if (!match) return { ok: false, reason: "no open blocked task" };
-  if (match.elementId !== FEATURE_BLOCKED_TASK_ELEMENT) return { ok: false, reason: "not a blocked task" };
-
-  const { completionId } = await completeUserTaskAttributed(
-    data,
-    engine,
-    { userTaskKey, elementId: match.elementId, variables: input.variables },
-    { kind: "human", id: operatorId },
-  );
-  return { ok: true, completionId, userTaskKey, elementId: match.elementId };
-}
-
 export interface RevertResult {
   ok: boolean;
   reason?: string;

package/app/convergeGate.test.ts

@@ -467,11 +467,15 @@ test("gw-converge-gate default arm finalizes with no condition", () => {
   assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
 });
 
-test("the blocked-comments escalation lands on the human wait-answer task with an answerable escalation", () => {
-  const f = flowElement("f_blockedWait");
-  assert(f, "f_blockedWait flow missing");
+test("the blocked-comments escalation routes through gw-escalated toward an answerable wait-answer", () => {
+  // #333: previously this flowed UNCONDITIONALLY into wait-answer, so a blank convergeBlockReason
+  // (the question is mapped from that OPTIONAL variable) opened no escalation yet still parked a
+  // dead wait with a null question. It now routes through gw-escalated, which parks wait-answer
+  // only on a real escalation and otherwise re-enters the loop.
+  const f = flowElement("f_blockedGate");
+  assert(f, "f_blockedGate flow missing");
   assertStringIncludes(f, 'sourceRef="persist-escalation-blockedcomments"');
-  assertStringIncludes(f, 'targetRef="wait-answer"');
+  assertStringIncludes(f, 'targetRef="gw-escalated"');
   const task = flat.match(
     /<bpmn:serviceTask\b[^>]*\bid="persist-escalation-blockedcomments"[^>]*>.*?<\/bpmn:serviceTask>/,
   );

package/app/convergenceEscalationGuard.test.ts

@@ -0,0 +1,106 @@
+// Regression guard for the question-less convergence-loop escalation defect (issue #333).
+//
+// The convergence loop (`resources/processes/convergence-loop.bpmn`) has FIVE `persist-escalation`
+// service tasks, but only ONE — `persist-escalation` (the `f_escalate` agent-verdict arm) — was
+// routed through the `gw-escalated` gateway that honours the worker's `escalated` output. The other
+// four flowed UNCONDITIONALLY into the durable `wait-answer` user task:
+//
+//   • persist-escalation-noprogress      (no progress made this round)
+//   • persist-review-stalled             (review-wait timer fired)          ← wedged live
+//   • persist-escalation-blockedcomments (unaddressed review comments)
+//   • persist-escalation-maxrounds       (round cap reached)
+//
+// Per ADR 0002 §1 a blank question is a NON-escalation: `pr.persist-escalation` opens no row and
+// returns `escalated:false`. The `persist-escalation-blockedcomments` arm maps its question from the
+// OPTIONAL `convergeBlockReason` process variable, so a blank reason returned `escalated:false` yet
+// STILL parked a dead `wait-answer` — a durable answer-wait with no escalation and a `null` question,
+// surfaced on the merge-driving inbox with nothing for a human to answer (observed live on three
+// instances, issue #333).
+//
+// The fix (mirroring the merge loop's `gw-merge-escalated`, PR #331): route EVERY arm that can reach
+// `wait-answer` through the single `gw-escalated` guard, so a `persist-escalation` returning
+// `escalated:false` RE-ENTERS the loop (`gw-guard`) instead of parking a dead wait. This makes the
+// invariant structural — `wait-answer` is reachable ONLY from a `gw-escalated == true` edge, so a
+// "durable answer-wait with no escalation" is unrepresentable.
+//
+// These are pure text assertions over the committed BPMN (no engine), matching the repo's
+// lightweight model-guard style (see mergeEscalationQuestion.test.ts, mergeRebaseArm.test.ts).
+
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+
+const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+// Collapse whitespace so attribute-order / line-wrapping churn doesn't make the assertions brittle.
+const flat = bpmn.replace(/\s+/g, " ");
+
+function flowHasId(id: string, source: string, target: string): boolean {
+  const m = flat.match(new RegExp(`<bpmn:sequenceFlow\\b[^>]*\\bid="${id}"[^>]*(?:/>|>)`));
+  if (!m) return false;
+  const tag = m[0];
+  return tag.includes(`sourceRef="${source}"`) && tag.includes(`targetRef="${target}"`);
+}
+
+function gatewayDefault(id: string, def: string): boolean {
+  const m = flat.match(new RegExp(`<bpmn:exclusiveGateway\\b[^>]*\\bid="${id}"[^>]*>`));
+  if (!m) return false;
+  return m[0].includes(`default="${def}"`);
+}
+
+/** The <userTask> element for wait-answer, including its incoming flows. */
+const waitAnswer = flat.match(/<bpmn:userTask\b[^>]*\bid="wait-answer"[\s\S]*?<\/bpmn:userTask>/);
+
+// Every control-flow escalation arm and the gateway edge it must now route through.
+const ARMS: ReadonlyArray<{ task: string; gate: string }> = [
+  { task: "persist-escalation-noprogress", gate: "f_noprogressGate" },
+  { task: "persist-review-stalled", gate: "f_stalledGate" },
+  { task: "persist-escalation-blockedcomments", gate: "f_blockedGate" },
+  { task: "persist-escalation-maxrounds", gate: "f_maxGate" },
+];
+
+test("every persist-escalation arm routes through gw-escalated, not straight to wait-answer", () => {
+  for (const { task, gate } of ARMS) {
+    assert(
+      flowHasId(gate, task, "gw-escalated"),
+      `${task} must route through gw-escalated (flow ${gate}), not directly to wait-answer (the #333 defect)`,
+    );
+  }
+  // The agent-verdict arm already routed through the gate — keep it.
+  assert(flowHasId("f_escGate", "persist-escalation", "gw-escalated"), "persist-escalation must route through gw-escalated");
+});
+
+test("gw-escalated honours persist-escalation's escalated output for every arm", () => {
+  // escalated:true → park the native user task for a human to answer.
+  assert(flowHasId("f_escWait", "gw-escalated", "wait-answer"), "gw-escalated → wait-answer (escalated) missing");
+  const escWait = flat.match(/<bpmn:sequenceFlow[^>]*id="f_escWait"[\s\S]*?<\/bpmn:sequenceFlow>/);
+  assert(escWait, "f_escWait flow missing");
+  assertStringIncludes(escWait![0], "escalated = true", "the wait arm must be guarded by escalated = true");
+  // escalated:false (a non-escalation, e.g. a blank convergeBlockReason) → re-enter the loop, not a dead wait.
+  assert(gatewayDefault("gw-escalated", "f_escReenter"), "gw-escalated default must re-enter the loop");
+  assert(flowHasId("f_escReenter", "gw-escalated", "gw-guard"), "the non-escalation arm must re-enter via gw-guard, not park a wait");
+});
+
+test("wait-answer is reachable ONLY from the gw-escalated == true edge (structural invariant)", () => {
+  // The single most important guarantee of #333: a durable answer-wait with no escalation is
+  // unrepresentable because the ONLY edge into wait-answer is the guarded f_escWait.
+  assert(waitAnswer, "wait-answer user task must exist");
+  const incoming = [...waitAnswer![0].matchAll(/<bpmn:incoming>([^<]+)<\/bpmn:incoming>/g)].map((m) => m[1]);
+  assert(incoming.length === 1, `wait-answer must have exactly one incoming (the guarded f_escWait); found: ${incoming.join(", ")}`);
+  assert(incoming[0] === "f_escWait", `wait-answer's only incoming must be f_escWait; found ${incoming[0]}`);
+  // The retired dead-wait edges must be gone.
+  for (const dead of ["f_noprogressWait", "f_stalledWait", "f_blockedWait", "f_maxWait"]) {
+    assert(!flat.includes(`id="${dead}"`), `the dead-wait edge ${dead} must be removed`);
+  }
+});
+
+test("each control-flow arm still carries a non-blank, human-actionable question", () => {
+  // The guard closes the wedge, but a legitimate control-flow escalation must still open a real
+  // escalation with a concrete question. Assert each arm supplies status + question via ioMapping.
+  for (const { task } of ARMS) {
+    const raw = flat.match(new RegExp(`<bpmn:serviceTask\\b[^>]*\\bid="${task}"[\\s\\S]*?</bpmn:serviceTask>`));
+    assert(raw, `${task} service task must exist`);
+    const el = raw![0];
+    assertStringIncludes(el, 'target="status"', `${task} must set an explicit status`);
+    assertStringIncludes(el, 'target="question"', `${task} must set a question`);
+  }
+});