@nanobpm/nano-workforce 0.202.0 → 0.203.0

package/test/delivery-graphs-staged-embed.test.ts

@@ -126,6 +126,19 @@ test("#460/#511/#569: Dispatch is the operator's launch — posts the digest to
   assert(!/approvalToken/.test(MOUNT_JS), "staged.mount.js must NOT carry the removed replayable approvalToken");
 });
 
+test("#889: the dispatch confirmation offers an escalation-steward opt-in and posts autoResolveEscalations", () => {
+  // Issue #889 §1 requires the opt-in on EVERY UI start pathway. The delivery-graph dispatch is one:
+  // the inline Dispatch confirmation must carry an "Automatically resolve escalations" checkbox, and
+  // the POST body must include `autoResolveEscalations: true` when the operator checks it (the dispatch
+  // door already accepts it — operations/dispatchDeliveryGraph.ts). Without the control a UI user can
+  // never opt a dispatched graph in.
+  assert(/data-dispatch-autoresolve=/.test(MOUNT_JS), "staged.mount.js must render an escalation-steward opt-in checkbox in the dispatch confirmation");
+  assert(/Automatically resolve escalations/.test(MOUNT_JS), "the opt-in control must be labelled for the operator");
+  // The checkbox state is tracked on the pending confirmation and included in the POST payload.
+  assert(/autoResolveEscalations/.test(MOUNT_JS), "staged.mount.js must thread autoResolveEscalations into the dispatch payload");
+  assert(/pending\.autoResolveEscalations/.test(MOUNT_JS), "the opt-in checkbox state is tracked on the pending dispatch confirmation");
+});
+
 test("#520/#569: Dismiss is the operator's discard — posts the digest to the dismiss door, behind an in-DOM confirm, and launches nothing", () => {
   assertModuleAnchored("dismissUrl", "app/api/actions/delivery-graph/dismiss");
   assert(/data-dismiss=/.test(MOUNT_JS), "staged.mount.js must render a per-row Dismiss affordance carrying the digest");

package/test/derivation-parity/derivation-parity.test.ts

@@ -57,6 +57,7 @@ test("every corpus model is either ported or has a documented blocker", () => {
     "merge-cell",
     "wait-gate",
     "human-escalation",
+    "escalation-steward",
   ];
   assertEquals(
     PORTS.map((p) => p.model),

package/test/derivation-parity/flows.ts

@@ -273,4 +273,16 @@ export const PORTS: readonly PortEntry[] = [
     model: "human-escalation",
     blockedReason: `${MULTI_START_END_BLOCK} (human-escalation: 1 start, 3 ends)`,
   },
+  {
+    model: "escalation-steward",
+    blockedReason:
+      "blocked (agent-task marker + gateway merge): single top-level start/end, but its " +
+      "`senior:escalation-steward` task carries the <zeebe:agentDefinition agentType=\"external\" /> " +
+      "marker issue #745 requires on every prompt-bearing senior:* task (a marker the published " +
+      "@nanobpm/workflow compiler cannot emit — the class-3 block), AND its `any eligible?` " +
+      "exclusive gateway is a two-way split whose `eligible`/`none` out-edges re-converge on the " +
+      "shared `done` end event (an explicit-join topology the structured-only builder cannot emit " +
+      "without inserting its own gateway). Awaits an agent-marker option on task() and an " +
+      "arbitrary-graph / explicit-join builder upstream in @nanobpm/workflow (nano-ide).",
+  },
 ];

package/workers/converge-feature/worker.ts

@@ -47,12 +47,17 @@ const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
     pr_key: parsed.prKey,
     updated_at: new Date().toISOString(),
   });
-  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge, featureKey, humanApproval);
+  // Propagate the feature run's escalation-steward opt-in (issue #889) to the convergence loop:
+  // read the durable flag off the `feature_runs` row (the source of truth) and hand it to `submitPr`.
+  const featureRow = await featureRuns(app.data).get(featureKey);
+  const autoResolve = featureRow?.auto_resolve_escalations === 1;
+  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge, featureKey, humanApproval, autoResolve);
   app.log.info("converge-feature: enrolled PR into convergence loop", {
     featureKey,
     prKey: parsed.prKey,
     convergeOnly: !autoMerge,
     humanApproval,
+    autoResolveEscalations: autoResolve,
   });
   return {};
 };

package/workers/delivery-connector/worker.test.ts

@@ -6,7 +6,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertThrows } from "#test-assert";
 import { PROCESS_ID } from "../../app/service.ts";
 import { withTrackingViews } from "../../test/trackingViews.ts";
-import handler, { readConnectorInput, readConvergeInput, safeStringify } from "./worker.ts";
+import handler, { readConnectorInput, readConvergeInput, safeStringify, setLaunchStampSleep } from "./worker.ts";
 
 function memTable(rows: Record<string, unknown>[], key: string) {
   return {
@@ -41,6 +41,7 @@ function fakeApp() {
     escalations: { rows: [], key: "id" },
     pr_dependencies: { rows: [], key: "pr_key" },
     delivery_connector_dispatches: { rows: [], key: "id" },
+    delivery_graph_runs: { rows: [], key: "run_key" },
   };
   const created: { processDefinitionId?: string; variables?: Record<string, unknown> }[] = [];
   let nextId = 1;
@@ -317,3 +318,73 @@ test("handler: a misconfigured converge connector (no parseable pr) fails CLOSED
     assertEquals(stores.delivery_connector_dispatches.rows.length, 0, "no junk ledger row is claimed");
   });
 });
+
+test("handler: the escalation-steward opt-in is resolved from the DURABLE delivery_graph_runs row, NOT the clobberable process variable (issue #889 review)", async () => {
+  await withGithubOff(async () => {
+    const { app, stores, created } = fakeApp();
+    // The run row for THIS process instance OPTED IN (auto_resolve_escalations = 1), keyed by
+    // `process_key` = the connector job's processInstanceKey.
+    stores.delivery_graph_runs.rows.push({ run_key: "run-1", process_key: "PI-graph", auto_resolve_escalations: 1, status: "running" });
+    // ...but an upstream agent completion CLOBBERED the inherited process variable to `false`. Before
+    // the fix the connector read `job.variables.autoResolveEscalations === true` → false, enrolling the
+    // PR as opted-OUT and contradicting the durable record. The durable row must win.
+    await handler(
+      { variables: { target: "converge-merge", payload: { pr: "owner/repo#21" }, autoResolveEscalations: false }, processInstanceKey: "PI-graph", elementId: "n2" } as never,
+      app,
+    );
+    assertEquals(created.length, 1, "the PR was enrolled");
+    assertEquals(created[0]?.variables?.autoResolveEscalations, true, "the durable run row's opt-in wins over the clobbered process variable");
+  });
+});
+
+test("handler: the escalation-steward opt-in FAILS CLOSED when no delivery_graph_runs row matches this process instance", async () => {
+  await withGithubOff(async () => {
+    const { app, created } = fakeApp();
+    // No delivery_graph_runs row for PI-graph (and the process variable claims opted-IN). With no
+    // durable record the connector must NOT trust the clobberable variable — fail closed to opted-OUT.
+    await handler(
+      { variables: { target: "converge-merge", payload: { pr: "owner/repo#22" }, autoResolveEscalations: true }, processInstanceKey: "PI-graph", elementId: "n2" } as never,
+      app,
+    );
+    assertEquals(created.length, 1, "the PR was still enrolled");
+    assertEquals(created[0]?.variables?.autoResolveEscalations, false, "no durable run row ⇒ fail closed to opted-out, never trust the process variable");
+  });
+});
+
+test("handler: a launch-in-flight run row (process_key not yet stamped) is retried, NOT converted to opted-out (issue #889 review — launch race)", async () => {
+  await withGithubOff(async () => {
+    const { app, stores, created } = fakeApp();
+    // THE LAUNCH RACE: `dispatchDeliveryGraphRun` claims the run row with `process_key = NULL`, starts
+    // the engine instance, and only THEN stamps the returned key. This connector job activated BEFORE
+    // that post-launch write, so the row is present (opted IN) but its `process_key` is still NULL. A
+    // single read keyed on `process_key` finds NO match → false → permanently enrolls the opted-in PR
+    // as opted OUT. The lookup must treat a NULL process_key as TRANSIENT and re-poll until the stamp
+    // lands. DETERMINISTIC (AGENTS.md — no real-timer race): the inter-poll sleep is overridden to a
+    // test-controlled signal that stamps `process_key` after a fixed number of polls (poll 1 and 2 see
+    // the launch-in-flight NULL, poll 3 sees the stamp) — no wall-clock timer, so the outcome cannot
+    // depend on scheduler load.
+    const row: Record<string, unknown> = { run_key: "run-1", process_key: null, auto_resolve_escalations: 1, status: "running" };
+    stores.delivery_graph_runs.rows.push(row);
+    let polls = 0;
+    setLaunchStampSleep(() => {
+      polls += 1;
+      if (polls === 2) row.process_key = "PI-graph"; // the dispatch's stamp lands after the 2nd poll
+      return Promise.resolve();
+    });
+    try {
+      await handler(
+        { variables: { target: "converge-merge", payload: { pr: "owner/repo#23" } }, processInstanceKey: "PI-graph", elementId: "n2" } as never,
+        app,
+      );
+    } finally {
+      setLaunchStampSleep();
+    }
+    assert(polls >= 2, "the launch-in-flight row was re-polled across the launch window, not read once and converted to opted-out");
+    assertEquals(created.length, 1, "the PR was enrolled");
+    assertEquals(
+      created[0]?.variables?.autoResolveEscalations,
+      true,
+      "a launch-in-flight run row is retried until its process_key stamp lands — never read as opted-out",
+    );
+  });
+});

package/workers/delivery-connector/worker.ts

@@ -7,7 +7,7 @@
 // envelope) so it is unit-testable without the engine and shares ONE implementation with any other
 // caller; this worker is the thin engine adapter that resolves the effective dedupe key from the job's
 // author-supplied `dedupeKey` or its stable engine identity (`processInstanceKey:elementId`).
-import type { AppJobHandler } from "@nanobpm/urban";
+import type { AppJobHandler, DataLayer } from "@nanobpm/urban";
 import {
   type BoundFact,
   type ConnectorDispatchResult,
@@ -17,6 +17,7 @@ import {
   isConvergeTarget,
   resolveConvergePr,
 } from "../../app/deliveryConnector.ts";
+import { deliveryGraphRuns } from "../../app/deliveryGraphRun.ts";
 import { isPrSettled, MAX_ROUNDS, type ParsedPr, parsePr, submitPr } from "../../app/service.ts";
 
 // Typed off the compiled `connector` subProcess ioMapping (a RUNTIME-generated definition, so there is
@@ -34,6 +35,49 @@ function isPlainObject(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
+/** Resolve the escalation-steward opt-in for THIS delivery run from the DURABLE
+ *  `delivery_graph_runs.auto_resolve_escalations` flag (keyed by the run's `process_key`), NOT the
+ *  inherited `autoResolveEscalations` process variable (issue #889 review). The process variable is
+ *  clobberable: an upstream agent node that completes with `autoResolveEscalations: false` in its
+ *  output overwrites the run-root variable downstream, so reading it here would enroll the PR with the
+ *  WRONG opt-in — contradicting the durable-source guarantee the steward's eligibility relies on. The
+ *  run row is the record of truth. FAIL CLOSED: no matching run row (or a non-1 flag) ⇒ not opted in.
+ *
+ *  LAUNCH RACE (issue #889 review): `dispatchDeliveryGraphRun` claims the run row with
+ *  `process_key = NULL`, starts the engine instance, and only THEN stamps the returned key
+ *  (`app/deliveryGraphDispatch.ts`). This connector job can activate BEFORE that post-launch write, so
+ *  a single read keyed on `process_key` finds NO match and would convert the launch-in-flight row to a
+ *  permanent opted-OUT enrollment. A NULL `process_key` is TRANSIENT (launch in flight), not proof of
+ *  "no run" — so re-poll across the launch window until the stamp lands (or the budget runs out, after
+ *  which we fail closed as before). */
+const LAUNCH_STAMP_POLLS = 20;
+const LAUNCH_STAMP_POLL_MS = 250;
+/** The scheduler the poll loop sleeps on between launch-stamp reads. Overridable in tests via
+ * {@link setLaunchStampSleep} so a regression drives the retry by a deterministic READ COUNT (the fake
+ * table stamps `process_key` after N polls) rather than racing real wall-clock timers — AGENTS.md
+ * forbids a test whose outcome depends on scheduler load. */
+let launchStampSleep: (ms: number) => Promise<void> = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Test-only seam: override the inter-poll sleep. Pass no argument to restore the real timer. */
+export function setLaunchStampSleep(sleep?: (ms: number) => Promise<void>): void {
+  launchStampSleep = sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+}
+async function resolveAutoResolveEscalations(data: DataLayer, processInstanceKey: string | null): Promise<boolean> {
+  if (!processInstanceKey) return false;
+  const runs = deliveryGraphRuns(data);
+  for (let attempt = 0; attempt < LAUNCH_STAMP_POLLS; attempt++) {
+    const rows = await runs.all();
+    const run = rows.find((r) => r.process_key != null && String(r.process_key) === String(processInstanceKey));
+    if (run != null) return run.auto_resolve_escalations === 1;
+    // No row carries this process_key yet. If a launch-in-flight row (NULL process_key) is still
+    // waiting for its stamp, re-poll; otherwise there is genuinely no run for this instance — fail
+    // closed without burning the remaining budget.
+    const launchInFlight = rows.some((r) => r.process_key == null && r.status === "running");
+    if (!launchInFlight) return false;
+    if (attempt < LAUNCH_STAMP_POLLS - 1) await launchStampSleep(LAUNCH_STAMP_POLL_MS);
+  }
+  return false;
+}
+
 /** Validate + normalise the untyped job variables into the shape the connector surface accepts. Job
  * variables are untyped at runtime, so a misconfigured node (or a hand-seeded instance) could hand us a
  * blank `target`, a scalar `payload`, or a non-array `boundFacts`. Fail CLOSED on a blank `target` (a
@@ -167,12 +211,19 @@ const handler: AppJobHandler<In, ConnectorDispatchResult> = async (job, app) =>
             });
             return { detail: `${converge.parsed.prKey} already terminal — enrollment skipped (at-most-once resume-safe)` };
           }
-          await submitPr(app.data, app.engine, converge.parsed, converge.dependsOn, MAX_ROUNDS, converge.convergeOnly, dedupeKey);
+          // Propagate the delivery run's escalation-steward opt-in (issue #889) to the enrolled PR.
+          // Resolve it from the DURABLE `delivery_graph_runs` row (keyed by this job's process
+          // instance), NOT the inherited `autoResolveEscalations` process variable — an upstream agent
+          // completion can clobber that variable, so the durable row is the only trustworthy source
+          // (issue #889 review). Fails closed (false) when no run row matches.
+          const autoResolve = await resolveAutoResolveEscalations(app.data, job.processInstanceKey != null ? String(job.processInstanceKey) : null);
+          await submitPr(app.data, app.engine, converge.parsed, converge.dependsOn, MAX_ROUNDS, converge.convergeOnly, dedupeKey, false, autoResolve);
           app.log.info("delivery-connector: enrolled PR into convergence loop", {
             target,
             dedupeKey,
             prKey: converge.parsed.prKey,
             convergeOnly: converge.convergeOnly,
+            autoResolveEscalations: autoResolve,
           });
           return { detail: `enrolled ${converge.parsed.prKey} into convergence loop (convergeOnly=${converge.convergeOnly})` };
         }

package/workers/escalation-steward-collect/worker.test.ts

@@ -0,0 +1,180 @@
+// Unit coverage for the pr.escalation-steward-collect worker (issue #889) — the steward tick's first
+// step. Drives the handler against the real data layer + a searchProcessInstances stub and asserts:
+//   • only OPTED-IN, past-min-age, answerable, unclaimed escalations are collected + claimed;
+//   • an escalation on non-opted-in work is NEVER collected (the core safety invariant);
+//   • the overlap guard: a still-ACTIVE prior steward instance makes the tick a no-op.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import { escalationAutoResolutions } from "../../app/escalationSteward.ts";
+import handler from "./worker.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..", "..");
+
+async function withApp(
+  fn: (data: DataLayer, run: (vars?: Record<string, unknown>, activeSteward?: string[]) => Promise<{ eligibleCount: number; claimed: string[]; skippedOverlap: boolean }>) => Promise<void>,
+): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-steward-col-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    const run = async (vars: Record<string, unknown> = {}, activeSteward: string[] = []) => {
+      const engine = {
+        searchProcessInstances: (filter?: { processDefinitionId?: string; state?: string }) => {
+          // Report the listed keys as ACTIVE steward instances (the overlap probe).
+          const list = filter?.processDefinitionId === "escalation-steward"
+            ? activeSteward.map((k) => ({ processInstanceKey: k, state: "ACTIVE" }))
+            : [];
+          return Promise.resolve(list);
+        },
+      };
+      const job = { jobKey: "J-1", processInstanceKey: "PI-THIS", variables: vars };
+      return (await handler(job as never, { data: app.db, engine: engine as never, log: { info: () => {}, warn: () => {}, error: () => {} } } as never)) as {
+        eligibleCount: number;
+        claimed: string[];
+        skippedOverlap: boolean;
+      };
+    };
+    await fn(app.db, run);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Seed an open user_tasks row + its owning subject (with the given opt-in flag). */
+async function seedEscalation(
+  data: DataLayer,
+  opts: { userTaskKey: string; processKey: string; optedIn: boolean; elementId?: string; ageMinutes?: number; subjectKey?: string; formKey?: string },
+): Promise<void> {
+  const ts = new Date().toISOString();
+  const created = new Date(Date.now() - (opts.ageMinutes ?? 10) * 60 * 1000).toISOString();
+  await data.table("pull_requests", "pr_key").insert({
+    pr_key: opts.subjectKey ?? "o/r#1", repo: "o/r", number: 1, url: "u", status: "converging", current_round: 0,
+    process_key: opts.processKey, auto_resolve_escalations: opts.optedIn ? 1 : 0, created_at: ts, updated_at: ts,
+  });
+  await data.table("user_tasks", "user_task_key").insert({
+    user_task_key: opts.userTaskKey, element_id: opts.elementId ?? "wait-answer", kind_label: "PR review",
+    subject_type: "pr", subject_key: opts.subjectKey ?? "o/r#1", subject_title: "t", subject_url: "u",
+    question: "q", process_key: opts.processKey, form_key: opts.formKey ?? "pr-escalation", created_at: created, updated_at: ts,
+  });
+}
+
+test("collect worker: collects + claims an opted-in, past-min-age, answerable escalation", async () => {
+  await withApp(async (data, run) => {
+    await seedEscalation(data, { userTaskKey: "UT-1", processKey: "PI-PR", optedIn: true });
+    const out = await run();
+    assertEquals(out.skippedOverlap, false);
+    assertEquals(out.eligibleCount, 1);
+    assertEquals(out.claimed.length, 1);
+    // The claim is recorded (a `claimed` placeholder row) so a racing tick is fenced out.
+    const rows = await escalationAutoResolutions(data).find({ user_task_key: "UT-1" });
+    assertEquals(rows.length, 1);
+    assertEquals(rows[0].outcome, "claimed");
+  });
+});
+
+test("collect worker: an escalation on NON-opted-in work is never collected (safety invariant)", async () => {
+  await withApp(async (data, run) => {
+    await seedEscalation(data, { userTaskKey: "UT-1", processKey: "PI-PR", optedIn: false });
+    const out = await run();
+    assertEquals(out.eligibleCount, 0, "non-opted-in work is never touched");
+    assertEquals(out.claimed.length, 0);
+    const rows = await escalationAutoResolutions(data).all();
+    assertEquals(rows.length, 0, "no claim row is written");
+  });
+});
+
+test("collect worker: a human-only kind (merge-approval) is never collected even when opted in", async () => {
+  await withApp(async (data, run) => {
+    await seedEscalation(data, { userTaskKey: "UT-1", processKey: "PI-PR", optedIn: true, elementId: "merge-approval" });
+    const out = await run();
+    assertEquals(out.eligibleCount, 0, "a human-only kind is never steward-collected");
+  });
+});
+
+test("collect worker: a delivery-human CREDENTIAL/manual task is never collected even when opted in", async () => {
+  // A dynamic delivery-human task whose resolved form is the manual OTP/OIDC credential publish form
+  // must fail closed — the agent completer does NOT validate dynamic delivery-human forms, so a
+  // mis-prompted steward could otherwise blind-complete a credential task (issue #889 review).
+  for (const formKey of ["delivery-human-publish", "delivery-human-ack", "no-such-form"]) {
+    await withApp(async (data, run) => {
+      await seedEscalation(data, { userTaskKey: "UT-DG", processKey: "PI-PR", optedIn: true, elementId: "delivery-human-task__publish", formKey });
+      const out = await run();
+      assertEquals(out.eligibleCount, 0, `delivery-human + ${formKey} is never steward-collected`);
+      assertEquals((await escalationAutoResolutions(data).all()).length, 0, "no claim row is written");
+    });
+  }
+});
+
+test("collect worker: a delivery-human task on a steward-safe form IS collected when opted in", async () => {
+  await withApp(async (data, run) => {
+    await seedEscalation(data, { userTaskKey: "UT-DG", processKey: "PI-PR", optedIn: true, elementId: "delivery-human-task__step", formKey: "delivery-human-generic" });
+    const out = await run();
+    assertEquals(out.eligibleCount, 1, "delivery-human + generic (typed-value) form is steward-answerable");
+  });
+});
+
+test("collect worker: a too-fresh escalation (under min age) is left for a human already answering", async () => {
+  await withApp(async (data, run) => {
+    await seedEscalation(data, { userTaskKey: "UT-1", processKey: "PI-PR", optedIn: true, ageMinutes: 0 });
+    const out = await run({ minAgeMs: 300_000 });
+    assertEquals(out.eligibleCount, 0, "a just-opened escalation is not yet eligible");
+  });
+});
+
+test("collect worker: an explicit process-key opt-OUT is trusted, never overridden by a colliding opted-in subject key in another table", async () => {
+  await withApp(async (data, run) => {
+    // The PR's OWN run opted OUT (auto_resolve=0). Its escalation parks with process_key=PI-PR,
+    // subject_type="pr", subject_key="o/r#1".
+    await seedEscalation(data, { userTaskKey: "UT-1", processKey: "PI-PR", optedIn: false });
+    // A DIFFERENT subject table has a row whose run_key COLLIDES with the PR's subject_key but opted IN.
+    const ts = new Date().toISOString();
+    await data.table("delivery_graph_runs", "run_key").insert({
+      run_key: "o/r#1", process_key: "PI-DELIVERY", digest: "d", status: "running",
+      auto_resolve_escalations: 1, created_at: ts, updated_at: ts,
+    });
+    const out = await run();
+    // Old bug: the un-scoped subject fallback matched the colliding delivery row (opted in) and OR-ed
+    // PAST the PR's explicit opt-OUT, collecting a task the PR owner opted OUT of. Fix: a direct opt-OUT
+    // is trusted (only an ABSENT direct lookup falls back) AND the fallback is compound-keyed by
+    // subject_type, so a cross-table key collision can never make a non-opted-in task eligible.
+    assertEquals(out.eligibleCount, 0, "an explicit opt-OUT is never overridden by a colliding opted-in subject key");
+    assertEquals(out.claimed.length, 0);
+    const rows = await escalationAutoResolutions(data).all();
+    assertEquals(rows.length, 0, "no claim row is written for an opted-out subject");
+  });
+});
+
+test("collect worker: the overlap guard makes a tick a no-op while a prior steward run is ACTIVE", async () => {
+  await withApp(async (data, run) => {
+    await seedEscalation(data, { userTaskKey: "UT-1", processKey: "PI-PR", optedIn: true });
+    const out = await run({}, ["PI-PRIOR"]);
+    assertEquals(out.skippedOverlap, true, "a still-active prior run skips this tick");
+    assertEquals(out.eligibleCount, 0);
+    assertEquals(out.claimed.length, 0);
+  });
+});
+
+test("collect worker: an escalation the steward ALREADY abstained/resolved is never re-claimed (no repeated abstentions)", async () => {
+  await withApp(async (data, run) => {
+    const { recordResolution } = await import("../../app/escalationSteward.ts");
+    await seedEscalation(data, { userTaskKey: "UT-1", processKey: "PI-PR", optedIn: true });
+    // First tick claims + abstains (the task stays OPEN — an abstention does not complete it).
+    const first = await run({});
+    assertEquals(first.claimed.length, 1, "the first tick claims the eligible escalation");
+    await recordResolution(data, "UT-1", { outcome: "abstained", rationale: "unclear — needs a human" });
+    // The NEXT tick must NOT re-claim the same `user_task_key`: the partial claim fence no longer
+    // covers the finalised row, so without the final-record exclusion the steward would abstain the
+    // same open task every tick forever (issue #889 review).
+    const second = await run({});
+    assertEquals(second.claimed.length, 0, "an already-abstained task is never re-claimed");
+    assertEquals(second.eligibleCount, 0);
+    const rows = await escalationAutoResolutions(data).find({ user_task_key: "UT-1" });
+    assertEquals(rows.length, 1, "exactly ONE durable row — no repeated abstention records");
+    assertEquals(rows[0].outcome, "abstained");
+  });
+});

package/workers/escalation-steward-collect/worker.ts

@@ -0,0 +1,99 @@
+// pr.escalation-steward-collect — the steward tick's first step (issue #889). Collects the OPEN
+// escalation user tasks that are ELIGIBLE for auto-resolution and claims them for THIS steward run,
+// so the agent dispatched next has a bounded, non-overlapping work set.
+//
+// Eligibility (app/escalationSteward.ts, the ONE derivation):
+//   • the escalation's owning work OPTED IN (`auto_resolve_escalations` on its subject row, resolved
+//     via the task's process/root instance key);
+//   • the kind is steward-answerable (never a human-only / irreversible / credential kind);
+//   • the task is past the minimum age (a human already answering wins);
+//   • it is not already claimed by a live steward run (the claim/lease fence).
+//
+// Overlap guard: if the PREVIOUS steward instance is still ACTIVE, this tick claims nothing and
+// reports `skippedOverlap` — the process's gateway then routes straight to done (a no-op tick), so
+// two steward runs never double-answer.
+import type { AppJobHandler } from "@nanobpm/urban";
+import {
+  claimEscalations,
+  DEFAULT_MIN_AGE_MS,
+  ESCALATION_STEWARD_PROCESS_ID,
+  finalRecordedTaskKeys,
+  isEligibleEscalation,
+  liveClaimedTaskKeys,
+  optInByProcessKey,
+  optInBySubjectKey,
+} from "../../app/escalationSteward.ts";
+import { type UserTaskRow, userTasks } from "../../app/userTasks.ts";
+
+interface In extends Record<string, unknown> {
+  stewardInstanceKey?: string;
+  minAgeMs?: number;
+}
+
+interface Out extends Record<string, unknown> {
+  eligibleCount: number;
+  /** The claimed escalations, serialised for the agent's `claimedTasks` input (JSON). */
+  claimed: string[];
+  skippedOverlap: boolean;
+}
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const stewardKey = job.processInstanceKey != null ? String(job.processInstanceKey) : `steward-${Date.now()}`;
+  const minAgeMs = typeof job.variables.minAgeMs === "number" && job.variables.minAgeMs >= 0 ? job.variables.minAgeMs : DEFAULT_MIN_AGE_MS;
+
+  // Overlap guard: a still-active prior steward instance means this tick is a no-op.
+  const active = await app.engine.searchProcessInstances({ processDefinitionId: ESCALATION_STEWARD_PROCESS_ID, state: "ACTIVE" });
+  const prior = active.filter((i) => String(i.processInstanceKey) !== stewardKey);
+  if (prior.length > 0) {
+    app.log.info("escalation-steward collect: prior run still active — no-op tick", { active: prior.length });
+    return { eligibleCount: 0, claimed: [], skippedOverlap: true };
+  }
+
+  const open = await userTasks(app.data).all();
+  const optInByProc = await optInByProcessKey(app.data);
+  const optInBySubject = await optInBySubjectKey(app.data);
+  // The claim fence's partial UNIQUE index only fences an OPEN claim; once a row is finalised
+  // (`resolved`/`abstained`) it leaves that index, and because an abstention does NOT complete the
+  // task, the same `user_task_key` would be re-claimed every tick (issue #889 review). Union the
+  // already-final keys into the exclusion set so a task the steward already answered/abstained is
+  // never re-claimed (a genuinely NEW escalation gets a NEW engine key, so this never blocks one).
+  const claimedKeys = await liveClaimedTaskKeys(app.data);
+  for (const k of await finalRecordedTaskKeys(app.data)) claimedKeys.add(k);
+  const at = Date.now();
+
+  // Resolve each task's opt-in from its owning subject. A top-level escalation's `process_key` IS the
+  // subject's instance; an escalation parked INSIDE a callActivity child cell (the shared
+  // `human-escalation`/`implement-cell`) instead carries the CHILD's `process_key` (no subject row
+  // tracks it) but the PARENT run's `subject_key` (pollUserTasks correlates it via the root instance).
+  // So check the direct `process_key` first; only when that lookup is ABSENT (no subject row keyed on
+  // this process instance at all) fall back to the correlated `<subject_type>:<subject_key>`. A direct
+  // lookup that returned `false` is an explicit opt-OUT and MUST be trusted — never OR-ed past with a
+  // subject-key fallback that could flip it back to eligible (issue #889 review). The subject fallback
+  // is COMPOUND-keyed by `subject_type` so a `plan_key`/`pr_key`/`run_key` colliding across tables
+  // can't cross-match. A task with no tracked subject either way is NOT opted in (fail-closed).
+  const eligible: UserTaskRow[] = [];
+  for (const row of open) {
+    const procKey = row.process_key ?? "";
+    const directOptIn = procKey !== "" ? optInByProc.get(procKey) : undefined;
+    const optedIn =
+      directOptIn !== undefined
+        ? directOptIn
+        : row.subject_key != null && row.subject_key !== "" &&
+          optInBySubject.get(`${row.subject_type}:${row.subject_key}`) === true;
+    if (isEligibleEscalation(row, { optedIn, minAgeMs, claimedUserTaskKeys: claimedKeys, at })) {
+      eligible.push(row);
+    }
+  }
+
+  const claimed = await claimEscalations(app.data, eligible, stewardKey);
+  app.log.info("escalation-steward collect", { open: open.length, eligible: eligible.length, claimed: claimed.length });
+  // Serialise the claimed rows for the agent (the message/job envelope is scalar-only for lists, so
+  // carry each as a compact JSON string the agent + record step parse).
+  return {
+    eligibleCount: claimed.length,
+    claimed: claimed.map((r) => JSON.stringify(r)),
+    skippedOverlap: false,
+  };
+};
+
+export default handler;