@nanobpm/nano-workforce 0.202.0 → 0.203.0

package/app/feature.test.ts

@@ -140,6 +140,22 @@ test("startFeature: humanApproval is persisted as 0/1 and seeded onto the instan
   }
 });
 
+test("startFeature: autoResolveEscalations is persisted as 0/1 and seeded onto the instance (issue #889)", async () => {
+  for (const autoResolve of [true, false]) {
+    const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+    let vars: any = null;
+    const engine = {
+      createInstance: (req: any) => {
+        vars = req.variables;
+        return Promise.resolve({ processInstanceKey: "PI-1" });
+      },
+    } as any;
+    await startFeature(memData(stores), engine, PARSED, "main", true, true, null, {}, false, autoResolve);
+    assertEquals(stores.feature_runs.rows[0].auto_resolve_escalations, autoResolve ? 1 : 0);
+    assertEquals(vars.autoResolveEscalations, autoResolve);
+  }
+});
+
 test("startFeature: seeds the single task slice + base-branch brief onto the instance", async () => {
   let captured: any = null;
   const engine = {

package/app/feature.ts

@@ -64,6 +64,9 @@ export interface FeatureRun {
   /** 1 ⇒ a human must approve the converged PR before the merge-loop runs (issue #826). Only
    * meaningful with `auto_merge = 1`; the `startFeature` operation pins it to 0 otherwise. */
   human_approval: number;
+  /** 1 ⇒ this run OPTED IN to the escalation steward (issue #889): its open escalations are eligible
+   * for the steward to auto-resolve (recorded reviewably). Default 0 — escalations stay human-only. */
+  auto_resolve_escalations: number;
   outcome: string | null;
   /** Human rollup detail. Projected by `pollFeatureDelivery` (fix: Feature history stuck at
    * `converging`) and also written by `pr.record-blocked-ack` with the operator's disposition
@@ -357,6 +360,7 @@ export async function startFeature(
   customInstructions: string | null = null,
   readiness: FeatureReadinessOptions = {},
   humanApproval = false,
+  autoResolveEscalations = false,
 ): Promise<StartFeatureResult> {
   // Intake-time readiness gate (issue #295): the probes the run must satisfy before it implements,
   // and the bound its preflight escalation timers fire off. Both are load-bearing together —
@@ -456,6 +460,7 @@ export async function startFeature(
       converge: converge ? 1 : 0,
       auto_merge: autoMerge ? 1 : 0,
       human_approval: humanApproval ? 1 : 0,
+      auto_resolve_escalations: autoResolveEscalations ? 1 : 0,
       outcome: null,
       delivery_label: null,
       // Clear the operator tick-off so a re-dispatched run is NOT silently dropped into History when
@@ -479,6 +484,7 @@ export async function startFeature(
       converge: converge ? 1 : 0,
       auto_merge: autoMerge ? 1 : 0,
       human_approval: humanApproval ? 1 : 0,
+      auto_resolve_escalations: autoResolveEscalations ? 1 : 0,
       outcome: null,
       delivery_label: null,
       created_at: ts,
@@ -516,6 +522,11 @@ export async function startFeature(
       autoMerge,
       // Park the converged PR at a human approval user task before the merge-loop (issue #826).
       humanApproval,
+      // Opt-in escalation steward (issue #889): seeded as an engine-owned process variable so the
+      // run's escalations carry the opt-in, AND persisted on the `feature_runs` row (above) — the
+      // steward's eligibility derivation reads the ROW (the durable source), so an agent-completion
+      // clobber of the variable can never silently opt a run in or out (#887/#888).
+      autoResolveEscalations,
       // A single-issue feature run OWNS its issue (the whole issue is the slice), so the agent may
       // claim it with a "starting work" comment on a first run (resources/prompts/feature.md). Epic slices
       // (plan-fanout) deliberately DO NOT set this — their `issue` is the shared parent epic, which

package/app/featureDelivery.test.ts

@@ -218,6 +218,29 @@ test("pollFeatureDelivery: the re-enroll keeps the run's human approval gate (is
   assertEquals(vars?.humanApproval, true, "a healed enrollment must not silently drop the approval gate");
 });
 
+test("pollFeatureDelivery: the re-enroll propagates the run's escalation-steward opt-in (issue #889 review)", async () => {
+  const { data, stores } = memData();
+  // An OPTED-IN converging run whose PR row is missing — the re-enroll must carry the run's
+  // `auto_resolve_escalations` onto the fresh PR row/instance, not drop it to the `false` default.
+  stores.feature_runs = [
+    { feature_key: "o/r#9", status: "converging", pr_key: "o/r#409", auto_merge: 1, human_approval: 0, auto_resolve_escalations: 1, delivery_label: null },
+  ];
+  stores.pull_requests = [];
+  let vars: Record<string, unknown> | undefined;
+  const engine = {
+    searchProcessInstances: async () => [],
+    createInstance: async (req: { variables?: Record<string, unknown> }) => {
+      vars = req.variables;
+      return { processInstanceKey: "pi-409" };
+    },
+  } as any;
+
+  await pollFeatureDelivery(data, engine);
+
+  assertEquals(vars?.autoResolveEscalations, true, "a healed enrollment must not silently drop the steward opt-in");
+  assertEquals(stores.pull_requests[0]?.auto_resolve_escalations, 1, "the PR row persists the opt-in");
+});
+
 test("pollFeatureDelivery: a converging run whose PR row is PARTIALLY enrolled (present, non-terminal, process_key NULL) is re-enrolled — a create-instance crash after the row insert does not wedge it (PR #809)", async () => {
   const { data, stores } = memData();
   stores.feature_runs = [

package/app/mcpToolSurface.ts

@@ -63,6 +63,9 @@ export const CURATED_MCP_TOOLS: readonly string[] = [
   "listEscalations",
   "getLineage",
   "getPrHistory",
+  // ── Escalation steward (issue #889) ──────────────────────────────────────
+  "listAutoResolutions",
+  "reviewAutoResolution",
   // ── Engine-truth reads (wedge triage) ────────────────────────────────────
   "urban_debug_search_process_instances",
   "urban_debug_search_element_instance_wait_states",
@@ -122,8 +125,21 @@ export const MCP_TOOL_COUNT_BUDGET = 60;
  * `target` description in `openapi.yaml` documents the new accepted handle. Measured 87,559 bytes
  * serialized (87,497 → 87,559 — over the old ceiling's 3-byte headroom). Deliberate, documented
  * growth of a real new accepted input format — not schema fat.
+ *
+ * RAISE PROVENANCE — 88_000 → 89_500 (#889): the opt-in escalation steward adds two read/review
+ * tools — `listAutoResolutions` (the Auto-resolutions read, with the `AutoResolution` record schema)
+ * and `reviewAutoResolution` (dismiss/intervene) — plus the `autoResolveEscalations` opt-in field on
+ * the start bodies. Measured 88,866 bytes serialized (over the old ceiling's 866-byte headroom).
+ * Deliberate, documented growth of a real new reviewable-record surface — not schema fat.
+ *
+ * RAISE PROVENANCE — 89_500 → 91_000 (#889 review): ten `openapi.yaml` descriptions that reference
+ * `(issue #889)` were unquoted plain scalars, so the `#` comment marker silently truncated each at
+ * `(issue` — the projected MCP schemas carried the cut text. Quoting them restores the full,
+ * intended description text (a correctness fix, not new surface). Measured 90,420 bytes serialized
+ * (over the old ceiling's 920-byte headroom). Deliberate, documented growth of restored description
+ * text — not schema fat.
  */
-export const MCP_SURFACE_BYTES_BUDGET = 88_000;
+export const MCP_SURFACE_BYTES_BUDGET = 91_000;
 
 /**
  * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it

package/app/plan.ts

@@ -98,6 +98,9 @@ export interface Plan {
   // admission); the column stays NULLABLE ONLY to grandfather pre-ADR-0003 / in-flight rows that
   // carry NULL — those must remain readable, so do NOT add a NOT NULL migration.
   base_branch: string | null;
+  // Opt-in escalation steward (120_escalation_auto_resolutions.sql, issue #889): 1 ⇒ this epic's
+  // escalations (and its spawned child loops) are eligible for steward auto-resolution. Default 0.
+  auto_resolve_escalations: number;
   // The derived epic delivery signal (029_plan_delivery.sql) was RETIRED as a stored column (epic
   // #412): `delivery` / `delivery_label` are now a DERIVED SQL VIEW (`plan_delivery` /
   // `plan_read_model`, 061), computed from the SAME pure `deriveDelivery`/`TERMINAL_STATUSES`
@@ -356,6 +359,10 @@ export interface AdmittedEpic {
   issue_number: number;
   issue_url: string;
   base_branch: string;
+  /** Escalation-steward opt-in staged at admission (issue #889). Persisted so the lowering
+   * (`lowerAdmittedSet`) can forward it to `startPlan` — without it a batch-admitted epic silently
+   * stayed opted out even when the caller opted in. 0|1 (SQLite boolean); absent on pre-124 rows ⇒ 0. */
+  auto_resolve_escalations: number;
   created_at: string;
 }
 export const admittedEpics = (data: DataLayer) =>
@@ -368,28 +375,55 @@ export const admittedPlanDeps = (data: DataLayer) =>
   data.table<PlanDep>("admitted_plan_deps", "plan_key");
 
 /** The fields an admission caller supplies for one staged admitted epic; `created_at` is stamped
- * here (mirrors {@link PlanDepInput}). */
-export type AdmittedEpicInput = Omit<AdmittedEpic, "created_at">;
+ * here (mirrors {@link PlanDepInput}). The escalation-steward opt-in (issue #889) is OPTIONAL on the
+ * input even though it is required on the persisted {@link AdmittedEpic} row: `recordAdmittedEpic`
+ * defaults an omitted value to `0` (opted out), so the typed API matches that default-off behavior
+ * and a caller that does not care about the steward need not spell it out. */
+export type AdmittedEpicInput = Omit<AdmittedEpic, "created_at" | "auto_resolve_escalations"> & {
+  auto_resolve_escalations?: number;
+};
 
 /** Stage one admitted epic (issue #292 slice S2). Idempotent on `plan_key`: a re-submitted set that
  * re-admits the same epic is a no-op returning the existing staged row, so the whole set door stays
- * idempotent (mirroring {@link recordAdmittedPlanDep}). */
+ * idempotent (mirroring {@link recordAdmittedPlanDep}).
+ *
+ * The escalation-steward opt-in is MONOTONIC on the existing row (issue #889 review): if an opted-out
+ * admission was staged and the request crashed before lowering, a retry that now opts in must WIDEN
+ * the staged row to opted-in — otherwise the epic starts opted out despite the caller's opt-in. This
+ * mirrors `submitPr`'s live-loop adoption (service.ts): an opted-in caller adopting an existing
+ * non-opted-in row widens it, never narrows an opted-in row back. Only ever flips 0→1. */
 export async function recordAdmittedEpic(
   data: DataLayer,
   epic: AdmittedEpicInput,
 ): Promise<AdmittedEpic> {
   const table = admittedEpics(data);
+  // The ONE canonical widening (issue #889 review): an opted-in caller observing a non-opted-in
+  // staged row widens it 0→1 and returns the widened row; otherwise returns the row unchanged. Shared
+  // by BOTH the read-existing path AND the concurrent-insert catch path, so the race below can never
+  // skip the widening the single-threaded path applies.
+  const widen = async (staged: AdmittedEpic): Promise<AdmittedEpic> => {
+    if (epic.auto_resolve_escalations === 1 && staged.auto_resolve_escalations !== 1) {
+      await table.update(epic.plan_key, { auto_resolve_escalations: 1 });
+      return { ...staged, auto_resolve_escalations: 1 };
+    }
+    return staged;
+  };
   const existing = await table.get(epic.plan_key);
-  if (existing) return existing;
-  const row: AdmittedEpic = { ...epic, created_at: now() };
+  if (existing) return widen(existing);
+  // Default the opt-in to 0 (opted out) when a caller omits it, so the staged row always carries the
+  // flag explicitly and the lowering never reads an undefined it would silently coerce.
+  const row: AdmittedEpic = { ...epic, auto_resolve_escalations: epic.auto_resolve_escalations ?? 0, created_at: now() };
   try {
     await table.insert(row);
     return row;
   } catch (err) {
     // Concurrent re-admission of the same epic races on the PRIMARY KEY (plan_key); honour the
     // idempotent no-op contract by returning the winning row rather than surfacing the collision.
+    // The winning row may be an opted-OUT insert that beat an opted-IN caller — apply the SAME
+    // monotonic widening before returning it, or the raced opt-in is silently lost (issue #889
+    // review): the caller opted in but the staged row stays 0.
     const raced = await table.get(epic.plan_key);
-    if (raced) return raced;
+    if (raced) return widen(raced);
     throw err;
   }
 }
@@ -895,6 +929,9 @@ export interface StartPlanOptions {
   readinessProbes?: ReadinessProbe[];
   probeTimeout?: string;
   probePollEvery?: string;
+  /** Opt-in escalation steward (issue #889): when true, this epic's escalations — and every child
+   * convergence/merge loop it spawns — become eligible for steward auto-resolution. Default false. */
+  autoResolveEscalations?: boolean;
 }
 
 /** Register a plan row (if new) and start the plan-fanout process. Idempotent on
@@ -981,6 +1018,7 @@ export async function startPlan(
       epic_phase: EPIC_PHASE.PLANNING,
       blackboard_token: token,
       base_branch: base,
+      auto_resolve_escalations: opts.autoResolveEscalations === true ? 1 : 0,
       updated_at: ts,
     });
   } else {
@@ -996,6 +1034,7 @@ export async function startPlan(
       epic_phase: EPIC_PHASE.PLANNING,
       blackboard_token: token,
       base_branch: base,
+      auto_resolve_escalations: opts.autoResolveEscalations === true ? 1 : 0,
       created_at: ts,
       updated_at: ts,
     });
@@ -1022,6 +1061,10 @@ export async function startPlan(
       // `operators` candidate group); an operator/agent can claim/reassign via the task inbox.
       escalationSlaTimeout: ESCALATION_SLA_TIMEOUT,
       escalationAssignee: null,
+      // Opt-in escalation steward (issue #889): carried on the instance so child processes inherit it,
+      // AND persisted on the `plans` row (the durable source the steward's eligibility reads), so an
+      // agent-completion clobber of the variable can never silently opt an epic in or out (#887/#888).
+      autoResolveEscalations: opts.autoResolveEscalations === true,
       // Agent-task liveness SLA (issue #849): PRE-SEED the canonical bound for the fan-out's
       // external agent tasks. Each slice's implementation agent (via the implement-cell
       // callActivity's explicit `agentSlaTimeout` input mapping) is bounded today; the wave's own

package/app/planLowering.test.ts

@@ -58,7 +58,7 @@ function makeData() {
   return { data, engine, tables, started };
 }
 
-function stageEpic(tables: Map<string, Record<string, unknown>[]>, planKey: string, base: string) {
+function stageEpic(tables: Map<string, Record<string, unknown>[]>, planKey: string, base: string, autoResolve = 0) {
   const rows = tables.get("admitted_epics") ?? [];
   tables.set("admitted_epics", rows);
   const [repo, num] = planKey.split("#");
@@ -68,6 +68,7 @@ function stageEpic(tables: Map<string, Record<string, unknown>[]>, planKey: stri
     issue_number: Number(num),
     issue_url: `https://github.com/${repo}/issues/${num}`,
     base_branch: base,
+    auto_resolve_escalations: autoResolve,
     created_at: "t0",
   });
 }
@@ -184,3 +185,27 @@ test("lowerAdmittedSet is idempotent: re-running neither double-starts an epic n
   assertEquals(started.length, 2, "no epic re-started on a re-run");
   assertEquals((tables.get("plan_deps") ?? []).length, 1, "no duplicate durable edge on a re-run");
 });
+
+// ── issue #889: the escalation-steward opt-in reaches batch-admitted epics ──────────────────────
+test("lowerAdmittedSet forwards the staged escalation-steward opt-in to startPlan (issue #889 — batch epic path)", async () => {
+  const { data, engine, tables, started } = makeData();
+  // Stage one opted-IN epic and one opted-OUT epic. The batch door (`startEpicSet`) records the
+  // caller's per-epic `autoResolveEscalations` onto the staging row; the lowering must forward it to
+  // `startPlan` (which seeds the `autoResolveEscalations` instance variable + the durable plans row),
+  // exactly as the single-issue door does. Before the fix the flag was dropped at the staging seam,
+  // so every batch-admitted epic stayed opted out.
+  stageEpic(tables, "o/r#1", "epic/in", 1);
+  stageEpic(tables, "o/r#2", "epic/out", 0);
+
+  await noFetch(() => lowerAdmittedSet(data, engine, ["o/r#1", "o/r#2"]));
+
+  const byKey = new Map(started.map((s) => [s.variables?.["planKey"], s.variables ?? {}]));
+  assertEquals(byKey.get("o/r#1")?.["autoResolveEscalations"], true, "opted-in epic propagates the steward opt-in");
+  assertEquals(byKey.get("o/r#2")?.["autoResolveEscalations"], false, "opted-out epic stays opted out");
+
+  // And the durable plans rows carry it (the steward eligibility reads the durable row, not the var).
+  const plans = tables.get("plans") ?? [];
+  const planByKey = new Map(plans.map((p) => [p["plan_key"], p]));
+  assertEquals(planByKey.get("o/r#1")?.["auto_resolve_escalations"], 1, "opted-in plans row persisted");
+  assertEquals(planByKey.get("o/r#2")?.["auto_resolve_escalations"], 0, "opted-out plans row persisted");
+});

package/app/planLowering.ts

@@ -166,6 +166,11 @@ export async function lowerAdmittedSet(
       readinessProbes: gate?.probes,
       probeTimeout: gate?.probeTimeout,
       probePollEvery: gate?.probePollEvery,
+      // Forward the escalation-steward opt-in staged at admission (issue #889) so a batch-admitted
+      // epic honours the caller's choice exactly like the single-issue door. `=== 1` coerces the
+      // SQLite 0|1 (and any pre-124 row that predates the column reads as 0 ⇒ opted out, the safe
+      // default).
+      autoResolveEscalations: staged.auto_resolve_escalations === 1,
     });
   }
 

package/app/promotionPoll.test.ts

@@ -163,6 +163,25 @@ test("pollPromotion: a landed epic on an epic/* base opens exactly one epic/*→
   assert(prRow, "promotion PR row registered by submitPr");
 });
 
+test("pollPromotion: the promotion PR inherits the epic's escalation-steward opt-in (issue #889 review)", async () => {
+  const { data, stores } = memData();
+  const { engine, instances } = recordingEngine();
+  // An OPTED-IN epic — its promotion PR must be enrolled with the steward opt-in, not the `false` default.
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: null, promotion_state: null, auto_resolve_escalations: 1 },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#295", pr_key: "o/r#299" }];
+  stores.pull_requests = [{ pr_key: "o/r#299", status: "merged" }];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(instances.length, 1);
+  assertEquals(instances[0].variables.autoResolveEscalations, true, "the promotion PR is enrolled opted-in");
+  const prRow = stores.pull_requests.find((p) => p.pr_key === "o/r#500");
+  assertEquals(prRow?.auto_resolve_escalations, 1, "the PR row persists the opt-in");
+});
+
 test("pollPromotion: re-running is idempotent — no duplicate promotion PR", async () => {
   const { data, stores } = memData();
   const { engine } = recordingEngine();

package/app/pullRequestReadModel.test.ts

@@ -33,7 +33,7 @@ import {
 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 = "118_pull_requests_read_model_churn_escalated_round.sql";
+const READ_MODEL_MIGRATION = "122_pull_requests_read_model_auto_resolve.sql";
 
 // The real base `pull_requests` columns, in schema order — DERIVED from the migration chain (not a
 // hand-kept list that could silently omit one), used by both the drift guard and the e2e stand-in.

package/app/service.test.ts

@@ -1142,6 +1142,42 @@ test("a gated submitPr adopting a live loop narrows it to humanApproval (issue #
   });
 });
 
+// Steward opt-in is monotonic too (issue #889 review): an opted-in caller adopting a live loop widens
+// the durable subject row to opted-in (the steward reads `auto_resolve_escalations` off the row, not a
+// process variable), and a non-opted-in retry must never downgrade an already-opted-in row. This is
+// safety-critical propagation — without it an opted-in adopter silently inherits a non-opted-in loop and
+// its escalations stay human-only. These pin both directions of the monotonic write at service.ts.
+test("steward opt-in adoption is monotonic: an opted-in adopter upgrades a live opted-out row (issue #889)", async () => {
+  await withGithubOff(async () => {
+    const pr = { repo: "owner/repo", number: 14, url: "https://github.com/owner/repo/pull/14", prKey: "owner/repo#14" };
+    // Live loop started WITHOUT the opt-in (auto_resolve_escalations unset → 0).
+    const live = adoptLoop("converging", "ACTIVE");
+    // An opted-in adopter (autoResolveEscalations = true, the 9th arg) must widen the row to opted-in.
+    assertEquals(
+      await submitPr(live.data, live.engine, pr, [], 20, false, null, false, true),
+      { prKey: pr.prKey, alreadyRunning: true },
+    );
+    const row = (await live.data.table("pull_requests", "pr_key").get(pr.prKey)) as { auto_resolve_escalations?: number } | null;
+    assertEquals(row?.auto_resolve_escalations, 1, "opted-in adopter upgrades the live row to opted-in");
+  });
+});
+
+test("steward opt-in adoption never downgrades: an opted-out retry leaves an opted-in row alone (issue #889)", async () => {
+  await withGithubOff(async () => {
+    const pr = { repo: "owner/repo", number: 14, url: "https://github.com/owner/repo/pull/14", prKey: "owner/repo#14" };
+    // Live loop already opted in.
+    const live = adoptLoop("converging", "ACTIVE");
+    (live.data.table("pull_requests", "pr_key") as any).update(pr.prKey, { auto_resolve_escalations: 1 });
+    // A non-opted-in adopter (autoResolveEscalations = false) must NOT clear the existing opt-in.
+    assertEquals(
+      await submitPr(live.data, live.engine, pr, [], 20, false, null, false, false),
+      { prKey: pr.prKey, alreadyRunning: true },
+    );
+    const row = (await live.data.table("pull_requests", "pr_key").get(pr.prKey)) as { auto_resolve_escalations?: number } | null;
+    assertEquals(row?.auto_resolve_escalations, 1, "an opted-out retry never downgrades an opted-in row");
+  });
+});
+
 test("human approval is pinned off when NANO_PR_AUTO_MERGE is off — the PR never merges (issue #826)", async () => {
   // `AUTO_MERGE` is read once at import, so load a fresh copy of the module under the env.
   const prev = process.env["NANO_PR_AUTO_MERGE"];

package/app/service.ts

@@ -34,10 +34,11 @@ import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./delivery.ts";
 import { DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
-import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels, reconcileOriginalInstanceBeforeRelaunch, reconcileStaleLaunchClaim } from "./deliveryGraphRun.ts";
+import { DELIVERY_GRAPH_TERMINAL_STATUSES, deliveryGraphRuns, deliveryGraphRunsTracking, deriveDeliveryPhase, parseHumanLabels, reconcileOriginalInstanceBeforeRelaunch, reconcileStaleLaunchClaim } from "./deliveryGraphRun.ts";
 import { decodeLivePrompt, deliveryHumanContextQuestion, deliveryHumanContextUrl, isDeliveryHumanElement, needsLiveDeliveryPrompt } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
+import { ESCALATION_STEWARD_PROCESS_ID } from "./escalationSteward.ts";
 import { deriveFeatureCompletion, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns, featureRunsTracking, foldCompletedFeatureRun } from "./feature.ts";
 import {
   classifyMergeability,
@@ -98,7 +99,7 @@ import { ENGINE_TERMINAL_STATES } from "./reconcile.ts";
 // (submitPr/startMerge) and re-exported below so the long-standing `import { repoEnvelopeVars } from
 // "./service.ts"` call sites (and its tests) keep resolving.
 import { repoEnvelopeVars } from "./repoEnvelope.ts";
-import { clampNudgeMinutes, isReviewStale, reviewWaitTimeout } from "./reviewWait.ts";
+import { clampNudgeMinutes, isoDurationToMs, isReviewStale, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
   buildUserTaskRow,
@@ -399,6 +400,9 @@ export interface PullRequest {
   // `pr_key` so the Lineage UI join resolves; a legacy NULL is tolerated the same way by the
   // lineage read projection (`pollLineage`), which self-roots on `pr_key`.
   root_request_key: string | null;
+  // Opt-in escalation steward (120_escalation_auto_resolutions.sql, issue #889): 1 ⇒ this PR's open
+  // escalations are eligible for the steward to auto-resolve (recorded reviewably). Default 0.
+  auto_resolve_escalations: number;
 }
 
 interface PrDependency {
@@ -621,9 +625,10 @@ export async function submitPr(
   convergeOnly = false,
   rootRequestKey: string | null = null,
   humanApproval = false,
+  autoResolveEscalations = false,
 ) {
   return withPrSubmitLock(parsed.prKey, () =>
-    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval),
+    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval, autoResolveEscalations),
   );
 }
 
@@ -636,6 +641,7 @@ async function submitPrCritical(
   convergeOnly = false,
   rootRequestKey: string | null = null,
   humanApproval = false,
+  autoResolveEscalations = false,
 ) {
   // Human approval before merge (issue #826) gates only a PR that `pr.finalize` would hand to the
   // merge-loop — its own predicate, `AUTO_MERGE && convergeOnly !== true`. A run that won't merge
@@ -677,6 +683,15 @@ async function submitPrCritical(
         await engine.setVariables({ scopeKey: loopKey, variables: { humanApproval: true } });
       }
     }
+    // Steward opt-in is monotonic too (issue #889 review): an opted-in caller adopting a live loop —
+    // possibly a non-opted-in one another run started — widens it to opted-in so the steward can serve
+    // its escalations, rather than silently inheriting the loop's non-opted-in state. The steward reads
+    // the flag off the SUBJECT row (`optInByProcessKey`), not a process variable, so the durable row
+    // update is the whole propagation — no `setVariables` is needed (or possible: the loop never reads
+    // it). Idempotent; a retry against our own opted-in loop is a no-op write.
+    if (autoResolveEscalations && existing.auto_resolve_escalations !== 1) {
+      await table.update(parsed.prKey, { auto_resolve_escalations: 1 });
+    }
     return { prKey: parsed.prKey, alreadyRunning: true };
   }
 
@@ -759,6 +774,7 @@ async function submitPrCritical(
       current_round: 1,
       abandon_token: abandonToken,
       root_request_key: effectiveRoot,
+      auto_resolve_escalations: autoResolveEscalations ? 1 : 0,
       created_at: ts,
       updated_at: ts,
     });
@@ -808,6 +824,10 @@ async function submitPrCritical(
       // Human approval before merge (issue #826): a converged PR parks at the `merge-approval` user
       // task before `pr.finalize` hands it to the merge-loop. Pinned off when the PR won't merge.
       humanApproval: gated,
+      // Opt-in escalation steward (issue #889): carried on the instance AND persisted on the
+      // `pull_requests` row (the durable source the steward's eligibility reads), so a clobbered
+      // variable can never silently opt a PR in or out (#887/#888).
+      autoResolveEscalations,
       // Cooperative abandon check (#76): the capability URL + the abort brief appended to the
       // review-round agent's prompt, so it can stop before pushing if the run is cancelled.
       abandonUrl: abUrl,
@@ -884,6 +904,9 @@ async function submitPrCritical(
         merged_at: null,
         abandon_token: abandonToken,
         root_request_key: effectiveRoot,
+        // Record the opt-in on the row (the durable source the steward's eligibility reads) so a
+        // fresh run's flag is authoritative even across a reopen (issue #889).
+        auto_resolve_escalations: autoResolveEscalations ? 1 : 0,
         // Publish the fresh run's identity in the SAME write as the status flip (may be null if the
         // instance could not be created — a phantom row a retry re-enrolls, as on first submit).
         process_key: processKey,
@@ -1018,6 +1041,9 @@ export interface ActivePr {
   activeWorker: string | null;
   /** ISO ts the current activation lease expires; null when not activated. */
   leaseUntil: string | null;
+  /** Whether this PR opted in to the escalation steward (issue #889) — its open escalations are
+   * eligible for steward auto-resolution. Shown in `/status` per PR. */
+  autoResolveEscalations: boolean;
 }
 
 /** Every tracked PR not in a terminal state (converged/abandoned), newest-updated first. Backs
@@ -1073,6 +1099,56 @@ export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
     updatedAt: p.updated_at,
     activeWorker: p.active_worker ?? null,
     leaseUntil: p.lease_until ?? null,
+    autoResolveEscalations: p.auto_resolve_escalations === 1,
+  }));
+}
+
+/** A delivery-graph run currently in flight, as reported by the status endpoint (issue #889 §1 —
+ *  "Show it in `/status` for each PR or delivery"). Mirrors {@link ActivePr} for the delivery side. */
+export interface ActiveDelivery {
+  runKey: string;
+  title: string | null;
+  status: string;
+  phase: string | null;
+  processKey: string | null;
+  openEscalation: OpenEscalation | null;
+  updatedAt: string;
+  /** Whether this run opted in to the escalation steward (issue #889) — its open escalations are
+   * eligible for steward auto-resolution. Derived from the durable `auto_resolve_escalations` flag,
+   * never a clobbered process variable. Shown in `/status` per delivery. */
+  autoResolveEscalations: boolean;
+}
+
+/** Every delivery-graph run not in a terminal state (done/failed/abandoned), newest-updated first.
+ *  Backs the delivery half of the GET status endpoint (issue #889 §1): a delivery run that opted in to
+ *  the escalation steward must surface that durable flag alongside its live escalation, exactly as a PR
+ *  does. The structured `openEscalation` pointer is derived from the SAME `user_tasks` read model as
+ *  `activePrs` (subject_type `delivery`, keyed by `run_key`), so a delivery node's parked human/escalation
+ *  task carries its completable `userTaskKey` here too. */
+export async function activeDeliveries(data: DataLayer): Promise<ActiveDelivery[]> {
+  // `derived_status` is a plain `string` (the tracking VIEW's fold column), while the terminal set is
+  // the narrow `DeliveryGraphRunStatus` union — classify via a `readonly string[]` view (the SAME
+  // idiom `TERMINAL_STATUSES: readonly string[]` gives the PR side) rather than a banned `as` cast.
+  const terminal: readonly string[] = DELIVERY_GRAPH_TERMINAL_STATUSES;
+  const active = (await deliveryGraphRunsTracking(data).all())
+    .filter((r) => !terminal.includes(r.derived_status))
+    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
+  const openEscByRun = new Map<string, OpenEscalation>();
+  for (const t of (await userTasks(data).find({ subject_type: "delivery" })).sort((a, b) =>
+    a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0,
+  )) {
+    if (openEscByRun.has(t.subject_key)) continue;
+    openEscByRun.set(t.subject_key, toOpenEscalation(t));
+  }
+  return active.map((r) => ({
+    runKey: r.run_key,
+    title: r.title ?? null,
+    status: r.status,
+    phase: r.phase ?? null,
+    processKey: r.process_key ?? null,
+    openEscalation: openEscByRun.get(r.run_key) ?? null,
+    updatedAt: r.updated_at,
+    autoResolveEscalations: r.auto_resolve_escalations === 1,
   }));
 }
 
@@ -2559,7 +2635,10 @@ export async function pollPromotion(data: DataLayer, engine: EngineClient, token
         }
         if (prStatus === null) {
           const parsed = parsePr(plan.promotion_pr);
-          if (parsed) await submitPr(data, engine, parsed);
+          // Thread the epic's escalation-steward opt-in (issue #889 review) so a re-enrolled
+          // promotion PR inherits the parent epic's enrolment rather than dropping to the `false`
+          // default (which would also overwrite a previously persisted opt-in with 0).
+          if (parsed) await submitPr(data, engine, parsed, [], MAX_ROUNDS, false, null, false, plan.auto_resolve_escalations === 1);
         }
         continue;
       }
@@ -2596,7 +2675,9 @@ export async function pollPromotion(data: DataLayer, engine: EngineClient, token
         updated_at: now(),
       });
       const parsed = parsePr(promotionPrKey);
-      if (parsed) await submitPr(data, engine, parsed);
+      // Thread the epic's escalation-steward opt-in (issue #889 review) so the freshly opened
+      // promotion PR is enrolled with the parent epic's enrolment, not the `false` default.
+      if (parsed) await submitPr(data, engine, parsed, [], MAX_ROUNDS, false, null, false, plan.auto_resolve_escalations === 1);
       console.log(
         `[poller] promotion PR ${result.created ? "opened" : "reused"} ${promotionPrKey} (${base} -> ${target})`,
       );
@@ -2705,6 +2786,10 @@ export async function pollFeatureDelivery(
             run.auto_merge !== 1,
             run.feature_key,
             run.human_approval === 1,
+            // Thread the run's escalation-steward opt-in (issue #889 review) so a re-enrolled PR
+            // inherits the feature run's enrolment — and a partial-enrollment repair never overwrites
+            // the PR row's previously persisted opt-in with the `false` default.
+            run.auto_resolve_escalations === 1,
           );
         }
       }
@@ -3779,6 +3864,46 @@ export async function pollUserTasks(
   }
 }
 
+/** Escalation-steward tick (issue #889): start ONE `escalation-steward` instance per interval when the
+ * loop is enabled (`NANO_ESCALATION_STEWARD` not off) and the previous tick's instance has finished.
+ * The collect step's own overlap guard is the authoritative no-op for a still-active prior run; this
+ * pass adds the interval pacing + the master switch. Self-scheduled via `pollOnce`; the interval is
+ * `NANO_ESCALATION_STEWARD_INTERVAL` (default `R/PT30M` — the poll reads its `PT…` duration part).
+ * Best-effort + idempotent — a failed start is logged and retried next pass, never wedges the loop. */
+let lastStewardTick = 0;
+export async function pollEscalationSteward(engine: EngineClient) {
+  const disabled = /^(0|off|false|no)$/i.test(readEnvOr("NANO_ESCALATION_STEWARD", "1"));
+  if (disabled) return;
+  // Parse the interval through the ONE canonical ISO-8601 duration parser (`isoDurationToMs`,
+  // app/reviewWait.ts) so the pacing can never drift from the grammar every other timer in the app
+  // uses. The env may carry a bare duration (`PT30M`) or a repeat interval (`R/PT30M`); strip an
+  // optional `R…/` prefix and parse the `P…` period. A malformed value falls back to 30 min; a
+  // zero/negative interval is clamped to that fallback so a steward never starts every poll.
+  const DEFAULT_INTERVAL_MS = 30 * 60 * 1000;
+  const cycle = readEnvOr("NANO_ESCALATION_STEWARD_INTERVAL", "PT30M");
+  const period = cycle.includes("/") ? cycle.slice(cycle.lastIndexOf("/") + 1) : cycle;
+  const parsedMs = isoDurationToMs(period, "PT30M");
+  const intervalMs = parsedMs > 0 ? parsedMs : DEFAULT_INTERVAL_MS;
+  const nowMs = Date.now();
+  if (nowMs - lastStewardTick < intervalMs) return;
+  // Overlap guard (cheap, pre-start): don't start a new tick while a prior one is still ACTIVE.
+  const active = await engine.searchProcessInstances({ processDefinitionId: ESCALATION_STEWARD_PROCESS_ID, state: "ACTIVE" });
+  if (active.length > 0) return;
+  const minAgeMs = Number(readEnvOr("NANO_ESCALATION_STEWARD_MIN_AGE_MS", "300000"));
+  // Advance the tick ONLY after a successful start: if `createInstance` throws, leaving
+  // `lastStewardTick` untouched lets the next pass retry immediately rather than suppressing retries
+  // for the whole interval (the "retried next pass" contract).
+  // Seed the canonical agent-task SLA (`agentSlaTimeout`, issue #849) so the steward-agent's
+  // interrupting timer boundary (`be_steward_sla`) bounds a hung agent run — without it a wedged
+  // agent parks the instance ACTIVE forever and the overlap guard above suppresses every later tick
+  // (issue #889 review).
+  await engine.createInstance({
+    processDefinitionId: ESCALATION_STEWARD_PROCESS_ID,
+    variables: { minAgeMs, agentSlaTimeout: AGENT_SLA_TIMEOUT },
+  });
+  lastStewardTick = nowMs;
+}
+
 /** One full poll pass: advance the review stage, the merge stage, the wave-merge barrier, and
  * (when the engine REST endpoint is supplied) the job-activation visibility pass and the
  * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`.
@@ -3799,6 +3924,15 @@ export async function pollOnce(
   await pollFeatureDelivery(data, engine);
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
+  // The escalation steward is an OPTIONAL, best-effort pass: a steward-specific failure (a search or
+  // instance-start error) must never reject `pollOnce` and starve the unrelated epic / taskless-plan /
+  // delivery-graph reconciliation passes that follow it. Catch + log it independently so the canonical
+  // poller always continues (issue #889 review).
+  try {
+    await pollEscalationSteward(engine);
+  } catch (err) {
+    console.error(`[poller] escalation-steward tick: ${err instanceof Error ? err.message : String(err)}`);
+  }
   await pollEpicPhase(data, engine, engineRest);
   await pollTasklessPlanTermination(data, engine);
   await pollDeliveryGraphPhase(data, engine);