@nanobpm/nano-workforce 0.201.5 → 0.203.0

package/app/agentic/families/claim.family.test.ts

@@ -56,6 +56,10 @@ function releaseFrame(instance: string, jobKey: string): Frame {
   return { lane: "control", family: RELEASE_FAMILY, seq: 1, payload: { instance, jobKey } };
 }
 
+function resyncFrame(instance: string, jobKeys: string[]): Frame {
+  return { lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance, jobKeys } };
+}
+
 function mountClaim(): { hub: AgenticHub; transport: ReturnType<typeof memTransport> } {
   const transport = memTransport();
   const hub = new AgenticHub({ transport: transport.transport, authenticator, sweepIntervalMs: 0 });
@@ -189,6 +193,218 @@ test("a malformed claim payload is rejected without touching the registry (advis
   }
 });
 
+test("a resync snapshot frame REPLACES an instance's claims — a RELEASE lost during an outage no longer strands the job", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    peer.feed(claimFrame("wk-a", "8421"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420", "8421"]);
+
+    // The hub missed the `release` for 8420 during an outage. On reconnect the supervisor restates its
+    // authoritative snapshot: wk-a now owns only 8421. The non-re-asserted 8420 is dropped.
+    peer.feed(resyncFrame("wk-a", ["8421"]));
+    await flush();
+    assertEquals(reg.jobKeysFor("wk-a"), ["8421"], "the stranded claim was dropped on resync");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a resync snapshot does NOT blank a jobKey that moved to another instance", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    peer.feed(claimFrame("wk-b", "8420")); // 8420 moved to wk-b
+    await flush();
+
+    // wk-a's authoritative resync no longer mentions 8420 — and must not blank the live owner wk-b.
+    peer.feed(resyncFrame("wk-a", []));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-b"), ["8420"], "the current owner's claim survives");
+    assertEquals(reg.ownerOf("8420"), "wk-b");
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a supervisor that never sends a resync snapshot keeps today's additive claim behaviour", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    // Only per-job claims, no snapshot frame — a claim is never dropped except by an explicit release.
+    peer.feed(claimFrame("wk-a", "8420"));
+    peer.feed(claimFrame("wk-a", "8421"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420", "8421"], "additive — neither claim is dropped");
+    assertEquals(reg.count(), 2);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a resync snapshot with a non-string instance is ignored (advisory, connection kept)", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    // A malformed snapshot (no instance) is rejected without touching the registry.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { jobKeys: ["8421"] } });
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the registry was untouched by the malformed snapshot");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a snapshot frame carrying BOTH jobKeys and a malformed jobKey is rejected — the snapshot branch never bypasses validation", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    // The bypass the reviewer flagged: `jobKeys` present routed the frame straight to replaceInstance,
+    // so a smuggled empty `jobKey` was never validated. The union validator rejects it.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKey: "", jobKeys: ["8421"] } });
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the malformed both-fields frame touched nothing");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a frame with a valid jobKey but a PRESENT malformed jobKeys is rejected — a broken snapshot can't launder as a per-job claim", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    // The reviewer's case: `jobKeys` is PRESENT but malformed ("invalid"), while `jobKey` is valid.
+    // Presence — not validity — selects the snapshot variant, so a broken `jobKeys` must be rejected,
+    // never treated as absent and accepted as a bare per-job claim that mutates ownership.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKey: "8421", jobKeys: "invalid" } });
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the malformed-snapshot frame touched nothing");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a snapshot frame with a PRESENT malformed jobKeys array is rejected as a broken snapshot (presence is the discriminant)", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    // `jobKeys` present but not a string array → a broken snapshot; it is rejected outright, never
+    // mistaken for a per-job claim. (No `jobKey` here either, but presence alone is enough to reject.)
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKeys: "8421" } });
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the malformed frame touched nothing");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("an EMPTY snapshot is a valid authoritative resync — the supervisor asserting it now owns nothing", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"]);
+
+    // The producer emits one snapshot per instance INCLUDING empty sets — an empty `jobKeys` is the
+    // meaningful "owns nothing now" resync, not a malformed frame.
+    peer.feed(resyncFrame("wk-a", []));
+    await flush();
+    assertEquals(reg.jobKeysFor("wk-a"), [], "the empty snapshot cleared the instance's claims");
+    assertEquals(reg.count(), 0);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a snapshot whose jobKeys contains an EMPTY-STRING element is rejected — it can't masquerade as an 'owns nothing' resync and clear real claims", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"]);
+
+    // The empty-ARRAY resync is valid ("owns nothing"), but a present `jobKeys` with an empty-STRING
+    // element is a BROKEN snapshot — `replaceInstance` silently skips empty keys, so `[""]` would
+    // otherwise masquerade as an authoritative empty snapshot and clear every real claim. It is held
+    // to the same non-empty bar as the per-job `jobKey` and rejected outright, touching nothing.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKeys: [""] } });
+    await flush();
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the sole-empty-string snapshot did not clear the real claim");
+    assertEquals(reg.count(), 1);
+
+    // A MIXED array with one empty element is equally a broken snapshot — fail closed, not partial.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKeys: ["8421", ""] } });
+    await flush();
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the mixed empty-element snapshot touched nothing — not even the valid element");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
 test("teardown clears the singleton", () => {
   mountClaim();
   assert(currentClaimRegistry() !== undefined);

package/app/agentic/families/claim.family.ts

@@ -13,7 +13,11 @@
 // the frame, NOT the connection id (`conn.id`); that is what lets one per-host supervisor multiplex N
 // distinct workers' ownership over a single connection. On a reconnect the supervisor re-`register`s
 // every worker and re-`claim`s every active jobKey, and the (idempotent) claim handler rebuilds the
-// registry from that resync.
+// registry from that resync. A supervisor may additionally close its resync with an AUTHORITATIVE
+// snapshot frame (`claim` carrying the full `jobKeys` set for an instance, issue #893 — the
+// `claim.snapshot` wire contract in `app/contracts.ts`): the handler then `replaceInstance`s, dropping
+// any claim the supervisor did NOT re-assert — so a `release` lost during a hub outage no longer
+// strands the job. A supervisor that omits the snapshot keeps the pre-#893 additive behaviour.
 //
 // Liveness: a worker holding a claim reads "working" even with ZERO transcript — visibility no longer
 // depends on terminal bytes landing/correlating. A bounded-memory maintenance tick reconciles the
@@ -46,6 +50,81 @@ function readString(value: unknown, key: string): string | undefined {
   return typeof field === "string" ? field : undefined;
 }
 
+/**
+ * The classification of a `claim` frame's `jobKeys` field. Its PRESENCE — NOT its validity — is the
+ * discriminant that tells an authoritative resync snapshot (`{ instance, jobKeys }`, issue #893) apart
+ * from a classic per-job claim (`{ instance, jobKey }`). So a PRESENT-but-malformed `jobKeys` is a
+ * BROKEN snapshot and must be rejected; it must never be treated as "absent" and laundered through the
+ * per-job validator (which tolerates the extra field), because that would let a malformed snapshot
+ * field mutate ownership on a frame that merely carries a valid `jobKey`.
+ */
+type JobKeysField =
+  | { present: false }
+  | { present: true; malformed: true }
+  | { present: true; malformed: false; jobKeys: readonly string[] };
+
+/**
+ * Classify a frame payload's `jobKeys` field. It rides the existing `claim` wire family as a
+ * forward-compatible enrichment — the protocol's structural validators tolerate the extra field, so an
+ * older hub ignores it and keeps additive behaviour. This is the SINGLE source that both the validator
+ * and the handler branch on, so the "present ⇒ snapshot" discriminant cannot drift between them.
+ */
+function readJobKeysField(value: unknown): JobKeysField {
+  if (!value || typeof value !== "object") return { present: false };
+  if (!Object.hasOwn(value, "jobKeys")) return { present: false };
+  const field = Object.getOwnPropertyDescriptor(value, "jobKeys")?.value;
+  // Each element must be a NON-EMPTY string — the canonical per-job validator requires a non-empty
+  // `jobKey`, so a snapshot entry is held to the same bar. An empty-string element is NOT a benign
+  // "owns nothing" signal (that is the empty ARRAY): `replaceInstance` silently skips empty keys, so
+  // `{ instance, jobKeys: [""] }` would otherwise masquerade as an authoritative empty snapshot and
+  // clear every real claim. Fail closed — a present `jobKeys` with any empty element is a broken
+  // snapshot and is rejected, never laundered through the per-job validator.
+  if (!Array.isArray(field) || !field.every((k) => typeof k === "string" && k !== "")) {
+    return { present: true, malformed: true };
+  }
+  return { present: true, malformed: false, jobKeys: field };
+}
+
+/**
+ * The `claim` family carries TWO payload variants (issue #893 — the `claim.snapshot` wire contract in
+ * `app/contracts.ts`): the classic per-job claim `{ instance, jobKey }` and the authoritative resync
+ * snapshot `{ instance, jobKeys }`. The pinned `@nanobpm/agentic` validator predates the snapshot
+ * variant and REQUIRES a non-empty `jobKey`, so it cannot validate the union — routing a snapshot
+ * through `validatePayload` would reject the very frame that closes a resync. Validate the union
+ * locally instead: a payload is well-formed iff it is EITHER a valid snapshot (non-empty `instance`
+ * plus a `jobKeys` array of NON-EMPTY strings — an EMPTY array is the meaningful "owns nothing now"
+ * resync) OR a valid per-job claim per the canonical validator. This is a UNION with a VALIDATED
+ * OVERLAP, not an exclusive-or: a frame carrying BOTH fields is accepted, but only when BOTH halves
+ * validate — it is validated as a snapshot AND must still pass the per-job validator, so a malformed
+ * `jobKey` can no longer smuggle past on a snapshot frame.
+ */
+function validateClaimPayload(payload: unknown): { ok: boolean; codes: string[] } {
+  const field = readJobKeysField(payload);
+  if (field.present) {
+    // PRESENCE selects the snapshot variant unconditionally. A present-but-malformed `jobKeys` is a
+    // broken snapshot — reject it here rather than letting it fall through to the per-job validator,
+    // which would accept it (extra fields tolerated) on any frame that also carries a valid `jobKey`.
+    if (field.malformed) {
+      return { ok: false, codes: ["bad-jobKeys"] };
+    }
+    const instance = readString(payload, "instance");
+    if (instance) {
+      // A frame carrying BOTH variants must satisfy both — the snapshot branch must never launder a
+      // malformed per-job field past validation. (readJobKeysField defined the value as an object.)
+      if (typeof payload === "object" && payload !== null && !Object.hasOwn(payload, "jobKey")) {
+        return { ok: true, codes: [] };
+      }
+      const both = validatePayload(CLAIM_FAMILY, payload);
+      return both.ok ? { ok: true, codes: [] } : { ok: false, codes: both.errors.map((e) => e.code) };
+    }
+    // A snapshot-shaped payload with a missing/empty instance is NOT a valid per-job claim either
+    // (jobKey is absent) — report the snapshot violation precisely.
+    return { ok: false, codes: ["bad-instance"] };
+  }
+  const result = validatePayload(CLAIM_FAMILY, payload);
+  return result.ok ? { ok: true, codes: [] } : { ok: false, codes: result.errors.map((e) => e.code) };
+}
+
 interface MountState {
   readonly registry: ClaimRegistry;
   timer: ReturnType<typeof setTimeout> | undefined;
@@ -72,9 +151,26 @@ export const family: AgenticFamily = {
     // malformed payload is rejected before it touches the registry (advisory: logged, connection
     // kept). Both mutations are idempotent, matching the wire contract.
     ctx.hub.registerFamilyHandler(CLAIM_FAMILY, (frame: Frame, _conn: HubConnection) => {
-      const result = validatePayload(CLAIM_FAMILY, frame.payload);
-      if (!result.ok) {
-        ctx.log.warn("agentic claim: malformed payload", { errors: result.errors.map((e) => e.code) });
+      // An authoritative resync SNAPSHOT (`{ instance, jobKeys }`, issue #893): the reconnecting
+      // supervisor restates the full current ownership for one instance and its view WINS —
+      // `replaceInstance` drops every claim it did NOT re-assert (so a `release` lost during a hub
+      // outage no longer strands the job). A supervisor that never sends it keeps additive behaviour.
+      // EVERY claim frame is validated first — as the snapshot/per-job union (a both-fields frame is
+      // accepted only when both halves validate) — so the snapshot
+      // branch never bypasses validation (a malformed frame is dropped before it touches the
+      // registry, exactly like a malformed per-job claim).
+      const valid = validateClaimPayload(frame.payload);
+      if (!valid.ok) {
+        ctx.log.warn("agentic claim: malformed payload", { errors: valid.codes });
+        return;
+      }
+      const field = readJobKeysField(frame.payload);
+      if (field.present && !field.malformed) {
+        // Validated above, so the instance is present and non-empty (and a malformed `jobKeys` was
+        // already rejected, so `field.present && field.malformed` can never reach the registry).
+        const instance = readString(frame.payload, "instance");
+        if (!instance) return;
+        registry.replaceInstance(instance, field.jobKeys);
         return;
       }
       const instance = readString(frame.payload, "instance");

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",
@@ -443,6 +466,14 @@ export const WIRE_CONTRACTS = {
       "Op-tagged relay control frame a worker terminal chunk producer emits and the hub consumes. The op-tagged shape superseded the legacy positional `{stream, offset, chunk}` frame (nano-ide #234/#236); a producer must emit the op-tagged shape or the hub rejects it as `malformed relay message payload`.",
     shape: '{ op: "produce", incarnation: number, stream: string, offset: number, chunk: string }',
   },
+  "claim.snapshot": {
+    category: "wire",
+    name: "claim.snapshot",
+    owner: "app/agentic/families/claim.family.ts (hub consumer); nano-supervisor#63 (producer)",
+    semantics:
+      "Authoritative reconnect-resync snapshot riding the EXISTING `claim` wire family (wire code 8, nano-ide#542) as a forward-compatible enrichment — the issue #893 resync boundary. A reconnecting supervisor closes its per-instance resync with ONE snapshot frame carrying the full current jobKey set for that instance; the hub validates it (as a snapshot/per-job UNION with a VALIDATED OVERLAP, not an exclusive-or — a both-fields frame is accepted only when BOTH halves validate; the pinned `@nanobpm/agentic` validator predates this variant and requires a non-empty `jobKey`, so the union is validated hub-side until nano-ide versions the shape into the canonical protocol payloads) and calls `ClaimRegistry.replaceInstance(instance, jobKeys)`, dropping every claim the supervisor did NOT re-assert so a `release` lost during a hub outage no longer strands the job. `jobKeys` MAY be the empty ARRAY (the meaningful 'owns nothing now' resync — this is why the producer emits one snapshot per instance INCLUDING empty sets), but every ELEMENT must be a NON-EMPTY string (held to the same bar as the per-job `jobKey`); a present `jobKeys` that is a non-array, has a non-string element, or has an empty-string element is a BROKEN snapshot and is rejected (fail closed), never laundered through the per-job validator. The frame's explicit `instance` is the owning worker, never the connection id. Compatibility: the protocol's structural validators tolerate the extra field, so an older hub ignores it and keeps additive behaviour; a supervisor that never sends a snapshot keeps the pre-#893 additive behaviour. Distinct from the classic per-job claim `{ instance, jobKey }` (the `@nanobpm/agentic` `ClaimPayload`) — consume this ONE shape for the resync boundary, do not re-declare a synonym.",
+    shape: '{ instance: string, jobKeys: string[] } — a `claim` (wire code 8) frame whose `jobKeys` array PRESENCE is the discriminant; a UNION with the per-job `{ instance: string, jobKey: string }` (a both-fields frame is accepted only when both halves validate, not an exclusive-or)',
+  },
   "io.nanobpm.agentTask.repository": {
     category: "wire",
     name: "io.nanobpm.agentTask.repository",

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