@nanobpm/nano-workforce 0.193.1 → 0.193.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.193.2](https://github.com/nanobpm/nano-workforce/compare/v0.193.1...v0.193.2) (2026-09-29)
+
+### Bug Fixes
+
+* **convergence:** heal PR rows stuck at status=escalated after escalation answered ([#829](https://github.com/nanobpm/nano-workforce/issues/829)) ([235a004](https://github.com/nanobpm/nano-workforce/commit/235a004f73ec1b27f52b5dfe88e2f2a28c1d99e8)), closes [#642](https://github.com/nanobpm/nano-workforce/issues/642) [#828](https://github.com/nanobpm/nano-workforce/issues/828) [#828](https://github.com/nanobpm/nano-workforce/issues/828) [#828](https://github.com/nanobpm/nano-workforce/issues/828) [#828](https://github.com/nanobpm/nano-workforce/issues/828)
+
 ## [0.193.1](https://github.com/nanobpm/nano-workforce/compare/v0.193.0...v0.193.1) (2026-09-28)
 
 ### Bug Fixes

package/app/persist-escalation.test.ts

@@ -8,29 +8,56 @@
 // guard moved downstream of progress classification) and likewise passes `recordRound=false`; an
 // agent-raised arm with no prior round row omits the flag and must still record the round.
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import { assertEquals, assertRejects } from "#test-assert";
 import handler from "../workers/persist-escalation/worker.ts";
 
-function fakeApp() {
+// `failOn` forces the named table's `update` to throw, so a test can assert the escalation-insert +
+// PR-stamp transaction rolls back as a unit (issue #829 — the insert-before-timestamp window).
+function fakeApp(opts: { failOn?: string } = {}) {
   const inserts: Record<string, unknown[]> = { rounds: [], escalations: [] };
   const updates: Record<string, unknown[]> = { pull_requests: [] };
   const rows: Record<string, Map<string, unknown>> = {};
+  // `apply` decides WHEN a staged write lands: outside a transaction it applies immediately; inside
+  // `open().tx()` it is buffered and flushed only on a clean return, so a throw discards it (rollback).
+  const makeTable = (name: string, apply: (fn: () => void) => void) => {
+    const store = (rows[name] ??= new Map());
+    return {
+      async get(key: string) {
+        return store.get(key);
+      },
+      async insert(row: unknown) {
+        const pk = name === "escalations" ? "id" : name === "rounds" ? "id" : "pr_key";
+        const id = name === "escalations" ? 42 : name === "rounds" ? 1 : (row as any).pr_key;
+        const stored = pk === "id" ? { id, ...(row as Record<string, unknown>) } : row;
+        apply(() => {
+          (inserts[name] ??= []).push(row);
+          store.set((stored as any)[pk], stored);
+        });
+        return id;
+      },
+      async update(key: string, patch: unknown) {
+        if (opts.failOn === name) throw new Error(`simulated ${name} update failure`);
+        apply(() => {
+          (updates[name] ??= []).push({ key, patch });
+        });
+      },
+    };
+  };
+  const applyNow = (fn: () => void) => fn();
   const app = {
     data: {
-      table(name: string, _key: string) {
-        const store = (rows[name] ??= new Map());
+      table(name: string, _key?: string) {
+        return makeTable(name, applyNow);
+      },
+      open() {
         return {
-          async get(key: string) {
-            return store.get(key);
-          },
-          async insert(row: unknown) {
-            (inserts[name] ??= []).push(row);
-            const pk = name === "escalations" ? "id" : name === "rounds" ? "id" : "pr_key";
-            store.set((row as any)[pk], row);
-            return name === "escalations" ? 42 : 1;
-          },
-          async update(key: string, patch: unknown) {
-            (updates[name] ??= []).push({ key, patch });
+          async tx<T>(fn: (t: unknown) => Promise<T>): Promise<T> {
+            const staged: Array<() => void> = [];
+            const stage = (fn2: () => void) => staged.push(fn2);
+            const handle = { table: (name: string, _key?: string) => makeTable(name, stage) };
+            const result = await fn(handle); // a throw here skips the flush below — the staged writes roll back
+            for (const s of staged) s();
+            return result;
           },
         };
       },
@@ -50,6 +77,20 @@ test("stalled arm (recordRound=false) does not insert a duplicate rounds row", a
   assertEquals((out as any).escalationId, 42);
 });
 
+// Red/green regression for the insert-before-timestamp race (issue #829, Copilot review). The
+// escalated-PR self-heal snapshots the PR generation + open-escalation ids and fences its repair on
+// them. If this worker inserted the fresh `open` escalation BEFORE stamping the PR's `updated_at`
+// (two separate writes), a heal snapshot landing between them would see the new escalation under the
+// OLD generation and could retire it, orphaning a live user task. The insert and the PR stamp are now
+// one transaction, so they are all-or-nothing: a failed PR stamp must roll the escalation insert back
+// — proving no `open` row is ever visible while the PR still carries the pre-escalation generation.
+test("persist-escalation opens the escalation and stamps the PR atomically — a failed PR stamp rolls back the escalation insert (issue #829)", async () => {
+  const { app, inserts } = fakeApp({ failOn: "pull_requests" });
+  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "needs input" } };
+  await assertRejects(() => handler(job as any, app as any));
+  assertEquals(inserts.escalations.length, 0, "the escalation insert rolls back with the failed PR stamp — no orphan open row under the old generation");
+});
+
 test("an agent-raised arm without the flag still records the round", async () => {
   const { app, inserts } = fakeApp();
   const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "needs input" } };

package/app/persistEscalationElements.test.ts

@@ -0,0 +1,40 @@
+// Drift guard for `PR_ESCALATION_PRODUCER_ELEMENTS` (issue #829).
+//
+// The escalated-PR self-heal (`pollUserTasks` in app/service.ts) treats an ACTIVE `pr.persist-escalation`
+// PRODUCER element as positive evidence an escalation is being raised, so it must NOT retire the live
+// escalation. That guard is only as correct as the element-id set it checks against — a NEW escalation
+// arm added to either loop's BPMN, or a renamed one, would silently fall outside the set and re-open the
+// race the fix closes. This test derives the truth from the deployed BPMN: every service task whose
+// `zeebe:taskDefinition type="pr.persist-escalation"` in convergence-loop.bpmn / merge-loop.bpmn must be
+// listed in the constant, and the constant must list nothing that isn't such a task. It fails loudly on
+// either drift so the set stays the single source of truth.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { PR_ESCALATION_PRODUCER_ELEMENTS } from "./userTasks.ts";
+
+/** Extract the `id`s of every `<bpmn:serviceTask>` whose `<zeebe:taskDefinition type="pr.persist-escalation"/>`
+ *  from one BPMN file. Matches each service task element and keeps the ones carrying the producer job type. */
+function persistEscalationTaskIds(bpmnPath: string): string[] {
+  const xml = readFileSync(bpmnPath, "utf8");
+  const ids: string[] = [];
+  const taskRe = /<bpmn:serviceTask\b[^>]*\bid="([^"]+)"[\s\S]*?<\/bpmn:serviceTask>/g;
+  for (let m = taskRe.exec(xml); m !== null; m = taskRe.exec(xml)) {
+    if (/<zeebe:taskDefinition\b[^>]*\btype="pr\.persist-escalation"/.test(m[0])) ids.push(m[1]);
+  }
+  return ids;
+}
+
+test("PR_ESCALATION_PRODUCER_ELEMENTS matches every pr.persist-escalation task in both PR loops (issue #829)", () => {
+  const modelled = [
+    ...persistEscalationTaskIds("resources/processes/convergence-loop.bpmn"),
+    ...persistEscalationTaskIds("resources/processes/merge-loop.bpmn"),
+  ].sort();
+  // Sanity: the BPMN really does carry producer tasks — a zero here would make the match vacuously pass.
+  assertEquals(modelled.length > 0, true, "expected at least one pr.persist-escalation task in the BPMN");
+  assertEquals(
+    [...PR_ESCALATION_PRODUCER_ELEMENTS].sort(),
+    modelled,
+    "PR_ESCALATION_PRODUCER_ELEMENTS drifted from the pr.persist-escalation tasks modelled in the BPMN — update the constant in app/userTasks.ts",
+  );
+});

package/app/pollUserTasks.test.ts

@@ -15,6 +15,34 @@ function memData(seed: Record<string, any[]> = {}): { data: DataLayer; stores: R
   const stores: Record<string, any[]> = {};
   for (const [k, v] of Object.entries(seed)) stores[k] = v.map((r) => ({ ...r }));
   function tbl(name: string, pk = "id") {
+    // The ADR-0065 derived tracking VIEW (`<base>__tracking`) is modelled as a read-only projection
+    // over its base store, augmenting each row with `derived_status` (Copilot review of #829 — the PR
+    // self-heal now reads candidates through `prsTracking` and filters on `derived_status="escalated"`).
+    // Default `derived_status` to the base `status`, so a fixture that does NOT model out-of-band
+    // termination reads live (base status passes through). A test that wants a row the reconciler has
+    // already folded terminal seeds an explicit `derived_status` (e.g. `"abandoned"`) on the base row.
+    const trackingMatch = /^(.*)__tracking$/.exec(name);
+    if (trackingMatch) {
+      const base = (stores[trackingMatch[1]] ??= [] as any[]);
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      const project = (r: any) => ({ ...r, derived_status: r.derived_status ?? r.status });
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+      return {
+        async all() {
+          return base.map(project);
+        },
+        // biome-ignore lint/suspicious/noExplicitAny: see above
+        async get(id: any) {
+          const r = base.find((row) => row[pk] === id);
+          return r ? project(r) : undefined;
+        },
+        // biome-ignore lint/suspicious/noExplicitAny: see above
+        async find(where: any = {}) {
+          return base.map(project).filter((r) => match(r, where));
+        },
+      };
+    }
     // biome-ignore lint/suspicious/noExplicitAny: see above
     const rows = (stores[name] ??= [] as any[]);
     // biome-ignore lint/suspicious/noExplicitAny: see above
@@ -48,26 +76,107 @@ function memData(seed: Record<string, any[]> = {}): { data: DataLayer; stores: R
       },
     };
   }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as unknown as DataLayer;
+  const data = openableData(stores, tbl);
   return { data, stores };
 }
 
+/** Wrap the in-memory `stores` as a `DataLayer` that ALSO exposes `open()` → a `DataSource` with the
+ *  `exec` (guarded UPDATE) + `tx` (snapshot/rollback) surface the escalated-PR self-heal now uses for its
+ *  conditional, atomic repair (Copilot review of #829). `exec` interprets ONLY the two guarded statements
+ *  the heal issues — the snapshot-fenced `pull_requests` CAS and the by-id `escalations` retirement —
+ *  mutating the same store objects `table()` reads, so both surfaces stay consistent within a test. The
+ *  SQL shape itself is exercised against real SQLite by the app's integration/e2e suites; here the fake
+ *  need only honour the guards so a race assertion can observe the CAS refusing a moved snapshot. */
+// biome-ignore lint/suspicious/noExplicitAny: in-memory rows are untyped fixtures
+function openableData(stores: Record<string, any[]>, tbl: (name: string, pk?: string) => any): DataLayer {
+  const norm = (v: unknown) => v ?? null;
+  const exec = async (sql: string, params: unknown[] = []) => {
+    const flip =
+      /UPDATE "pull_requests" SET "status" = 'converging', "updated_at" = \? WHERE "pr_key" = \? AND "status" = 'escalated' AND "process_key" IS \? AND "updated_at" IS \?/.exec(
+        sql,
+      );
+    if (flip) {
+      const [at, prKey, processKey, updatedAt] = params;
+      const row = (stores.pull_requests ?? []).find((r) => r.pr_key === prKey);
+      if (row && row.status === "escalated" && norm(row.process_key) === norm(processKey) && norm(row.updated_at) === norm(updatedAt)) {
+        row.status = "converging";
+        row.updated_at = at;
+        return { changed: 1 };
+      }
+      return { changed: 0 };
+    }
+    const retire = /UPDATE "escalations" SET "status" = 'stale' WHERE "id" = \? AND "status" = 'open'/.exec(sql);
+    if (retire) {
+      const row = (stores.escalations ?? []).find((r) => r.id === params[0]);
+      if (row && row.status === "open") {
+        row.status = "stale";
+        return { changed: 1 };
+      }
+      return { changed: 0 };
+    }
+    throw new Error(`unexpected exec sql: ${sql}`);
+  };
+  const source: any = {
+    exec,
+    table: (n: string, pk?: string) => tbl(n, pk),
+    tx: async (fn: (t: any) => Promise<unknown>) => {
+      const snap = JSON.parse(JSON.stringify(stores));
+      try {
+        return await fn(source);
+      } catch (e) {
+        for (const [n, rows] of Object.entries(stores)) {
+          rows.length = 0;
+          rows.push(...(snap[n] ?? []));
+        }
+        throw e;
+      }
+    },
+  };
+  return { table: (n: string, pk?: string) => tbl(n, pk), open: () => source } as unknown as DataLayer;
+}
+
 /** A single engine-reported user task in the fixture. `state` mirrors the engine lifecycle; it
  *  defaults to `"CREATED"` (the only open/answerable state) so existing fixtures read as live tasks.
  *  A looping instance holds multiple tasks for one element (COMPLETED from prior rounds + the live one). */
 type FakeTask = { userTaskKey: string; elementId?: string; state?: "CREATED" | "COMPLETED" | "CANCELED"; formKey?: string };
 
+/** A single engine-reported element instance in the fixture — the answer-recording service task the
+ *  escalation self-heal probes for (issue #829). `state` mirrors the engine lifecycle; `"ACTIVE"` is the
+ *  in-flight marker that an answer is being recorded. */
+type FakeElement = { elementId: string; state: string };
+
 /** A fake engine whose user tasks are keyed by processInstanceKey (the only field the poller queries on
  *  for plan / PR instances). It models the real engine's two accessors from ONE fixture so a test
  *  genuinely exercises the lifecycle-state filtering: `searchUserTasks` returns tasks in ANY state
- *  (COMPLETED first, as the live API does — issue #294), while `openUserTasks` pins `state:"CREATED"`. */
-function fakeEngine(byInstance: Record<string, FakeTask[]>): EngineClient {
+ *  (COMPLETED first, as the live API does — issue #294), while `openUserTasks` pins `state:"CREATED"`.
+ *  `searchElementInstances` is fed from an OPTIONAL second fixture (default empty) so the PR escalation
+ *  self-heal can see an ACTIVE answer-recording task (issue #829). `searchProcessInstances` is fed from an
+ *  OPTIONAL third fixture keyed by processInstanceKey: any key NOT listed defaults to reporting the
+ *  instance `ACTIVE` (so existing heal fixtures, which model a genuinely-resumed live loop, stay green); a
+ *  value of `null` models an instance ABSENT from the read model; a string overrides its lifecycle state
+ *  (e.g. `"TERMINATED"`) — the positive-ACTIVE liveness gate the self-heal requires (issue #829). */
+function fakeEngine(
+  byInstance: Record<string, FakeTask[]>,
+  elementsByInstance: Record<string, FakeElement[]> = {},
+  instanceStateByInstance: Record<string, string | null> = {},
+): EngineClient {
   const all = (filter?: { processInstanceKey?: string }) =>
     filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : [];
   return {
     searchUserTasks: (filter?: { processInstanceKey?: string }) => Promise.resolve(all(filter)),
     openUserTasks: (filter?: { processInstanceKey?: string }) =>
       Promise.resolve(all(filter).filter((t) => (t.state ?? "CREATED") === "CREATED")),
+    searchElementInstances: (filter?: { processInstanceKey?: string }) =>
+      Promise.resolve(filter?.processInstanceKey ? (elementsByInstance[filter.processInstanceKey] ?? []) : []),
+    searchProcessInstances: (filter?: { processInstanceKeys?: string[] }) =>
+      Promise.resolve(
+        (filter?.processInstanceKeys ?? [])
+          .map((k) => {
+            const state = k in instanceStateByInstance ? instanceStateByInstance[k] : "ACTIVE";
+            return state === null ? null : { processInstanceKey: k, state };
+          })
+          .filter((it): it is { processInstanceKey: string; state: string } => it != null),
+      ),
   } as unknown as EngineClient;
 }
 
@@ -1072,3 +1181,463 @@ test("pollUserTasks (typed-seam fallback): self-heals an escalated run with no o
   const byKey = Object.fromEntries((stores.feature_runs ?? []).map((r) => [r.feature_key, r]));
   assertEquals(byKey["o/r#632"].status, "running", "the stranded escalated run is healed to running");
 });
+
+test("pollUserTasks (engine-first): self-heals an escalated PR stranded off its parked task, sparing a genuinely parked one (issue #828)", async () => {
+  // The convergence-path twin of the #642 feature heal. A PR's `status="escalated"` must hold ONLY while
+  // a `wait-answer` / `wait-merge-answer` task is open. A PR whose instance the engine no longer reports
+  // parked (its escalation was answered, but the write-side `answer-escalation` flip was lost around an
+  // app restart — the #828 tear) is reconciled to `converging`; a PR whose task IS still open is left
+  // escalated. The engine's open set is the authority, not the raw `pull_requests.status` column. The
+  // orphaned `open` escalation rows are retired to `stale` so the audit trail matches.
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#828", status: "escalated", process_key: "rp-828", url: "https://github.com/o/r/pull/828", title: "stranded" },
+      { pr_key: "o/r#77", status: "escalated", process_key: "rp-77", url: "https://github.com/o/r/pull/77", title: "still parked" },
+    ],
+    escalations: [
+      { id: 1, pr_key: "o/r#828", status: "open", question: "orphaned — never answered", answer: null, answered_at: null },
+      { id: 2, pr_key: "o/r#77", status: "open", question: "genuinely open", answer: null, answered_at: null },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    // Only rp-77 is genuinely parked; the engine reports NO open task on rp-828.
+    { userTaskKey: "ut-parked", elementId: "wait-answer", processInstanceKey: "rp-77", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({ "rp-77": [{ userTaskKey: "ut-parked", elementId: "wait-answer" }] }), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#828"].status, "converging", "the stranded escalated PR is healed to converging");
+  assertEquals(byKey["o/r#77"].status, "escalated", "the genuinely parked PR stays escalated");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "stale", "the healed PR's orphaned open escalation row is retired to stale");
+  assertEquals(escById[2].status, "open", "the genuinely parked PR's escalation row stays open");
+});
+
+test("pollUserTasks (engine-first): self-heals an escalated MERGE-loop PR off its parked wait-merge-answer task (issue #828)", async () => {
+  // Both loops write `pr.persist-escalation` (`status="escalated"`) and are answered by the same
+  // `answer-escalation` flip, so the heal must confirm against BOTH PR escalation elements — a merge
+  // escalation parks on `wait-merge-answer`.
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#828m", status: "escalated", process_key: "mp-828", url: "https://github.com/o/r/pull/828", title: "stranded merge" },
+    ],
+    escalations: [{ id: 1, pr_key: "o/r#828m", status: "open", question: "not mergeable", answer: null, answered_at: null }],
+  });
+  const restore = stubUserTaskSearch([]); // engine reports NO open task on mp-828
+  const engine = fakeEngine({ "mp-828": [] });
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#828m"].status, "converging", "the stranded escalated merge-loop PR is healed to converging");
+});
+
+test("pollUserTasks (engine-first): does NOT heal an escalated PR while its answer-recording job is in flight (issue #829)", async () => {
+  // The dangerous race: both BPMN models flow the completed `wait-answer` / `wait-merge-answer` user task
+  // DIRECTLY to the `record-answer` / `record-merge-answer` service task (`pr.answer-escalation`). Between
+  // the operator completing the task and that job running, the user task is already gone (openUserTasks
+  // returns none) yet the answer is being recorded RIGHT NOW. The escalation can be arbitrarily old (past
+  // the raise-time grace), so the grace window does not cover this. Healing here would flip the row to
+  // `converging` and retire the still-`open` escalation to `stale`, and the in-flight worker would then
+  // find no target and silently drop the operator's answer. An ACTIVE answer-recording element instance is
+  // positive evidence the answer is in flight, so the heal must skip it — exactly like an open task.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#829r", status: "escalated", process_key: "rp-829r", updated_at: stale, url: "https://github.com/o/r/pull/829", title: "answer in flight (review)" },
+      { pr_key: "o/r#829m", status: "escalated", process_key: "rp-829m", updated_at: stale, url: "https://github.com/o/r/pull/8290", title: "answer in flight (merge)" },
+    ],
+    escalations: [
+      { id: 1, pr_key: "o/r#829r", status: "open", question: "answered, recording", answer: "do it", answered_at: stale },
+      { id: 2, pr_key: "o/r#829m", status: "open", question: "answered, recording", answer: "rebase", answered_at: stale },
+    ],
+  });
+  const restore = stubUserTaskSearch([]); // the user task has already completed on both instances
+  // Each instance's answer-recording service task is ACTIVE — the operator's answer is being written.
+  const engine = fakeEngine(
+    { "rp-829r": [], "rp-829m": [] },
+    {
+      "rp-829r": [{ elementId: "record-answer", state: "ACTIVE" }],
+      "rp-829m": [{ elementId: "record-merge-answer", state: "ACTIVE" }],
+    },
+  );
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#829r"].status, "escalated", "a PR with an in-flight review answer-recorder is spared the heal");
+  assertEquals(byKey["o/r#829m"].status, "escalated", "a PR with an in-flight merge answer-recorder is spared the heal");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "open", "the in-flight review escalation row is left for the worker to answer");
+  assertEquals(escById[2].status, "open", "the in-flight merge escalation row is left for the worker to answer");
+});
+
+test("pollUserTasks (engine-first): DOES heal an escalated PR once its answer-recorder has completed (issue #829)", async () => {
+  // The genuine #828 lost-write tear: the answer-recording job COMPLETED (its element instance is no
+  // longer ACTIVE) but the durable `status="converging"` flip was lost around an app restart. With no open
+  // task AND no ACTIVE answer-recorder, the PR is genuinely stranded and must heal — the in-flight guard
+  // must not over-fire and wedge it permanently.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [{ pr_key: "o/r#829c", status: "escalated", process_key: "rp-829c", updated_at: stale, url: "https://github.com/o/r/pull/8291", title: "recorder completed, write lost" }],
+    escalations: [{ id: 1, pr_key: "o/r#829c", status: "open", question: "orphaned", answer: null, answered_at: null }],
+  });
+  const restore = stubUserTaskSearch([]);
+  const engine = fakeEngine({ "rp-829c": [] }, { "rp-829c": [{ elementId: "record-answer", state: "COMPLETED" }] });
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#829c"].status, "converging", "a stranded PR whose answer-recorder already completed is healed");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "stale", "the orphaned open escalation row is retired to stale");
+});
+
+test("pollUserTasks (engine-first): does NOT heal an escalated PR whose process instance is TERMINAL (issue #829)", async () => {
+  // Copilot review of the #828 heal: "no open task and no ACTIVE escalation element" is ALSO true for a
+  // TERMINAL instance (cancelled / completed / failed), whose loop never resumed. Flipping such a frozen
+  // `escalated` row to `converging` and retiring its audit rows fabricates a live loop the engine will
+  // never advance; terminal PRs are owned by tracking/reconciliation (they read `abandoned`/settled on
+  // `derived_status`). The heal now requires POSITIVE engine-truth that the instance is `ACTIVE`, so a
+  // TERMINATED (and, below, an absent) instance is spared. One case per known terminal state.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#829tt", status: "escalated", process_key: "rp-829tt", updated_at: stale, url: "https://github.com/o/r/pull/8297", title: "terminated instance" },
+      { pr_key: "o/r#829tc", status: "escalated", process_key: "rp-829tc", updated_at: stale, url: "https://github.com/o/r/pull/8298", title: "cancelled instance" },
+    ],
+    escalations: [
+      { id: 1, pr_key: "o/r#829tt", status: "open", question: "loop gone", answer: null, answered_at: null },
+      { id: 2, pr_key: "o/r#829tc", status: "open", question: "loop gone", answer: null, answered_at: null },
+    ],
+  });
+  const restore = stubUserTaskSearch([]); // no open task — but the loop is dead, not merely mid-transition
+  // No open task, no ACTIVE escalation element, but the instance itself is a known terminal state.
+  const engine = fakeEngine(
+    { "rp-829tt": [], "rp-829tc": [] },
+    {},
+    { "rp-829tt": "TERMINATED", "rp-829tc": "CANCELED" },
+  );
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#829tt"].status, "escalated", "a TERMINATED instance is left to tracking/reconciliation, not healed");
+  assertEquals(byKey["o/r#829tc"].status, "escalated", "a CANCELED instance is left to tracking/reconciliation, not healed");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "open", "the terminal instance's escalation row is not retired");
+  assertEquals(escById[2].status, "open", "the cancelled instance's escalation row is not retired");
+});
+
+test("pollUserTasks (engine-first): does NOT heal an escalated PR whose process instance is ABSENT / unknown-state (issue #829)", async () => {
+  // The other halves of the tri-state (Copilot review of #828): an instance genuinely ABSENT from the
+  // read model (engine answered, no match) is treated like a terminal — its loop is gone, so leave it to
+  // tracking rather than fabricate a resumed loop. An instance present with an UNKNOWN/empty `state` is a
+  // partial read this app cannot interpret and is SPARED (never healed off a wire shape we misread). Both
+  // stay `escalated`. One case each.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#829ab", status: "escalated", process_key: "rp-829ab", updated_at: stale, url: "https://github.com/o/r/pull/8299", title: "absent instance" },
+      { pr_key: "o/r#829uk", status: "escalated", process_key: "rp-829uk", updated_at: stale, url: "https://github.com/o/r/pull/82990", title: "unknown-state instance" },
+    ],
+    escalations: [
+      { id: 1, pr_key: "o/r#829ab", status: "open", question: "loop gone", answer: null, answered_at: null },
+      { id: 2, pr_key: "o/r#829uk", status: "open", question: "partial read", answer: null, answered_at: null },
+    ],
+  });
+  const restore = stubUserTaskSearch([]);
+  // `null` models an instance absent from the read model; a blank string models an unknown/partial state.
+  const engine = fakeEngine({ "rp-829ab": [], "rp-829uk": [] }, {}, { "rp-829ab": null, "rp-829uk": "" });
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#829ab"].status, "escalated", "an ABSENT instance is left to tracking/reconciliation, not healed");
+  assertEquals(byKey["o/r#829uk"].status, "escalated", "an UNKNOWN-state instance is spared, not healed off a misread wire shape");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "open", "the absent instance's escalation row is not retired");
+  assertEquals(escById[2].status, "open", "the unknown-state instance's escalation row is not retired");
+});
+
+test("pollUserTasks (engine-first): a terminated-while-escalated PR is EXCLUDED by the derived tracking VIEW — never probed (issue #829)", async () => {
+  // Copilot review of #829: the candidate scan reads through `prsTracking` and requires
+  // `derived_status="escalated"`, so a PR TERMINATED while its base status was `escalated` — whose VIEW
+  // folds `derived_status` to `abandoned` — is excluded BEFORE any per-instance probe. Without the VIEW
+  // filter this historical row would be reselected every poll and burn engine RPCs forever. We seed an
+  // explicit `derived_status: "abandoned"` (the reconciler's terminal fold) and assert the heal issues NO
+  // engine RPC for it at all, and its frozen base row / escalation are left untouched.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#829term", status: "escalated", derived_status: "abandoned", process_key: "rp-829term", updated_at: stale, url: "https://github.com/o/r/pull/82991", title: "terminated-while-escalated (VIEW-folded)" },
+    ],
+    escalations: [{ id: 1, pr_key: "o/r#829term", status: "open", question: "loop gone", answer: null, answered_at: null }],
+  });
+  const restore = stubUserTaskSearch([]);
+  const probed: string[] = [];
+  const engine = {
+    searchUserTasks: () => Promise.resolve([]),
+    openUserTasks: (f?: { processInstanceKey?: string }) => {
+      if (f?.processInstanceKey) probed.push(f.processInstanceKey);
+      return Promise.resolve([]);
+    },
+    searchElementInstances: (f?: { processInstanceKey?: string }) => {
+      if (f?.processInstanceKey) probed.push(f.processInstanceKey);
+      return Promise.resolve([]);
+    },
+    searchProcessInstances: (f?: { processInstanceKeys?: string[] }) => {
+      for (const k of f?.processInstanceKeys ?? []) probed.push(k);
+      return Promise.resolve([]);
+    },
+  } as unknown as EngineClient;
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  assertEquals(probed.includes("rp-829term"), false, "a VIEW-folded terminal row is excluded from the scan — no engine RPC is issued for it");
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#829term"].status, "escalated", "the terminated row's frozen base status is left to tracking, not rewritten");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "open", "the terminated row's escalation is not retired");
+});
+
+test("pollUserTasks (engine-first): does NOT heal an escalated PR while its persist-escalation producer is still ACTIVE (issue #829)", async () => {
+  // The producer-side twin of the answer-recorder race. `pr.persist-escalation` COMMITS the `open` row and
+  // `status="escalated"` BEFORE the engine creates the `wait-answer` user task, so there is a window with an
+  // `escalated` PR, an `open` escalation, and NO user task yet. The raise-time grace normally covers it, but
+  // if the producer service task stays ACTIVE past the grace (an app restart / lease delay between the DB
+  // commit and the job completing) the row is old enough to heal while the escalation is being raised RIGHT
+  // NOW. Healing here would retire the just-raised escalation to `stale` and the question would never surface.
+  // An ACTIVE persist-escalation element is positive evidence, so the heal must skip it — one case per loop.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#829pr", status: "escalated", process_key: "rp-829pr", updated_at: stale, url: "https://github.com/o/r/pull/8293", title: "producer active (review)" },
+      { pr_key: "o/r#829pm", status: "escalated", process_key: "rp-829pm", updated_at: stale, url: "https://github.com/o/r/pull/8294", title: "producer active (merge)" },
+    ],
+    escalations: [
+      { id: 1, pr_key: "o/r#829pr", status: "open", question: "being raised", answer: null, answered_at: null },
+      { id: 2, pr_key: "o/r#829pm", status: "open", question: "being raised", answer: null, answered_at: null },
+    ],
+  });
+  const restore = stubUserTaskSearch([]); // the user task does not exist yet — the producer hasn't completed
+  const engine = fakeEngine(
+    { "rp-829pr": [], "rp-829pm": [] },
+    {
+      "rp-829pr": [{ elementId: "persist-escalation-blockedcomments", state: "ACTIVE" }],
+      "rp-829pm": [{ elementId: "merge-esc-conflict", state: "ACTIVE" }],
+    },
+  );
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#829pr"].status, "escalated", "a PR with an ACTIVE review persist-escalation producer is spared the heal");
+  assertEquals(byKey["o/r#829pm"].status, "escalated", "a PR with an ACTIVE merge persist-escalation producer is spared the heal");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "open", "the just-raised review escalation row is left open");
+  assertEquals(escById[2].status, "open", "the just-raised merge escalation row is left open");
+});
+
+test("pollUserTasks (engine-first): does NOT heal an escalated PR when the producer→user-task transition lands BETWEEN the two engine reads (issue #829)", async () => {
+  // The producer→user-task TOCTOU the prior two guards miss. `openUserTasks()` (read 1) returns empty while
+  // a long-running persist producer is still ACTIVE; that producer then COMPLETES and the engine creates the
+  // `wait-answer` / `wait-merge-answer` user task BEFORE `searchElementInstances()` (read 2). Read 2 therefore
+  // sees an ACTIVE wait element — NOT the producer. Because user-task creation does not re-stamp the PR row's
+  // `updated_at` (only `pr.persist-escalation` does, before the task exists), the row is past the raise-time
+  // grace, so neither the grace nor the producer/answer-recorder predicate covers it: a predicate that ignores
+  // the wait elements lets the CAS win and stale a live escalation. Treat an ACTIVE `wait-answer` /
+  // `wait-merge-answer` element as positive evidence in the second snapshot too — one case per loop.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#829wr", status: "escalated", process_key: "rp-829wr", updated_at: stale, url: "https://github.com/o/r/pull/8295", title: "producer→wait (review)" },
+      { pr_key: "o/r#829wm", status: "escalated", process_key: "rp-829wm", updated_at: stale, url: "https://github.com/o/r/pull/8296", title: "producer→wait (merge)" },
+    ],
+    escalations: [
+      { id: 1, pr_key: "o/r#829wr", status: "open", question: "raised mid-read", answer: null, answered_at: null },
+      { id: 2, pr_key: "o/r#829wm", status: "open", question: "raised mid-read", answer: null, answered_at: null },
+    ],
+  });
+  // The typed `openUserTasks` seam reports NO open task (the producer was still ACTIVE at read 1), while the
+  // element search (read 2) now sees the freshly-created wait element ACTIVE — the transition landed mid-read.
+  const restore = stubUserTaskSearch([]);
+  const engine = fakeEngine(
+    { "rp-829wr": [], "rp-829wm": [] },
+    {
+      "rp-829wr": [{ elementId: "wait-answer", state: "ACTIVE" }],
+      "rp-829wm": [{ elementId: "wait-merge-answer", state: "ACTIVE" }],
+    },
+  );
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#829wr"].status, "escalated", "a PR whose wait-answer appeared mid-read is spared the heal");
+  assertEquals(byKey["o/r#829wm"].status, "escalated", "a PR whose wait-merge-answer appeared mid-read is spared the heal");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "open", "the live review escalation row is left open");
+  assertEquals(escById[2].status, "open", "the live merge escalation row is left open");
+});
+
+test("pollUserTasks (engine-first): a re-escalation in the read→write window is NOT clobbered — the guarded CAS refuses the moved snapshot (issue #829)", async () => {
+  // The TOCTOU race Copilot flagged: the heal reads the PR, then does two remote engine RPCs, THEN writes.
+  // If the SAME instance re-escalates in that window (`pr.persist-escalation` re-stamps `updated_at` and
+  // INSERTs a fresh open escalation), a blind write would clobber the fresh `escalated` status and stale
+  // the fresh escalation — dropping the operator's next answer. We reproduce the concurrent re-escalation
+  // by mutating the store from inside `searchElementInstances` (the last read before the write), then
+  // assert the snapshot-fenced CAS makes NO change: the PR stays `escalated` and the fresh escalation open.
+  // NB the mutation advances `updated_at` AND inserts the fresh escalation TOGETHER, modelling the now-atomic
+  // `pr.persist-escalation` producer (its insert + PR re-stamp share one transaction, issue #829) — so a
+  // captured snapshot can never see the new escalation under the OLD generation; the covering red/green for
+  // that producer atomicity lives in app/persist-escalation.test.ts.
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [{ pr_key: "o/r#829race", status: "escalated", process_key: "rp-829race", updated_at: stale, url: "https://github.com/o/r/pull/8292", title: "re-escalates mid-heal" }],
+    escalations: [{ id: 1, pr_key: "o/r#829race", status: "open", question: "first", answer: null, answered_at: null }],
+  });
+  const restore = stubUserTaskSearch([]);
+  let reEscalated = false;
+  const engine = {
+    searchUserTasks: () => Promise.resolve([]),
+    openUserTasks: () => Promise.resolve([]),
+    // Report the instance ACTIVE so the heal reaches its guarded CAS (Copilot review of #829): without a
+    // `searchProcessInstances` response the positive-liveness probe throws, sets `queryErrored`, and the
+    // row would be spared for the WRONG reason — never exercising the snapshot-fenced CAS this test asserts.
+    searchProcessInstances: () => Promise.resolve([{ processInstanceKey: "rp-829race", state: "ACTIVE" }]),
+    searchElementInstances: (filter?: { processInstanceKey?: string }) => {
+      // Simulate the concurrent re-escalation landing AFTER the heal captured its snapshot but BEFORE its
+      // write: the row's generation advances (`updated_at`) and a brand-new open escalation is inserted.
+      if (filter?.processInstanceKey === "rp-829race" && !reEscalated) {
+        reEscalated = true;
+        const row = (stores.pull_requests ?? []).find((r) => r.pr_key === "o/r#829race");
+        if (row) row.updated_at = new Date().toISOString();
+        (stores.escalations ?? []).push({ id: 2, pr_key: "o/r#829race", status: "open", question: "second", answer: null, answered_at: null });
+      }
+      return Promise.resolve([{ elementId: "record-answer", state: "COMPLETED" }]);
+    },
+  } as unknown as EngineClient;
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#829race"].status, "escalated", "the re-escalated PR is left escalated — the CAS refused the moved snapshot");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[2].status, "open", "the fresh escalation opened in the window is NOT retired");
+  assertEquals(escById[1].status, "open", "the snapshot's own escalation is left untouched too — the whole tx rolled to a no-op");
+});
+
+test("pollUserTasks (engine-first): skips the per-instance open-task RPC for an escalated PR already seen parked in this pass's sweep (issue #828)", async () => {
+  // best-effort sweep may truncate (drop tasks) but never invents one. Re-confirming with a per-instance
+  // `openUserTasks` RPC is a redundant N+1 query; the self-heal must skip it. Only a PR NOT confirmed
+  // parked by the sweep still needs the per-instance check.
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#parked", status: "escalated", process_key: "rp-parked", url: "https://github.com/o/r/pull/1", title: "parked" },
+      { pr_key: "o/r#stranded", status: "escalated", process_key: "rp-stranded", url: "https://github.com/o/r/pull/2", title: "stranded" },
+    ],
+    escalations: [{ id: 1, pr_key: "o/r#parked", status: "open", question: "open", answer: null, answered_at: null }],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-parked", elementId: "wait-answer", processInstanceKey: "rp-parked", state: "CREATED" },
+  ]);
+  const openUserTasksCalls: string[] = [];
+  const engine = {
+    searchUserTasks: () => Promise.resolve([]),
+    openUserTasks: (filter?: { processInstanceKey?: string }) => {
+      if (filter?.processInstanceKey) openUserTasksCalls.push(filter.processInstanceKey);
+      return Promise.resolve([]);
+    },
+    searchElementInstances: () => Promise.resolve([]),
+    // The stranded instance genuinely resumed (ACTIVE) — so the sweep-miss falls through to the
+    // per-instance confirm AND the positive-liveness gate, and heals (issue #829).
+    searchProcessInstances: (filter?: { processInstanceKeys?: string[] }) =>
+      Promise.resolve((filter?.processInstanceKeys ?? []).map((k) => ({ processInstanceKey: k, state: "ACTIVE" }))),
+  } as unknown as EngineClient;
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#parked"].status, "escalated", "the swept-parked PR stays escalated without a per-instance query");
+  assertEquals(byKey["o/r#stranded"].status, "converging", "the PR absent from the sweep is still confirmed per-instance and healed");
+  assertEquals(openUserTasksCalls.includes("rp-parked"), false, "no redundant per-instance RPC for the already-parked PR");
+  assertEquals(openUserTasksCalls.includes("rp-stranded"), true, "the unconfirmed PR still needs the per-instance RPC");
+});
+
+test("pollUserTasks (engine-first): does NOT heal an escalated PR when the per-instance open-task query errors (issue #828)", async () => {
+  // A per-instance query error is not proof the PR is unparked — mutating on that negative evidence would
+  // steal a parked escalation. On query error the PR must be left `escalated` for a later pass.
+  const { data, stores } = memData({
+    pull_requests: [{ pr_key: "o/r#err", status: "escalated", process_key: "rp-err", url: "https://github.com/o/r/pull/9", title: "query errors" }],
+    escalations: [{ id: 1, pr_key: "o/r#err", status: "open", question: "open", answer: null, answered_at: null }],
+  });
+  const restore = stubUserTaskSearch([]);
+  const engine = {
+    searchUserTasks: () => Promise.resolve([]),
+    openUserTasks: (filter?: { processInstanceKey?: string }) =>
+      filter?.processInstanceKey === "rp-err" ? Promise.reject(new Error("engine down")) : Promise.resolve([]),
+    searchElementInstances: () => Promise.resolve([]),
+  } as unknown as EngineClient;
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#err"].status, "escalated", "a failed per-instance query leaves the PR escalated");
+  const escById = Object.fromEntries((stores.escalations ?? []).map((r) => [r.id, r]));
+  assertEquals(escById[1].status, "open", "the escalation row is untouched when the heal is skipped");
+});
+
+test("pollUserTasks (engine-first): does NOT heal a JUST-escalated PR inside the grace window before its user task exists (issue #828)", async () => {
+  // `pr.persist-escalation` stamps `status="escalated"` (and `updated_at`) IMMEDIATELY BEFORE the engine
+  // creates the `wait-answer` user task. A poll landing in that window sees `openUserTasks` return none
+  // and would wrongly flip the fresh escalation back to `converging`. A short grace window on `updated_at`
+  // spares a just-written escalation while still healing genuinely-stranded (old) rows.
+  const fresh = new Date().toISOString();
+  const stale = new Date(Date.now() - 60 * 60_000).toISOString();
+  const { data, stores } = memData({
+    pull_requests: [
+      { pr_key: "o/r#fresh", status: "escalated", process_key: "rp-fresh", updated_at: fresh, url: "https://github.com/o/r/pull/3", title: "just escalated" },
+      { pr_key: "o/r#old", status: "escalated", process_key: "rp-old", updated_at: stale, url: "https://github.com/o/r/pull/4", title: "genuinely stranded" },
+    ],
+    escalations: [
+      { id: 1, pr_key: "o/r#fresh", status: "open", question: "fresh", answer: null, answered_at: null },
+      { id: 2, pr_key: "o/r#old", status: "open", question: "old", answer: null, answered_at: null },
+    ],
+  });
+  const restore = stubUserTaskSearch([]);
+  const engine = fakeEngine({});
+  try {
+    await pollUserTasks(data, engine, REST);
+  } finally {
+    restore();
+  }
+  const byKey = Object.fromEntries((stores.pull_requests ?? []).map((r) => [r.pr_key, r]));
+  assertEquals(byKey["o/r#fresh"].status, "escalated", "a just-escalated PR inside the grace window is spared the heal");
+  assertEquals(byKey["o/r#old"].status, "converging", "a genuinely-stranded (old) PR is still healed");
+});

package/app/service.ts

@@ -106,6 +106,9 @@ import {
   latestTrialMergeQuestion,
   type OpenEscalation,
   PLAN_REVIEW_ELEMENT,
+  PR_ESCALATION_PRODUCER_ELEMENTS,
+  PR_RECORD_ANSWER_ELEMENT,
+  PR_RECORD_MERGE_ANSWER_ELEMENT,
   PR_WAIT_ANSWER_ELEMENT,
   PR_WAIT_MERGE_ANSWER_ELEMENT,
   prEscalations,
@@ -251,6 +254,15 @@ export const REVIEW_NUDGE_MS = clampNudgeMinutes(process.env.NANO_PR_REVIEW_NUDG
  * still reconciling genuinely-stranded rows. */
 export const FEATURE_ESCALATION_HEAL_GRACE_MS = 60_000;
 
+/** Grace window (ms) before the `escalated`→`converging` PR self-heal (below) may act on a row — the
+ * convergence-path twin of `FEATURE_ESCALATION_HEAL_GRACE_MS` (issue #828). The sole writer of a PR's
+ * `status="escalated"` — `pr.persist-escalation` — stamps the row IMMEDIATELY BEFORE the engine creates
+ * the `wait-answer` / `wait-merge-answer` user task. A poll landing in that window would see
+ * `openUserTasks` report none and wrongly heal the just-raised escalation back to `converging`, hiding
+ * it before the operator can answer. Only heal rows whose escalation is older than this window, by when
+ * the user task must already be observable. */
+export const PR_ESCALATION_HEAL_GRACE_MS = 60_000;
+
 /** Whether a converged PR is automatically driven to merge (the merge-loop). Default on; set
  * `NANO_PR_AUTO_MERGE=0` to stop at `converged` (review-only mode). */
 export const AUTO_MERGE = !["0", "false", "off", "no"].includes(
@@ -3325,6 +3337,152 @@ export async function pollUserTasks(
     if (queryErrored || stillParked) continue;
     await featureRuns(data).update(run.feature_key, { status: "running", updated_at: at });
   }
+
+  // ── Self-heal: a convergence PR row holds `escalated` ONLY while parked (issue #828) ─────────────
+  // The convergence-path twin of the feature self-heal above (issue #642). `pr.persist-escalation` is
+  // the sole writer of a PR's `status="escalated"`, and the sole writer that moves it back off is the
+  // `pr.answer-escalation` worker (the guarded `UPDATE … SET status='converging'` on user-task
+  // completion). When that write is lost — e.g. the app restarts while a `wait-answer` completion /
+  // `answer-escalation` job is in flight — the engine resumes the loop (token back on `review-round`,
+  // no open user task) but the PR row stays `escalated` forever, since NOTHING on the PR path repairs
+  // it (unlike the feature path). `/status` then shows `status="escalated"` with a null derived
+  // `openEscalation` indefinitely, inviting a human to answer an already-answered question.
+  //
+  // Heal it engine-first, on the SAME positive-evidence contract as the feature sweep: a PR at
+  // `status="escalated"` is reconciled back to `converging` only when the engine confirms NO open PR
+  // escalation task (`wait-answer` / `wait-merge-answer`) for its instance. As above, presence in THIS
+  // pass's `desired` set is itself positive evidence of parking (truncation only ever DROPS tasks), so a
+  // PR whose escalation task was already swept is genuinely parked — skip its per-instance RPC. Only a
+  // PR not confirmed parked by the sweep falls through to the per-instance `openUserTasks` check, and a
+  // query error is negative evidence (skip the heal), so durable state flips only on positive proof.
+  //
+  // Candidate set: read through the ADR-0065 derived tracking VIEW and require `derived_status="escalated"`
+  // (Copilot review of #829). A PR TERMINATED while its base status was `escalated` keeps that frozen base
+  // status forever — the reconciler never rewrites it (app/instanceTracking.ts) — so a raw `prs.find({
+  // status:"escalated" })` scan would reselect every such HISTORICAL row on every poll and burn up to three
+  // sequential engine RPCs on each, indefinitely. The VIEW folds the terminal edge to `derived_status`
+  // (out-of-band terminate → `abandoned`), so filtering on `derived_status="escalated"` bounds the pass to
+  // LIVE/UNKNOWN candidates and leaves terminal rows to tracking as intended; the ACTIVE-instance gate below
+  // is the correctness backstop for a candidate the VIEW hasn't yet reconciled. Writes still target `prs`.
+  const sweptParkedPrEscalations = new Set<string>();
+  for (const r of desired) {
+    if (r.element_id !== PR_WAIT_ANSWER_ELEMENT && r.element_id !== PR_WAIT_MERGE_ANSWER_ELEMENT) continue;
+    if (r.subject_type !== "pr") continue;
+    if (r.process_key) sweptParkedPrEscalations.add(r.process_key);
+    if (r.subject_key) sweptParkedPrEscalations.add(r.subject_key);
+  }
+  for (const pr of await prsTracking(data).find({ derived_status: "escalated" })) {
+    if (!pr.process_key) continue;
+    if (sweptParkedPrEscalations.has(pr.process_key) || sweptParkedPrEscalations.has(pr.pr_key)) continue; // parked this pass — no RPC, no heal
+    // Don't race a just-raised escalation: `pr.persist-escalation` stamps `updated_at` immediately
+    // before the engine creates the user task, so heal only rows past the grace window.
+    const escalatedAt = Date.parse(pr.updated_at ?? "");
+    if (Number.isFinite(escalatedAt) && Date.now() - escalatedAt < PR_ESCALATION_HEAL_GRACE_MS) continue;
+    // Snapshot the PR generation (`process_key` + `updated_at`) and the `open` escalation rows we observe
+    // NOW — BEFORE the remote engine reads below. The repair writes are fenced on this snapshot, so a
+    // FRESH escalation the SAME instance opens in the read→write window is neither clobbered nor retired.
+    // The convergence loop REUSES one process instance across rounds, so a re-escalation keeps the same
+    // `process_key`; the discriminator is `updated_at`, which `pr.persist-escalation` re-stamps every time
+    // it writes `status="escalated"`. Capturing the open-escalation ids here (not re-reading `status=open`
+    // after the write) means a fresh escalation row — a NEW id inserted after this point — is never retired
+    // to `stale` even though it is `open`, since it was not part of the snapshot we healed (issue #829).
+    const snapshotProcessKey = pr.process_key;
+    const snapshotUpdatedAt = pr.updated_at ?? null;
+    const snapshotOpenEscalationIds = (await escs(data).find({ pr_key: pr.pr_key, status: "open" })).map((e) => e.id);
+    let stillParked = false;
+    let escalationInFlight = false;
+    let instanceActive = false;
+    let queryErrored = false;
+    try {
+      const openTasks = await engine.openUserTasks({ processInstanceKey: pr.process_key });
+      stillParked = openTasks.some((t) => t.elementId === PR_WAIT_ANSWER_ELEMENT || t.elementId === PR_WAIT_MERGE_ANSWER_ELEMENT);
+      // An empty open-task set is NOT yet proof the escalation is dead. Two distinct DB/engine boundaries
+      // each leave the row `escalated` with NO open user task while an escalation is genuinely live:
+      //
+      //   1. The ANSWER side. `pr.answer-escalation` (`record-answer` / `record-merge-answer`) is the sole
+      //      writer that moves a PR OFF `escalated`, and both BPMN models flow the completed `wait-answer` /
+      //      `wait-merge-answer` user task DIRECTLY to that service task. So a normal answer has a window
+      //      where the user task is already gone (this query returns none) while the answer-recording job is
+      //      still queued or running.
+      //   2. The PRODUCER side. `pr.persist-escalation` (the `PR_ESCALATION_PRODUCER_ELEMENTS`) COMMITS the
+      //      `open` row and `status="escalated"` IMMEDIATELY BEFORE the engine creates the `wait-answer` /
+      //      `wait-merge-answer` user task. The raise-time grace window covers the normal case, but if that
+      //      producer service task stays ACTIVE past the grace (e.g. an app restart / lease delay between
+      //      the DB commit and the job completing) the row is old enough to heal yet no user task exists.
+      //   3. The PRODUCER→USER-TASK TOCTOU BETWEEN THE TWO READS. `openUserTasks` (read 1) can return empty
+      //      while a persist producer is still ACTIVE; that producer then COMPLETES and the engine creates
+      //      the `wait-answer` / `wait-merge-answer` user task BEFORE `searchElementInstances` (read 2). Read 2
+      //      then sees an ACTIVE WAIT element — not the producer. Because user-task creation does NOT re-stamp
+      //      the PR row's `updated_at` (only `pr.persist-escalation` does, before the task exists), the row is
+      //      past the grace, so neither the grace nor the producer/answer-recorder check covers it. Treat an
+      //      ACTIVE wait element as positive evidence here too, or the CAS wins and stales a live escalation.
+      //
+      // In EITHER window the escalation is arbitrarily old (past the raise-time grace), so the grace above
+      // does not cover it. Healing here flips the row to `converging` and retires the still-`open`
+      // escalation to `stale`, and the live escalation is lost — the answer-recorder finds no target and
+      // silently drops the operator's answer, or the just-raised question never surfaces (issue #829). An
+      // ACTIVE answer-recording, persist-escalation, OR wait-answer/wait-merge-answer element instance is
+      // positive evidence an escalation is in flight, so treat it exactly like an open task and skip the
+      // heal. But even a PR with NEITHER an open task NOR any ACTIVE escalation element is NOT yet
+      // heal-eligible — it must ALSO be a confirmed-ACTIVE instance (the positive-liveness gate below);
+      // a terminal/absent instance matches this negative shape too but never resumed (the #828 tear).
+      if (!stillParked) {
+        const elements = await engine.searchElementInstances({ processInstanceKey: pr.process_key });
+        escalationInFlight = elements.some(
+          (el) =>
+            el.state === "ACTIVE" &&
+            (el.elementId === PR_RECORD_ANSWER_ELEMENT ||
+              el.elementId === PR_RECORD_MERGE_ANSWER_ELEMENT ||
+              el.elementId === PR_WAIT_ANSWER_ELEMENT ||
+              el.elementId === PR_WAIT_MERGE_ANSWER_ELEMENT ||
+              (el.elementId != null && PR_ESCALATION_PRODUCER_ELEMENTS.includes(el.elementId))),
+        );
+      }
+      // "No open task and no in-flight escalation element" is necessary but NOT sufficient to heal
+      // (Copilot review of #829). A TERMINAL or ABSENT process instance — one cancelled, completed, or
+      // dropped from the read model — ALSO reports no open task and no ACTIVE escalation element, yet its
+      // loop never resumed: flipping such a frozen `escalated` row to `converging` and retiring its audit
+      // rows fabricates a live loop the engine will never advance. Terminal/absent PRs are owned by the
+      // ADR-0065 derived tracking + reconciliation (they read `abandoned`/settled on `derived_status`), so
+      // leave them be. Require POSITIVE engine-truth that the instance is `ACTIVE` before healing — the
+      // same tri-state contract as the feature-handoff probe (search ~L2562) and `makeEngineActiveProbe`
+      // (app/reconcile.ts): ONLY a confirmed `ACTIVE` state heals; a known-terminal or genuinely-absent
+      // instance is left to tracking; a missing/empty/unknown `state` (or a query error) is spared, never
+      // healed off a wire shape we misread. So a healed row is provably the #828 lost-write tear: an
+      // ACTIVE loop that resumed but whose `status="converging"` flip was lost.
+      const snapshots = await engine.searchProcessInstances({ processInstanceKeys: [pr.process_key] });
+      const match = snapshots.find((s) => String(s.processInstanceKey) === pr.process_key);
+      instanceActive = match != null && String(match.state ?? "").trim().toUpperCase() === "ACTIVE";
+    } catch (err) {
+      console.error(`[poller] escalated-pr self-heal (${pr.pr_key} @ ${pr.process_key}): ${err}`);
+      queryErrored = true;
+    }
+    if (queryErrored || stillParked || escalationInFlight || !instanceActive) continue;
+    // Repair conditionally and atomically (Copilot review of #829). The read→write window between the
+    // engine reads above and here is wide (two remote RPCs), so the PR may have re-escalated on the same
+    // instance meanwhile; a blind `update` would then overwrite that fresh `escalated` status and retire
+    // its new `open` escalation. The PR flip is therefore a SINGLE guarded UPDATE fenced on the inspected
+    // snapshot — still `escalated`, same `process_key`, same `updated_at` — an atomic compare-and-swap
+    // (SQLite serialises it against the worker's guarded writes in the other process). Only when that CAS
+    // WON (`changed === 1`) do we retire the snapshot's own orphan escalation rows, in the SAME
+    // transaction: a crash can never leave a healed PR with a dangling `open` row, nor an un-healed PR
+    // with retired rows — a rolled-back heal is simply retried by a later pass. Retiring by the captured
+    // snapshot ids (never a fresh `status=open` re-read) means a just-opened escalation is left untouched.
+    const db = data.open();
+    await db.tx(async (t) => {
+      const flipped = await t.exec(
+        `UPDATE "pull_requests" SET "status" = 'converging', "updated_at" = ? WHERE "pr_key" = ? AND "status" = 'escalated' AND "process_key" IS ? AND "updated_at" IS ?`,
+        [at, pr.pr_key, snapshotProcessKey, snapshotUpdatedAt],
+      );
+      if (flipped.changed !== 1) return; // snapshot moved (a fresh escalation re-stamped the row) — leave it for a later pass
+      // Retire the orphaned `open` escalation rows so the audit trail matches the healed PR row — the
+      // `answer-escalation` write that would have answered/retired them was the very write we lost. We
+      // mark them `stale` (not `answered`) because no operator answer was recorded for them.
+      for (const escId of snapshotOpenEscalationIds) {
+        await t.exec(`UPDATE "escalations" SET "status" = 'stale' WHERE "id" = ? AND "status" = 'open'`, [escId]);
+      }
+    });
+  }
 }
 
 /** One full poll pass: advance the review stage, the merge stage, the wave-merge barrier, and

package/app/userTasks.ts

@@ -52,6 +52,40 @@ export const PR_WAIT_ANSWER_ELEMENT = "wait-answer";
  *  canonical `completeUserTask` door and surfaced in this same Tasks inbox. */
 export const PR_WAIT_MERGE_ANSWER_ELEMENT = "wait-merge-answer";
 
+/** The PR review-loop answer-recording service task (convergence-loop.bpmn) — the `pr.answer-escalation`
+ *  job the token moves to IMMEDIATELY when `wait-answer` completes. Its ACTIVE element instance is the
+ *  positive-evidence marker that an operator's answer is in-flight (recorded but the loop hasn't looped
+ *  yet), so the escalation self-heal must NOT steal the row while it runs (issue #829). */
+export const PR_RECORD_ANSWER_ELEMENT = "record-answer";
+
+/** The PR merge-loop answer-recording service task (merge-loop.bpmn) — the merge-path twin of
+ *  `PR_RECORD_ANSWER_ELEMENT`, reached when `wait-merge-answer` completes (issue #829). */
+export const PR_RECORD_MERGE_ANSWER_ELEMENT = "record-merge-answer";
+
+/** Every `pr.persist-escalation` PRODUCER element across the two PR loops — the service tasks that write
+ *  `status="escalated"` (and INSERT the `open` escalation row) IMMEDIATELY BEFORE the engine creates the
+ *  `wait-answer` / `wait-merge-answer` user task. An ACTIVE instance of any of these is positive evidence
+ *  an escalation is being RAISED right now: the row is already `escalated` but no user task exists yet, so
+ *  neither the open-task probe nor the answer-recorder probe covers it. If such a producer stays ACTIVE
+ *  past the raise-time grace window (e.g. an app restart / lease delay between the DB commit and the job
+ *  completing), the escalated-PR self-heal would otherwise see no parked task and wrongly retire the live
+ *  escalation. So the heal must treat an ACTIVE producer as in-flight too (issue #829). This is the single
+ *  source of truth for that set; `app/persistEscalationElements.test.ts` fails if it drifts from the
+ *  `pr.persist-escalation` tasks actually modelled in the BPMN. */
+export const PR_ESCALATION_PRODUCER_ELEMENTS: readonly string[] = [
+  // convergence-loop.bpmn
+  "persist-escalation",
+  "persist-escalation-noprogress",
+  "persist-escalation-maxrounds",
+  "persist-escalation-blockedcomments",
+  "persist-escalation-scope",
+  "persist-review-stalled",
+  // merge-loop.bpmn
+  "merge-esc-conflict",
+  "merge-esc-attempt",
+  "merge-esc-landed",
+];
+
 /** The ACP permission-prompt escalation (issue #559, ADR 0056) — the Tasks-inbox kind a bridged
  *  `session/request_permission` surfaces under when an escalate-policy agent asks a human to Allow/Deny
  *  a proposed action. Unlike the other escalation elements this is NOT a BPMN user-task element; it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.193.1",
+  "version": "0.193.2",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -83,7 +83,7 @@
     "yaml": "^2.9.0"
   },
   "overrides": {
-    "@nanobpm/engine-wasm": "^0.9.0",
+    "@nanobpm/engine-wasm": "^0.10.0",
     "@semantic-release/npm": "^13.1.5"
   }
 }

package/workers/persist-escalation/worker.ts

@@ -111,20 +111,35 @@ const handler: AppJobHandler<In> = async (job, app) => {
       process_instance_key: job.processInstanceKey != null ? String(job.processInstanceKey) : null,
     });
   }
-  const escalationId = await app.data.table("escalations", "id").insert({
-    pr_key: prKey,
-    round_no: round,
-    kind,
-    question,
-    transcript,
-    worker,
-    status: "open",
-    asked_at: now,
-  });
-  await app.data.table("pull_requests", "pr_key").update(prKey, {
-    status: "escalated",
-    current_round: round,
-    updated_at: now,
+  // Open the escalation row and stamp the PR to `escalated` ATOMICALLY, in ONE transaction (Copilot
+  // review of #829). `pr.persist-escalation` is the SOLE producer of a PR's escalated generation, and the
+  // escalated-PR self-heal (`pollUserTasks` in app/service.ts) fences its repair on a snapshot of the PR
+  // generation (`process_key` + `updated_at`) plus the `open` escalation ids it observes. If the fresh
+  // `open` row were INSERTED before the PR's `updated_at` re-stamp — two separate writes, as this worker
+  // used to do — a heal snapshot landing between them would capture the new escalation while the PR still
+  // matched the OLD generation; its compare-and-swap, still matching the un-bumped `updated_at`, could then
+  // WIN and retire the just-opened escalation to `stale`, orphaning a live user task and dropping the
+  // operator's next answer. Committing the insert and the generation re-stamp together closes that window
+  // categorically: the heal can only ever observe the new escalation AND the bumped `updated_at` atomically,
+  // so its snapshot-fenced CAS misses (the discriminator moved) and never clobbers. The same transaction
+  // also means a crash mid-write rolls back cleanly — never an `open` escalation row with no `escalated` PR.
+  let escalationId: number | bigint = 0;
+  await app.data.open().tx(async (t) => {
+    escalationId = await t.table("escalations", "id").insert({
+      pr_key: prKey,
+      round_no: round,
+      kind,
+      question,
+      transcript,
+      worker,
+      status: "open",
+      asked_at: now,
+    });
+    await t.table("pull_requests", "pr_key").update(prKey, {
+      status: "escalated",
+      current_round: round,
+      updated_at: now,
+    });
   });
 
   return { escalationId: Number(escalationId), escalated: true, question };