@nanobpm/nano-workforce 0.202.0 → 0.203.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.203.0](https://github.com/nanobpm/nano-workforce/compare/v0.202.0...v0.203.0) (2026-10-13)
+
+### Features
+
+* **escalation-steward:** opt-in auto-resolution of escalations with a reviewable record (Closes [#889](https://github.com/nanobpm/nano-workforce/issues/889)) ([#892](https://github.com/nanobpm/nano-workforce/issues/892)) ([cd1c9eb](https://github.com/nanobpm/nano-workforce/commit/cd1c9eb58bc44b7af0c66d4c1a7bc615920a46d2)), closes [887/#888](https://github.com/887/nano-workforce/issues/888) [#833](https://github.com/nanobpm/nano-workforce/issues/833) [o/r#1](https://github.com/o/r/issues/1) [o/r#1](https://github.com/o/r/issues/1)
+
 ## [0.202.0](https://github.com/nanobpm/nano-workforce/compare/v0.201.5...v0.202.0) (2026-10-12)
 
 ### Features

package/SPEC.md

@@ -1310,6 +1310,54 @@ re-park (a human node has no separate escalation twin to re-park onto). The gate
 like the escalation resume's no-required-target case), and a no-emit acknowledgement node
 has nothing to validate.
 
+## 13.4 Escalation steward (`escalation-steward.bpmn`) — issue #889
+
+An **opt-in**, timer-paced loop that reviews a run's OPEN escalations and submits a recommended
+choice for each, so work keeps moving when no human is watching — while every automatic decision
+stays **reviewable after the fact** in the Auto-resolutions view. It is strictly opt-in: only work
+whose start request set `autoResolveEscalations: true` (persisted as `auto_resolve_escalations` on
+the subject row) is ever touched; everything else is fail-closed out.
+
+- **Pacing + master switch.** `pollEscalationSteward` (a `pollOnce` pass) starts ONE
+  `escalation-steward` instance per interval — `NANO_ESCALATION_STEWARD_INTERVAL` (default `PT30M`,
+  parsed through the canonical `isoDurationToMs`) — when the loop is enabled (`NANO_ESCALATION_STEWARD`,
+  default on) and no prior tick is still ACTIVE. The pass is **best-effort and isolated**: a
+  steward-specific failure is caught and logged so it never starves the poller's other liveness
+  passes, and the tick timestamp advances only after a successful start (a failed start retries next
+  pass).
+- **Eligibility + the claim fence.** The collect step (`pr.escalation-steward-collect`) gathers the
+  open escalation user tasks whose owning subject OPTED IN — resolved off the subject row by
+  `process_key`, falling back to the root-correlated `subject_key` so an escalation parked inside a
+  callActivity child cell (`human-escalation`/`implement-cell`) inherits its parent run's opt-in —
+  that are past a short minimum age (`NANO_ESCALATION_STEWARD_MIN_AGE_MS`, default 5 min, so a human
+  already answering wins), of a steward-answerable kind, and not already claimed. It claims them with
+  a durable compare-and-swap lease (`escalation_auto_resolutions` `claimed` placeholder + a partial
+  UNIQUE index), so two overlapping ticks (or a tick racing a human) never double-answer; an expired
+  lease is released so a crashed steward never wedges a task.
+- **The agent + the record.** The `senior:escalation-steward` agent reviews the claimed escalations
+  and returns one decision each (`resolved` + typed form `variables`, or `abstained`). The record
+  step (`pr.escalation-steward-record`) submits each resolution through the ONE canonical attributed
+  door (`completeEscalationAsAgent`, AGENT attribution — never a human decision, ADR 0046) and writes
+  exactly one durable `escalation_auto_resolutions` row per acted escalation.
+- **Fail-closed guards (defence-in-depth under the prompt's own abstain rules).** Before any
+  submission the record step enforces, in one place: the **claim/ownership fence** (this run must
+  hold a live claim for the key — a hallucinated or foreign key is **skipped**, leaving any other
+  run's claim untouched, *not* recorded `abstained`: `recordResolution` finalises the claim row keyed
+  only by `user_task_key`, so writing even an `abstained` row for a key this run does not own would
+  finalise another run's live claim); the **destructive-option guard**
+  (`abandon`/`force-merge`/credential, derived from the decision's own selected value scoped to the
+  task's ACTUAL form — abstained, never submitted; a foreign safe key can never shadow a destructive
+  own-form key, and a decision carrying conflicting selection fields is abstained as ambiguous); the
+  **loop guard** (a subject auto-resolved `LOOP_GUARD_MAX_RESOLUTIONS` times
+  that escalates again is abstained); and the **malformed-decision guards** (a non-object entry is
+  skipped; a `resolved` decision with no valid `variables` object is recorded `abstained`, never a
+  false `resolved`). Human-only / irreversible kinds (`merge-approval`, `acp-permission`,
+  readiness gates, `feature-blocked`, `conformance-`/`empty-plan-`escalation) are refused before the
+  agent is even dispatched.
+- **The reviewable record.** Every final decision (`resolved`/`abstained`) is listed in
+  Auto-resolutions, attributed to the steward agent, where an operator can **Dismiss** (reviewed, no
+  action) or **Intervene** (stepped in) with a note — a record is never a hidden machine decision.
+
 ## 14. Open questions / future
 
 - **Provisioning the existing PR branch** — resolved: the `c8ctl` host-git

package/app/admittedStaging.test.ts

@@ -23,9 +23,20 @@ function memData() {
           find: (q: any) =>
             Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
           insert: (r: any) => {
+            // Enforce the PRIMARY KEY (plan_key) uniqueness the real SQLite table has, so the
+            // concurrent-insert race path (a colliding second insert throws) is exercisable.
+            if (rows.some((x) => x[key] === r[key])) {
+              return Promise.reject(new Error(`UNIQUE constraint failed: ${name}.${key}`));
+            }
             rows.push(r);
             return Promise.resolve(r);
           },
+          update: (k: any, patch: any) => {
+            const i = rows.findIndex((r) => r[key] === k);
+            if (i === -1) return Promise.resolve({ changed: 0 });
+            rows[i] = { ...rows[i], ...patch };
+            return Promise.resolve({ changed: 1 });
+          },
         };
       },
     } as any,
@@ -59,6 +70,66 @@ test("recordAdmittedEpic is idempotent on plan_key (no second row, existing wins
   assertEquals(again.base_branch, "epic/a"); // the existing staged row is returned, not overwritten
 });
 
+test("recordAdmittedEpic widens the staged escalation opt-in monotonically on an idempotent retry", async () => {
+  const { data, tables } = memData();
+  // Stage the epic OPTED OUT (the caller omitted the flag → 0), as a crashed-before-lowering request
+  // would leave it.
+  const first = await recordAdmittedEpic(data, EPIC);
+  assertEquals(first.auto_resolve_escalations, 0, "an omitted opt-in stages as 0 (opted out)");
+  // Retry the SAME admission now opting in: the staged row must WIDEN to opted-in (issue #889 review),
+  // not stay opted out — otherwise the epic starts opted out despite the caller's opt-in.
+  const retried = await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 1 });
+  assertEquals(tables.get("admitted_epics")!.length, 1, "still one staged row (idempotent)");
+  assertEquals(retried.auto_resolve_escalations, 1, "the retry widened the staged opt-in to 1");
+  assertEquals(retried.created_at, first.created_at, "the original staged row is preserved");
+  assertEquals(tables.get("admitted_epics")![0].auto_resolve_escalations, 1, "the widening is persisted");
+});
+
+test("recordAdmittedEpic never narrows an opted-in staged row back to opted-out", async () => {
+  const { data, tables } = memData();
+  await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 1 });
+  // A retry that omits (or explicitly clears) the flag must NOT narrow the staged opt-in back to 0 —
+  // the flag is monotonic (mirrors submitPr's live-loop adoption, service.ts).
+  const retried = await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 0 });
+  assertEquals(retried.auto_resolve_escalations, 1, "an opted-in staged row is never narrowed to 0");
+  assertEquals(tables.get("admitted_epics")![0].auto_resolve_escalations, 1);
+});
+
+test("recordAdmittedEpic applies the monotonic widening on the concurrent-insert race path", async () => {
+  // Simulate the race the reviewer cited (issue #889): an opted-OUT admission's insert WINS, so by
+  // the time the opted-IN caller runs, the row already exists — but the opted-in caller's initial
+  // `get` raced ahead of that commit and observed NO row, so it proceeds to `insert`, collides on the
+  // PRIMARY KEY, and lands in the catch path. The catch must apply the SAME 0→1 widening before
+  // returning the raced row, or the opt-in is silently lost.
+  const { data, tables } = memData();
+  // The winning racer commits its opted-out row directly (as its own successful insert).
+  await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 0 });
+  assertEquals(tables.get("admitted_epics")![0].auto_resolve_escalations, 0, "the racer staged opted-out");
+
+  // Force the opted-in caller's FIRST `get` to miss (the race window: it read before the racer's
+  // commit became visible); the catch-path re-read then sees the committed row.
+  const realTable = (data as any).table;
+  let missOnce = true;
+  (data as any).table = (name: string, key: string) => {
+    const t = realTable(name, key);
+    if (name !== "admitted_epics") return t;
+    return {
+      ...t,
+      get: (k: any) => (missOnce ? ((missOnce = false), Promise.resolve(null)) : t.get(k)),
+    };
+  };
+
+  // The opted-in caller: get misses → insert collides (mock enforces PK uniqueness) → catch path.
+  const raced = await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 1 });
+  assertEquals(raced.auto_resolve_escalations, 1, "the catch path widens the raced opted-out row to 1");
+  assertEquals(
+    tables.get("admitted_epics")!.find((r) => r.plan_key === EPIC.plan_key)!.auto_resolve_escalations,
+    1,
+    "the widening is persisted on the raced row",
+  );
+  assertEquals(tables.get("admitted_epics")!.length, 1, "still exactly one staged row (no duplicate)");
+});
+
 test("recordAdmittedPlanDep stages an edge and stays out of plan_deps", async () => {
   const { data, tables } = memData();
   await recordAdmittedPlanDep(data, {

package/app/agentActivationLedger.ts

@@ -34,6 +34,11 @@ export const AGENT_SLA_JOB_TYPES: readonly string[] = [
   "senior:retro", // retro synthesize
   "senior:fix-ci", // merge-loop CI-fix cell (be_fixci_sla)
   "senior:rebase", // merge-loop rebase cell (be_rebase_sla)
+  // Tracked for AUDIT PROVENANCE, not an SLA boundary (issue #889 review): the escalation-steward
+  // record step reads this row's `job_key` to persist the ACTUAL answering agent's activation key on
+  // the durable auto-resolution (rather than its own record-task key), so the review surface points at
+  // the job that made the decision.
+  "senior:escalation-steward", // escalation-steward agent (escalation-steward.bpmn)
 ];
 
 /** One ledger row: whether (and when) a worker picked up an agent job for a given process instance. */

package/app/agentCompletion.test.ts

@@ -21,6 +21,8 @@ import {
   escalationFormId,
   latestCompletion,
   revertAgentCompletion,
+  snapshotEscalationFormOptions,
+  snapshotUserTaskFormOptions,
   type TaskCompletion,
   validateEscalationVariables,
 } from "./agentCompletion.ts";
@@ -958,3 +960,34 @@ test("feature-escalation demands non-blank answer on the answer path, but not on
     "the abandon path does not demand the hidden answer field",
   );
 });
+
+test("snapshotUserTaskFormOptions: resolves the engine form_key first (delivery-graph human tasks)", () => {
+  // A delivery-graph human task's element id is dynamic and has NO static escalationFormId mapping, so
+  // the element-only snapshot returns null — but its engine form_key names the real deployed form. The
+  // form_key must win so the options are the REAL choices, not NULL (issue #889 review).
+  assertEquals(snapshotEscalationFormOptions("delivery-human-task__publish"), null, "no static form for a dynamic element id");
+  assertEquals(
+    snapshotUserTaskFormOptions("delivery-escalation", "delivery-human-task__publish"),
+    ["continue", "retry"],
+    "the engine form_key resolves the deployed form's real options",
+  );
+});
+
+test("snapshotUserTaskFormOptions: falls back to the element's static form when form_key is blank", () => {
+  // No engine form_key — fall back to the fixed-form element's static linkage (trial-merge-decision →
+  // [proceed, rebase, abandon]).
+  assertEquals(snapshotUserTaskFormOptions(null, "trial-merge-decision"), ["proceed", "rebase", "abandon"]);
+  assertEquals(snapshotUserTaskFormOptions("   ", "trial-merge-decision"), ["proceed", "rebase", "abandon"], "a blank form_key falls through to the element form");
+});
+
+test("snapshotUserTaskFormOptions: an unresolvable form_key never throws (safe read)", () => {
+  // `formContract` does a readFileSync that THROWS on a missing file — a form_key that names no bundled
+  // form must degrade to the element fallback / null, never throw (a throw in the claim loop wedges the
+  // steward). With neither a resolvable form_key NOR a mappable element, the result is null.
+  assertEquals(snapshotUserTaskFormOptions("no-such-form", "delivery-human-task__x"), null, "unresolvable key + dynamic element → null, no throw");
+  assertEquals(
+    snapshotUserTaskFormOptions("no-such-form", "trial-merge-decision"),
+    ["proceed", "rebase", "abandon"],
+    "an unresolvable form_key falls back to the element's static form",
+  );
+});

package/app/agentCompletion.ts

@@ -296,6 +296,82 @@ export function validateEscalationVariables(
   return null;
 }
 
+/** Snapshot the REAL option values an escalation's deployed `.form` offers (the union of every `select`
+ *  field's allowed `values`), read from the canonical form contract host-side. The escalation-steward
+ *  record step persists THIS — never the deciding agent's self-reported `options` array, which the agent
+ *  may omit or misstate (issue #889 review) — so the reviewable record shows the choices that were
+ *  genuinely on offer. Returns `null` when the element has no linked form (nothing to snapshot). */
+export function snapshotEscalationFormOptions(elementId: string): string[] | null {
+  const formId = escalationFormId(elementId);
+  if (!formId) return null;
+  return optionUnionForForm(formId);
+}
+
+/** The SELECT-field KEYS a fixed-form escalation's deployed `.form` carries (e.g. `["action"]` for
+ *  `trial-merge-decision`, `["directive"]` for `plan-review-decision`), read from the SAME canonical
+ *  form contract the completer validates against — one derivation, no second field list. The
+ *  escalation-steward record step uses this to scope its destructive-option guard to the field the
+ *  task's ACTUAL form submits, so a foreign recognized key (a `resolution` on a `trial-merge-decision`,
+ *  whose own select is `action`) can never shadow the real destructive choice (issue #889 review).
+ *  Returns `null` when the element has no linked form (nothing to scope to — the caller falls back to
+ *  its conservative recognized-key sweep). Never throws on an unreadable form (yields `null`). */
+export function escalationFormSelectKeys(elementId: string): string[] | null {
+  const formId = escalationFormId(elementId);
+  if (!formId) return null;
+  let contract: FormContract;
+  try {
+    contract = formContract(formId);
+  } catch {
+    return null;
+  }
+  return Object.keys(contract.allowed);
+}
+
+/** The union of every `select` field's allowed option values in a deployed `.form`, or `null` when the
+ *  form id is blank/unreadable (a missing or non-`.form` key never throws — see the try/catch). Shared
+ *  by {@link snapshotEscalationFormOptions} (fixed-form escalations, keyed off the element) and
+ *  {@link snapshotUserTaskFormOptions} (keyed off the engine-resolved `form_key`). */
+function optionUnionForForm(formId: string): string[] | null {
+  let contract: FormContract;
+  try {
+    contract = formContract(formId);
+  } catch {
+    // `formContract` does a `readFileSync` and THROWS on a missing/unreadable `.form` — a `form_key`
+    // can be a key that doesn't name a bundled form. Treat that as "nothing to snapshot", never a throw
+    // that would incident the record tick.
+    return null;
+  }
+  const out: string[] = [];
+  for (const values of Object.values(contract.allowed)) {
+    for (const v of values) if (!out.includes(v)) out.push(v);
+  }
+  return out;
+}
+
+/** Snapshot the REAL option values a parked user task's deployed form offers, resolving the form from
+ *  the engine-reported `formKey` FIRST and falling back to the element's static form linkage — the SAME
+ *  precedence the Tasks grid denormalises with (`app/service.ts`), so there is one derivation. This is
+ *  what the escalation-steward record step persists for a DELIVERY-GRAPH human task, whose element id is
+ *  dynamic (`delivery-human-task__<node>`) and so has NO static `escalationFormId` mapping — snapshotting
+ *  off `element_id` alone would record `NULL` options for exactly those tasks (issue #889 review). Reads
+ *  the `formKey` safely (a key that doesn't name a bundled `.form` yields `null`, never a throw).
+ *  Returns `null` when neither source resolves a readable form. */
+export function snapshotUserTaskFormOptions(
+  formKey: string | null | undefined,
+  elementId: string | null | undefined,
+): string[] | null {
+  const engineKey = typeof formKey === "string" ? formKey.trim() : "";
+  if (engineKey) {
+    const fromKey = optionUnionForForm(engineKey);
+    if (fromKey != null) return fromKey;
+  }
+  if (elementId) {
+    const formId = escalationFormId(elementId);
+    if (formId) return optionUnionForForm(formId);
+  }
+  return null;
+}
+
 /** The canonical attributed completer. Records an attribution row in `task_completions` and THEN
  *  completes the user task with the exact typed `variables` — so the ledger row can never be lost by a
  *  resume that fires before the write. If the engine completion throws (a failed/rejected completion,
@@ -401,6 +477,30 @@ export async function latestCompletion(
   return newest;
 }
 
+/** The newest NON-reverted completion an AGENT recorded for a user-task key under a specific
+ *  `agentId`, or undefined. The escalation-steward record step uses this to make its
+ *  completion→record pair idempotent across a service-job retry (issue #889 review): the engine
+ *  completion lands first, then the record worker finalises the claim row — if that finalise fails
+ *  transiently, the retry finds the user task already COMPLETED (the attributed door reports "no open
+ *  completable task") and must NOT degrade the already-applied decision to a false `abstained`.
+ *  Detecting the prior agent-attributed row lets the retry recover the original submitted variables
+ *  and finalise the SAME decision instead. Reverted rows are excluded: a human overrode that
+ *  completion, so it is not a live applied decision to recover. */
+export async function priorAgentCompletion(
+  data: DataLayer,
+  userTaskKey: string,
+  agentId: string,
+): Promise<TaskCompletion | undefined> {
+  const rows = await taskCompletions(data).find({ user_task_key: userTaskKey });
+  let newest: TaskCompletion | undefined;
+  for (const row of rows) {
+    if (row.actor_kind !== "agent" || row.actor_id !== agentId) continue;
+    if (row.reverted === 1) continue;
+    if (!newest || row.id > newest.id) newest = row;
+  }
+  return newest;
+}
+
 export interface AgentCompleteResult {
   ok: boolean;
   reason?: string;
@@ -460,14 +560,20 @@ function isCompletableElement(elementId: string, allowed: ReadonlySet<string>):
 export async function completeEscalationAsAgent(
   data: DataLayer,
   engine: EngineClient,
-  input: { userTaskKey: string; variables: Record<string, unknown>; agentId: string },
+  input: { userTaskKey: string; variables: Record<string, unknown>; agentId: string; processInstanceKey?: string | null },
 ): Promise<AgentCompleteResult> {
   const userTaskKey = input.userTaskKey.trim();
   if (!userTaskKey) return { ok: false, reason: "userTaskKey is required" };
   const agentId = input.agentId.trim();
   if (!agentId) return { ok: false, reason: "agentId is required" };
 
-  const resolved = await resolveEscalationTask(engine, userTaskKey);
+  // When the caller already knows the task's owning process instance (the escalation-steward record
+  // worker does — it holds the claim row's `process_instance_key`), scope the resolve scan to that ONE
+  // instance instead of an engine-wide `openUserTasks()` per decision. A record tick finalises MANY
+  // claimed tasks in one pass, so an unfiltered global scan each is O(N²) REST load (issue #889 review);
+  // the instance filter makes it O(N) and never changes the outcome (the task lives in exactly that
+  // instance). A bare-key caller (a one-off human/agent door) omits it and keeps the engine-wide scan.
+  const resolved = await resolveEscalationTask(engine, userTaskKey, ESCALATION_TASK_ELEMENTS, input.processInstanceKey ?? undefined);
   if (!resolved.ok) return resolved;
 
   const invalid = validateEscalationVariables(resolved.elementId, input.variables);

package/app/agentic/vocab/agent-sla-boundary.test.ts

@@ -150,7 +150,12 @@ test("externalAgentTasksMissingSlaBoundary rejects a timer with no timeDuration,
 // exactly these processes so a regression on a *bounded* process is caught while the deferred
 // two stay out. merge-loop.bpmn's agent tasks (`fix-ci` / `rebase`) were bounded in an earlier
 // #849 commit, so it belongs here too — every already-bounded process stays regression-guarded.
-const BOUNDED_PROCESSES = ["implement-cell.bpmn", "merge-cell.bpmn", "merge-loop.bpmn", "retro.bpmn"] as const;
+// escalation-steward.bpmn's `steward-agent` was bounded for the #889 review (a hung steward
+// instance otherwise parks ACTIVE forever, suppressing every later tick via the poller's overlap
+// guard and wedging claim recovery); its boundary routes to `done` (the steward has no escalation
+// path of its own — on SLA the tick ends and the 15-min claim TTL frees its claims for the next
+// tick), which satisfies the guard's "routes somewhere" requirement.
+const BOUNDED_PROCESSES = ["implement-cell.bpmn", "merge-cell.bpmn", "merge-loop.bpmn", "retro.bpmn", "escalation-steward.bpmn"] as const;
 
 test("DEFECT-CLASS GUARD: every external agent task in a bounded process carries an interrupting timer SLA boundary", () => {
   let anyAgentTasks = false;

package/app/contracts.ts

@@ -179,6 +179,29 @@ export const ENV_CONTRACTS = {
     semantics: "How long to wait for a review before nudging/escalating (FEEL/ISO-8601 duration).",
     default: "PT30M",
   },
+  NANO_ESCALATION_STEWARD: {
+    category: "env",
+    name: "NANO_ESCALATION_STEWARD",
+    owner: "app/escalationSteward.ts",
+    semantics:
+      "Escalation-steward master switch (issue #889): `off`/`0`/`false`/`no` disables the timer loop entirely; anything else (or unset) leaves it enabled.",
+  },
+  NANO_ESCALATION_STEWARD_INTERVAL: {
+    category: "env",
+    name: "NANO_ESCALATION_STEWARD_INTERVAL",
+    owner: "app/escalationSteward.ts",
+    semantics:
+      "How often the escalation-steward timer fires (FEEL/ISO-8601 duration or `R/PT…` cycle), pacing the steward tick (issue #889).",
+    default: "R/PT30M",
+  },
+  NANO_ESCALATION_STEWARD_MIN_AGE_MS: {
+    category: "env",
+    name: "NANO_ESCALATION_STEWARD_MIN_AGE_MS",
+    owner: "app/escalationSteward.ts",
+    semantics:
+      "Minimum age (ms) an open escalation must reach before the steward considers it, so a human already answering wins (issue #889).",
+    default: "300000",
+  },
   NANO_PR_REVIEW_NUDGE_MINUTES: {
     category: "env",
     name: "NANO_PR_REVIEW_NUDGE_MINUTES",

package/app/deliveryGraphDispatch.ts

@@ -227,6 +227,9 @@ export async function dispatchDeliveryGraphRun(
     title,
     humanLabels: buildHumanLabels(compiled),
     createdAt: existing?.created_at,
+    // Opt-in escalation steward (issue #889): persist the run's opt-in so the steward's eligibility
+    // derivation reads it off the durable row.
+    autoResolveEscalations: options.autoResolveEscalations === true,
   };
 
   // Claim the run durably BEFORE the side effect (the at-most-once dispatch fence). A losing racer
@@ -344,6 +347,9 @@ export async function dispatchDeliveryGraphRun(
       repository: options.repository,
       baseBranch: options.baseBranch,
       repoless: options.repoless,
+      // Opt-in escalation steward (issue #889): seeded as a run-root variable so every node's
+      // escalation inherits it (and the delivery-connector propagates it to any enrolled PR).
+      autoResolveEscalations: options.autoResolveEscalations,
     });
   } catch (err) {
     await markClaimFailed();

package/app/deliveryGraphReadModel.test.ts

@@ -39,7 +39,7 @@ import { applyMigrationSet, readMigrationSetFromDisk } from "../test/migrations.
 const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
 
-const READ_MODEL_MIGRATION = "096_delivery_graph_read_model_list_bucket.sql";
+const READ_MODEL_MIGRATION = "121_delivery_graph_read_model_auto_resolve.sql";
 
 // A minimal in-memory DB carrying the base `delivery_graph_runs` / `pull_requests` shapes the VIEW
 // reads, plus stand-ins for the managed `<table>__tracking` derived VIEWs urban provisions at mount
@@ -53,7 +53,7 @@ function viewDb(): DatabaseSync {
        run_key TEXT PRIMARY KEY, process_key TEXT, process_definition_id TEXT, digest TEXT,
        status TEXT, side_effecting INTEGER, node_count INTEGER, human_node_count INTEGER,
        side_effect_count INTEGER, title TEXT, phase TEXT, phase_node_id TEXT, human_labels TEXT,
-       created_at TEXT, updated_at TEXT, acknowledged_at TEXT, derived_status_override TEXT);
+       created_at TEXT, updated_at TEXT, acknowledged_at TEXT, auto_resolve_escalations INTEGER, derived_status_override TEXT);
      CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, root_request_key TEXT, status TEXT,
        derived_status_override TEXT);`,
   );

package/app/deliveryGraphRun.ts

@@ -28,6 +28,7 @@ import type { CompileDeliveryGraphResult } from "../nano-generated/api-io.d.ts";
 import { isUniqueConstraintFence } from "./dbFence.ts";
 import { redactFreeText } from "./deliveryGraphCompiler.ts";
 import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement, stripDeliveryEscalationTwinSuffix } from "./deliveryHuman.ts";
+import { derivedTrackingTable } from "./instanceTracking.ts";
 
 const now = () => new Date().toISOString();
 
@@ -52,6 +53,9 @@ export interface DeliveryGraphRun {
    *  the `delivery_graph_read_model` VIEW folds its `list_bucket` to 'history'; NULL while the run is
    *  live or terminal-but-undismissed (it stays in Active until an operator ticks it off). */
   acknowledged_at: string | null;
+  /** Opt-in escalation steward (120_escalation_auto_resolutions.sql, issue #889): 1 ⇒ this run's
+   * escalations are eligible for steward auto-resolution. Default 0. */
+  auto_resolve_escalations: number;
 }
 
 /** The run lifecycle. `awaiting-approval` is RESERVED but no longer produced (issue #460 moved dispatch
@@ -98,6 +102,18 @@ export const DELIVERY_PHASE = {
 export const deliveryGraphRuns = (data: DataLayer) =>
   data.table<DeliveryGraphRun>("delivery_graph_runs", "run_key");
 
+/** A `delivery_graph_runs` row as seen through its derived tracking VIEW
+ *  (`delivery_graph_runs__tracking`): the base columns plus urban's ADR-0065 `derived_status`, which
+ *  folds the reconciler's terminal edge (out-of-band terminate → `failed`) over the worker-owned
+ *  transient. */
+export type TrackedDeliveryGraphRun = DeliveryGraphRun & { derived_status: string };
+/** Read-only accessor over the delivery-run derived tracking VIEW. Use this — and read
+ *  `derived_status`, not `status` — for any terminal-edge classification (e.g. the `/status` active
+ *  list), so an out-of-band-terminated run (whose base row is still `running`) is correctly seen as
+ *  `failed`. Mirrors `prsTracking` / `featureRunsTracking`. Writes stay on `deliveryGraphRuns`. */
+export const deliveryGraphRunsTracking = (data: DataLayer) =>
+  derivedTrackingTable<TrackedDeliveryGraphRun>(data, "delivery_graph_runs", "run_key");
+
 /** One row of the `delivery_graph_run_identity` SIDE table (migration 113) — the run's LOSSLESS
  * content-identity fingerprint, kept OFF the heavily-projected `delivery_graph_runs` base row so no
  * drift-guarded read-model/compat view has to carry it. Keyed by `run_key`. */
@@ -493,6 +509,7 @@ export function buildDeliveryGraphRunRow(input: {
   processDefinitionId?: string | null;
   humanLabels?: Record<string, string>;
   createdAt?: string;
+  autoResolveEscalations?: boolean;
 }): DeliveryGraphRun {
   const at = now();
   return {
@@ -509,6 +526,7 @@ export function buildDeliveryGraphRunRow(input: {
     phase: input.phase,
     phase_node_id: null,
     human_labels: input.humanLabels ? JSON.stringify(input.humanLabels) : null,
+    auto_resolve_escalations: input.autoResolveEscalations === true ? 1 : 0,
     created_at: input.createdAt ?? at,
     updated_at: at,
     acknowledged_at: null,

package/app/deliveryRunner.ts

@@ -55,6 +55,10 @@ export interface DeliveryRunTimeouts {
   probePollEvery?: string;
   /** Optional explicit assignee for `human` nodes + escalation tasks (else candidate-group routed). */
   escalationAssignee?: string | null;
+  /** Opt-in escalation steward (issue #889): when true, this run's escalations (human nodes, service
+   * node escalation twins, and any `converge*` connector's enrolled PR) become eligible for steward
+   * auto-resolution. Seeded as a run-root variable and persisted on the `delivery_graph_runs` row. */
+  autoResolveEscalations?: boolean;
 }
 
 export interface DeliveryRunOptions extends DeliveryRunTimeouts {
@@ -96,7 +100,7 @@ export interface DeliveryRunOptions extends DeliveryRunTimeouts {
   repoless?: boolean;
 }
 
-const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
+const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee" | "autoResolveEscalations">> = {
   nodeTimeout: DELIVERY_NODE_DEFAULT_TIMEOUT,
   probeTimeout: "PT30M",
   probePollEvery: msToIsoDuration(DEFAULT_EVERY_MS),
@@ -253,6 +257,10 @@ export async function runDeliveryGraph(
       // bounds a node's whole retry budget; this seeds the shared `agentSlaTimeout` knob so any
       // agent cell modelled with the fleet-wide SLA boundary resolves it too.
       agentSlaTimeout: AGENT_SLA_TIMEOUT,
+      // Opt-in escalation steward (issue #889): seeded as a run-root variable so every node's
+      // escalation (and the delivery-connector's `converge*` enrollment) inherits the opt-in. The
+      // durable record the steward's eligibility reads is the `delivery_graph_runs` row (dispatch).
+      autoResolveEscalations: options.autoResolveEscalations === true,
     },
   });
   // The engine can yield a numeric key; `DeliveryRunHandle.processInstanceKey` is typed `string` and