@nanobpm/nano-workforce 0.201.5 → 0.203.0

package/db/migrations/120_escalation_auto_resolutions.sql

@@ -0,0 +1,229 @@
+-- Issue #889: opt-in escalation steward. Two halves, both additive (expand-and-contract):
+--
+--   1. `auto_resolve_escalations` (0|1, default 0) on each escalation-raising subject table —
+--      `feature_runs`, `plans`, `pull_requests`, `delivery_graph_runs` — recording whether the work
+--      OPTED IN to having its open escalations auto-resolved by the steward. The steward's
+--      eligibility derivation (app/escalationSteward.ts) reads the flag off the SUBJECT row keyed by
+--      the escalation's owning process instance, so an escalation from non-opted-in work is never
+--      touched. Mirrored into the `delivery_units` aggregate (ADR 0006) — the sync triggers (089) and
+--      compat VIEWs (091) are re-created verbatim plus the new column, exactly as migration 116 did
+--      for `human_approval` (parity-tested in app/deliveryUnit.test.ts).
+--
+--   2. `escalation_auto_resolutions` — the durable, reviewable record of every escalation the steward
+--      ACTED ON or ABSTAINED from (one row each), backing the Auto-resolutions view and the
+--      dismiss/intervene doors. `review_state` starts `pending`; an operator `dismiss`/`intervene`
+--      folds it to `dismissed`/`intervened` with `reviewed_by`/`reviewed_at`/`review_note`.
+
+ALTER TABLE feature_runs ADD COLUMN auto_resolve_escalations INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE plans ADD COLUMN auto_resolve_escalations INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE pull_requests ADD COLUMN auto_resolve_escalations INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE delivery_graph_runs ADD COLUMN auto_resolve_escalations INTEGER NOT NULL DEFAULT 0;
+
+-- Mirror the new column through the `delivery_units` aggregate so the compat VIEWs stay row-for-row
+-- equal to their base tables (ADR 0006, parity-tested in app/deliveryUnit.test.ts).
+ALTER TABLE delivery_units ADD COLUMN auto_resolve_escalations INTEGER;
+UPDATE delivery_units SET auto_resolve_escalations = 0 WHERE auto_resolve_escalations IS NULL;
+
+DROP TRIGGER IF EXISTS feature_runs__du_ai;
+CREATE TRIGGER feature_runs__du_ai AFTER INSERT ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, auto_resolve_escalations, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.auto_resolve_escalations, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_au;
+CREATE TRIGGER feature_runs__du_au AFTER UPDATE ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, auto_resolve_escalations, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.auto_resolve_escalations, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS plans__du_ai;
+CREATE TRIGGER plans__du_ai AFTER INSERT ON plans
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, auto_resolve_escalations, created_at, updated_at)
+  VALUES ('epic:' || NEW.plan_key, 'epic', NEW.plan_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'planning' THEN 'requested' WHEN NEW.status = 'dispatched' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('planning') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('dispatched') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.status, NEW.task_count, NEW.process_key, NEW.outcome, NEW.gate_wave, NEW.blackboard_token, NEW.retro_started_at, NEW.base_branch, NEW.epic_phase, NEW.promotion_pr, NEW.promotion_state, NEW.acknowledged_at, NEW.list_bucket, NEW.ack_open, NEW.wait_gate, NEW.wait_gate_label, NEW.bound_artifacts, NEW.auto_resolve_escalations, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS plans__du_au;
+CREATE TRIGGER plans__du_au AFTER UPDATE ON plans
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, auto_resolve_escalations, created_at, updated_at)
+  VALUES ('epic:' || NEW.plan_key, 'epic', NEW.plan_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'planning' THEN 'requested' WHEN NEW.status = 'dispatched' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('planning') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('dispatched') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.status, NEW.task_count, NEW.process_key, NEW.outcome, NEW.gate_wave, NEW.blackboard_token, NEW.retro_started_at, NEW.base_branch, NEW.epic_phase, NEW.promotion_pr, NEW.promotion_state, NEW.acknowledged_at, NEW.list_bucket, NEW.ack_open, NEW.wait_gate, NEW.wait_gate_label, NEW.bound_artifacts, NEW.auto_resolve_escalations, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_ai;
+CREATE TRIGGER delivery_graph_runs__du_ai AFTER INSERT ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, acknowledged_at, auto_resolve_escalations, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.acknowledged_at, NEW.auto_resolve_escalations, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_au;
+CREATE TRIGGER delivery_graph_runs__du_au AFTER UPDATE ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, acknowledged_at, auto_resolve_escalations, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.acknowledged_at, NEW.auto_resolve_escalations, NEW.created_at, NEW.updated_at);
+END;
+
+DROP VIEW IF EXISTS feature_runs__units;
+CREATE VIEW feature_runs__units AS
+SELECT
+  du.legacy_key AS feature_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.base_branch AS base_branch,
+  du.status AS status,
+  du.process_key AS process_key,
+  du.pr_key AS pr_key,
+  du.converge AS converge,
+  du.auto_merge AS auto_merge,
+  du.human_approval AS human_approval,
+  du.auto_resolve_escalations AS auto_resolve_escalations,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.delivery_label AS delivery_label,
+  du.title AS title,
+  du.acknowledged_at AS acknowledged_at,
+  du.stage AS stage,
+  du.stage_state AS stage_state,
+  du.stage_skipped AS stage_skipped,
+  du.attention AS attention,
+  du.list_bucket AS list_bucket
+FROM delivery_units du
+WHERE du.kind = 'feature';
+
+DROP VIEW IF EXISTS plans__units;
+CREATE VIEW plans__units AS
+SELECT
+  du.legacy_key AS plan_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.title AS title,
+  du.status AS status,
+  du.task_count AS task_count,
+  du.process_key AS process_key,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.gate_wave AS gate_wave,
+  du.blackboard_token AS blackboard_token,
+  du.retro_started_at AS retro_started_at,
+  du.base_branch AS base_branch,
+  du.epic_phase AS epic_phase,
+  du.promotion_pr AS promotion_pr,
+  du.promotion_state AS promotion_state,
+  du.acknowledged_at AS acknowledged_at,
+  du.list_bucket AS list_bucket,
+  du.ack_open AS ack_open,
+  du.wait_gate AS wait_gate,
+  du.wait_gate_label AS wait_gate_label,
+  du.bound_artifacts AS bound_artifacts,
+  du.auto_resolve_escalations AS auto_resolve_escalations
+FROM delivery_units du
+WHERE du.kind = 'epic';
+
+DROP VIEW IF EXISTS delivery_graph_runs__units;
+CREATE VIEW delivery_graph_runs__units AS
+SELECT
+  du.legacy_key AS run_key,
+  du.process_key AS process_key,
+  du.process_definition_id AS process_definition_id,
+  du.digest AS digest,
+  du.status AS status,
+  du.side_effecting AS side_effecting,
+  du.node_count AS node_count,
+  du.human_node_count AS human_node_count,
+  du.side_effect_count AS side_effect_count,
+  du.title AS title,
+  du.phase AS phase,
+  du.phase_node_id AS phase_node_id,
+  du.human_labels AS human_labels,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.acknowledged_at AS acknowledged_at,
+  du.auto_resolve_escalations AS auto_resolve_escalations
+FROM delivery_units du
+WHERE du.kind = 'delivery-graph';
+
+-- The durable, reviewable record of every escalation the steward acted on or abstained from.
+CREATE TABLE escalation_auto_resolutions (
+  id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+  -- The escalation user task acted on (the engine `userTaskKey`), its BPMN element id, and the
+  -- escalation kind label at the time (denormalised so the record survives the task completing).
+  user_task_key         TEXT NOT NULL,
+  escalation_kind       TEXT,
+  element_id            TEXT,
+  -- The subject the escalation belongs to (PR key / feature key / plan key / delivery run key).
+  subject_type          TEXT,
+  subject_key           TEXT,
+  subject_url           TEXT,
+  process_instance_key  TEXT,
+  -- Snapshots of what was asked and the choices on offer, so the record is reviewable after the fact.
+  question              TEXT,
+  options               TEXT,               -- JSON array of the form's option values/labels
+  -- `resolved` (the steward submitted an answer) or `abstained` (it deliberately left it for a human).
+  outcome               TEXT NOT NULL,      -- resolved | abstained
+  submitted_variables   TEXT,               -- JSON of the variables submitted (NULL when abstained)
+  rationale             TEXT,               -- one-line why
+  evidence              TEXT,               -- JSON/markdown: what was checked, with links
+  -- Provenance of the steward run that produced this record.
+  steward_instance_key  TEXT,
+  agent_job_key         TEXT,
+  worker                TEXT,
+  model                 TEXT,
+  created_at            TEXT NOT NULL,
+  -- Operator review lifecycle: pending → dismissed | intervened.
+  review_state          TEXT NOT NULL DEFAULT 'pending',  -- pending | dismissed | intervened
+  reviewed_by           TEXT,
+  reviewed_at           TEXT,
+  review_note           TEXT,
+  -- Claim/lease bookkeeping (not part of the review surface): which steward instance holds the open
+  -- claim and until when. NULL once the row is finalised (resolved/abstained recorded).
+  claimed_by            TEXT,
+  claimed_until         TEXT
+);
+
+CREATE INDEX idx_auto_resolutions_review_state ON escalation_auto_resolutions(review_state, created_at);
+CREATE INDEX idx_auto_resolutions_subject ON escalation_auto_resolutions(subject_key);
+-- The claim/lease fence: at most ONE open (unfinalised, `outcome='claimed'`) claim per user task, so
+-- two overlapping steward ticks can never both act on the same escalation. Final rows
+-- (`resolved`/`abstained`) are excluded so a re-escalation of the SAME task can be recorded afresh.
+CREATE UNIQUE INDEX ux_auto_resolutions_open_claim ON escalation_auto_resolutions(user_task_key) WHERE outcome = 'claimed';
+CREATE INDEX idx_auto_resolutions_task ON escalation_auto_resolutions(user_task_key);
+
+-- The Auto-resolutions page read model (ADR 0042): projects each FINAL record (resolved/abstained —
+-- never an in-flight `claimed` placeholder) with a derived `pending_review` flag (1 iff still
+-- `pending`) for the row-action `showWhenField` gate, which reads JS truthiness. Derivation over
+-- duplication: the grid binds this VIEW, never the base table.
+CREATE VIEW escalation_auto_resolutions__read_model AS
+SELECT
+  id,
+  user_task_key,
+  escalation_kind,
+  element_id,
+  subject_type,
+  subject_key,
+  subject_url,
+  process_instance_key,
+  question,
+  options,
+  outcome,
+  submitted_variables,
+  rationale,
+  evidence,
+  steward_instance_key,
+  agent_job_key,
+  worker,
+  model,
+  created_at,
+  review_state,
+  reviewed_by,
+  reviewed_at,
+  review_note,
+  CASE WHEN review_state = 'pending' THEN 1 ELSE 0 END AS pending_review
+FROM escalation_auto_resolutions
+WHERE outcome IN ('resolved', 'abstained');

package/db/migrations/121_delivery_graph_read_model_auto_resolve.sql

@@ -0,0 +1,54 @@
+-- Re-create the `delivery_graph_read_model` VIEW so it re-exports the base column added by
+-- 120_escalation_auto_resolutions.sql (`auto_resolve_escalations`). The read-model VIEW must pass
+-- through EVERY base `delivery_graph_runs` column (the static pages↔schema contract guard +
+-- app/deliveryGraphReadModel.test.ts DRIFT GUARD assert it), so adding a base column obliges a fresh
+-- VIEW definition — 087/096 are immutable and cannot be edited in place.
+--
+-- Every DERIVED column below is emitted VERBATIM from the ONE declaration in
+-- app/deliveryGraphReadModel.ts (`deliveryGraphReadModel.sqlSelectFor(col, { baseAlias: "dg" })`) —
+-- the same closed-DSL AST that drives the runtime TS via `fnFor`, so the two lowerings cannot
+-- diverge. This file is a mechanical re-emission of 096 with the one new base pass-through added;
+-- the derived `stage`/`stage_state`/`list_bucket`/`ack_open`/`park_label` expressions are unchanged.
+-- The drift guard now points at THIS migration (the latest VIEW definition).
+--
+-- Forward-only VIEW definition (DROP then CREATE), sourced off the managed
+-- `delivery_graph_runs__tracking` re-export of the base table so a terminated run classifies on
+-- ENGINE TRUTH. The runner wraps each file in its own transaction, so this file must NOT contain
+-- BEGIN/COMMIT. Numbered after 120.
+
+DROP VIEW IF EXISTS delivery_graph_read_model;
+DROP VIEW IF EXISTS delivery_graph_pr_counts;
+
+CREATE VIEW IF NOT EXISTS "delivery_graph_pr_counts" AS
+SELECT
+  "__urban_rollup_src"."root_request_key" AS "root_request_key",
+  SUM(CASE WHEN COALESCE(((NOT COALESCE(("__urban_rollup_src"."root_request_key" IS NULL), 0)) AND (NOT COALESCE(COALESCE((COALESCE(("__urban_rollup_src"."derived_status" = 'converged'), 0) OR COALESCE(("__urban_rollup_src"."derived_status" = 'merged'), 0) OR COALESCE(("__urban_rollup_src"."derived_status" = 'abandoned'), 0)), 0), 0))), 0) THEN 1 ELSE 0 END) AS "prs_in_flight"
+FROM "pull_requests__tracking" "__urban_rollup_src"
+GROUP BY "__urban_rollup_src"."root_request_key";
+
+CREATE VIEW delivery_graph_read_model AS
+SELECT
+  dg.run_key AS run_key,
+  COALESCE(dg.derived_status, dg.status) AS status,
+  dg.process_key AS process_key,
+  dg.process_definition_id AS process_definition_id,
+  dg.digest AS digest,
+  dg.side_effecting AS side_effecting,
+  dg.node_count AS node_count,
+  dg.human_node_count AS human_node_count,
+  dg.side_effect_count AS side_effect_count,
+  dg.title AS title,
+  dg.phase AS phase,
+  dg.phase_node_id AS phase_node_id,
+  dg.human_labels AS human_labels,
+  dg.created_at AS created_at,
+  dg.updated_at AS updated_at,
+  dg.acknowledged_at AS acknowledged_at,
+  dg.auto_resolve_escalations AS auto_resolve_escalations,
+  CASE WHEN COALESCE(("dg"."derived_status" = 'done'), 0) THEN 'Done' WHEN COALESCE((COALESCE(("dg"."derived_status" = 'failed'), 0) OR COALESCE(("dg"."derived_status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("dg"."derived_status" = 'awaiting-approval'), 0) THEN 'Requested' WHEN COALESCE((COALESCE("pc"."prs_in_flight", 0) > 0), 0) THEN 'Converging' ELSE 'Implementing' END AS stage,
+  CASE WHEN COALESCE(("dg"."derived_status" = 'done'), 0) THEN 'ok' WHEN COALESCE((COALESCE(("dg"."derived_status" = 'failed'), 0) OR COALESCE(("dg"."derived_status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("dg"."derived_status" = 'done'), 0) OR COALESCE(("dg"."derived_status" = 'failed'), 0) OR COALESCE(("dg"."derived_status" = 'abandoned'), 0)), 0) AND COALESCE(("dg"."acknowledged_at" = "dg"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("dg"."derived_status" = 'done'), 0) OR COALESCE(("dg"."derived_status" = 'failed'), 0) OR COALESCE(("dg"."derived_status" = 'abandoned'), 0)), 0) AND (NOT COALESCE(COALESCE(("dg"."acknowledged_at" = "dg"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open,
+  CASE WHEN dg.phase_node_id IS NOT NULL THEN dg.phase ELSE NULL END AS park_label
+FROM delivery_graph_runs__tracking dg
+LEFT JOIN delivery_graph_pr_counts pc ON dg.run_key = pc.root_request_key;

package/db/migrations/122_pull_requests_read_model_auto_resolve.sql

@@ -0,0 +1,56 @@
+-- Re-create the `pull_requests_read_model` VIEW so it re-exports the base column added by
+-- 120_escalation_auto_resolutions.sql (`auto_resolve_escalations`). The read-model VIEW must pass
+-- through EVERY base `pull_requests` column (the static pages↔schema contract guard +
+-- app/pullRequestReadModel.test.ts DRIFT GUARD assert it), so adding a base column obliges a fresh
+-- VIEW definition — 094/104/118 are immutable and cannot be edited in place.
+--
+-- Every DERIVED column below is emitted VERBATIM from the ONE declaration in
+-- app/pullRequestReadModel.ts (`pullRequestReadModel.sqlSelectFor(col, { baseAlias: "pr" })`) — the
+-- same closed-DSL AST that drives the runtime TS via `fnFor`, so the two lowerings cannot diverge.
+-- This file is a mechanical re-emission of 118 with the one new base pass-through added; the
+-- derived `list_bucket`/`ack_open` expressions are unchanged. The drift guard now points at THIS
+-- migration (the latest VIEW definition).
+--
+-- Forward-only VIEW definition (DROP then CREATE), sourced off the managed `pull_requests__tracking`
+-- re-export of the base table so a terminated PR classifies on ENGINE TRUTH. SQLite does not validate
+-- a view body at CREATE time. The runner wraps each file in its own transaction, so this file must
+-- NOT contain BEGIN/COMMIT. Numbered after 121.
+
+DROP VIEW IF EXISTS pull_requests_read_model;
+
+CREATE VIEW pull_requests_read_model AS
+SELECT
+  pr.pr_key AS pr_key,
+  pr.repo AS repo,
+  pr.number AS number,
+  pr.url AS url,
+  pr.title AS title,
+  COALESCE(pr.derived_status, pr.status) AS status,
+  pr.current_round AS current_round,
+  pr.process_key AS process_key,
+  pr.waiting_since AS waiting_since,
+  pr.last_review_id AS last_review_id,
+  pr.outcome AS outcome,
+  pr.created_at AS created_at,
+  pr.updated_at AS updated_at,
+  pr.converged_at AS converged_at,
+  pr.merged_at AS merged_at,
+  pr.active_worker AS active_worker,
+  pr.lease_until AS lease_until,
+  pr.last_nudge_at AS last_nudge_at,
+  pr.fresh_head_run_head AS fresh_head_run_head,
+  pr.abandon_token AS abandon_token,
+  pr.incident_key AS incident_key,
+  pr.incident_message AS incident_message,
+  pr.last_round_head AS last_round_head,
+  pr.last_progress_job_key AS last_progress_job_key,
+  pr.last_progress_result AS last_progress_result,
+  pr.last_progress_agent_watermark AS last_progress_agent_watermark,
+  pr.churn_escalated_round AS churn_escalated_round,
+  pr.root_request_key AS root_request_key,
+  pr.epic_phase_label AS epic_phase_label,
+  pr.acknowledged_at AS acknowledged_at,
+  pr.auto_resolve_escalations AS auto_resolve_escalations,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND (NOT COALESCE(COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM pull_requests__tracking pr;

package/db/migrations/123_escalation_auto_resolutions_selected_option.sql

@@ -0,0 +1,47 @@
+-- Issue #889 review (Copilot "Previously missed"): the Auto-resolutions grid omitted the SELECTED
+-- option, so an operator could not see whether the steward chose retry/continue/etc. without decoding
+-- the raw submitted variables. Add a first-class `selected_option` column (the option value the steward
+-- actually selected, derived host-side by the record worker from the decision's own form variables) and
+-- re-create the read-model VIEW to expose it as a list column.
+--
+-- Expand-and-contract: the column is nullable (existing rows keep NULL — they predate the projection),
+-- and the VIEW is re-created forward-only (DROP then CREATE) to add the new pass-through. Migration 120
+-- is immutable and cannot be edited in place. Numbered after 122.
+
+ALTER TABLE escalation_auto_resolutions ADD COLUMN selected_option TEXT;
+
+DROP VIEW IF EXISTS escalation_auto_resolutions__read_model;
+CREATE VIEW escalation_auto_resolutions__read_model AS
+SELECT
+  id,
+  user_task_key,
+  escalation_kind,
+  element_id,
+  subject_type,
+  subject_key,
+  subject_url,
+  process_instance_key,
+  -- The cockpit "Agent" transcript link keys on `process_key` (the #833 invariant: every Agent →
+  -- cockpit link uses keyField `process_key`). The ANSWERING agent ran under `steward_instance_key`
+  -- (the steward process), NOT `process_instance_key` (the escalated SUBJECT's process), so project
+  -- the steward key under the canonical `process_key` name for that link (issue #889 review).
+  steward_instance_key AS process_key,
+  question,
+  options,
+  outcome,
+  submitted_variables,
+  selected_option,
+  rationale,
+  evidence,
+  steward_instance_key,
+  agent_job_key,
+  worker,
+  model,
+  created_at,
+  review_state,
+  reviewed_by,
+  reviewed_at,
+  review_note,
+  CASE WHEN review_state = 'pending' THEN 1 ELSE 0 END AS pending_review
+FROM escalation_auto_resolutions
+WHERE outcome IN ('resolved', 'abstained');

package/db/migrations/124_admitted_epics_auto_resolve.sql

@@ -0,0 +1,21 @@
+-- 124_admitted_epics_auto_resolve.sql — issue #889: carry the escalation-steward opt-in through the
+-- set/batch admission door (`startEpicSet`).
+--
+-- The single-issue door (`startPlanFanout`) already seeds `plans.auto_resolve_escalations` (added by
+-- 120) from the request body's `autoResolveEscalations`. The set/batch door dropped it: `startEpicSet`
+-- stages each admitted epic into `admitted_epics` and `lowerAdmittedSet` later reads that staging to
+-- call `startPlan` — but the staging row had no column for the flag, so every batch-admitted epic (and
+-- every child convergence/merge loop it spawns) stayed opted OUT even when the caller opted in. That
+-- contradicts the issue #889 contract that the opt-in reach "every initiation pathway".
+--
+-- Fix the class at the staging seam: persist the per-epic opt-in on the staged row so the lowering
+-- reads it back and forwards it to `startPlan`. Additive (nullable-free `NOT NULL DEFAULT 0`), so an
+-- existing install's already-staged rows read as opted-out (the safe default) and fresh admissions
+-- record the caller's choice. No read-model view selects from `admitted_epics`, so no VIEW re-emission
+-- is needed (unlike `pull_requests` — cf. 121/122).
+--
+-- Numbered 124: above this branch's highest committed prefix (123) and origin/main's (119), so a
+-- fan-out sibling forking at either point cannot collide. The runner wraps each file in its own
+-- transaction, so this file must NOT contain BEGIN/COMMIT.
+
+ALTER TABLE admitted_epics ADD COLUMN auto_resolve_escalations INTEGER NOT NULL DEFAULT 0;

package/docs/agent-guide.md

@@ -76,6 +76,7 @@ The body is flat. Fields:
 | `autoMerge` | boolean | **Positive per-request setting.** `false` = review only, stopping at `converged`, regardless of the global default; `true` = converge **then merge** when `NANO_PR_AUTO_MERGE` is enabled. |
 | `maxRounds` | integer | per-submit cap before escalating (clamped 1–100; default from `NANO_PR_MAX_ROUNDS`, 20). |
 | `dependsOn` | string[] | other `prKey`s that must land before this one merges (merge-loop barrier). |
+| `autoResolveEscalations` | boolean | **Opt in to the escalation steward** (issue #889). When `true`, this loop's open escalations become eligible for the steward to review and auto-resolve every 30 min (recorded reviewably in **Auto-resolutions**, §3). Default `false` — escalations stay human-only. |
 
 **Converge-only vs. converge-and-merge — choose deliberately:**
 
@@ -116,6 +117,12 @@ blank/absent base is rejected with a 400. Starting a
 plan is idempotent on the plan key; an already-running plan short-circuits. The
 response (202) echoes the `planKey` and engine `processKey`.
 
+Both epic (`startPlanFanout`) and feature (`startFeature`) accept the optional
+**`autoResolveEscalations`** boolean (issue #889, default `false`). When `true`, the run opts in to
+the escalation steward, and the opt-in **propagates to every child it spawns** — an epic's
+implementation tasks and each enrolled convergence/merge loop, a feature run's handed-off PR. Only
+escalations raised under opted-in work are eligible for the steward (§3).
+
 **Single issue, one PR (feature run, `startFeature`)** — no planning or fan-out. Same body and
 base-branch admission, plus `converge` (enrol the PR in §1) and `autoMerge`:
 
@@ -313,6 +320,37 @@ Guidance for the human you assist: read the escalation `question` or plan-review
 `findings` first, decide the smallest unblocking answer, and answer it precisely —
 the answer becomes the agent's next-round context.
 
+### The escalation steward (opt-in auto-resolution, issue #889)
+
+Escalations are **still for humans** — unless the work opted in. Each initiation
+pathway (§1, §2, §9) accepts `autoResolveEscalations` (default off). When a piece of
+work opts in, the **escalation steward** reviews its open escalations every 30 minutes
+(configurable via `NANO_ESCALATION_STEWARD_INTERVAL`; `NANO_ESCALATION_STEWARD=off`
+disables the loop entirely) and submits a recommended choice for each — keeping the
+fleet moving instead of parking for hours on a decision with a clear best option.
+
+The steward is deliberately conservative:
+
+- It only touches escalations on **opted-in** work, past a short minimum age (so a
+  human already answering wins), and never a human-only / irreversible / credential
+  kind (merge approval, a permission prompt, a readiness gate, a blocked/conformance
+  ack, an *abandon*).
+- It **abstains** — leaving the escalation for a human — when the right choice is
+  unclear, and a **loop guard** abstains once a subject has been auto-resolved twice
+  and escalates again (the automatic answer isn't working).
+- Every resolution goes through the canonical `completeUserTask` door with **agent**
+  attribution (ADR 0046) — never recorded as a human decision.
+
+**Reviewing auto-resolutions.** Every resolution *and* abstention is written to a
+durable record and shown in the **Auto-resolutions** view (a pending-count badge sits
+in the nav). The default list shows `pending` records, newest first; open one to see
+the full question, the options offered, the submitted variables, the rationale and the
+evidence checked, plus links to the subject and the steward's transcript. From there
+you can **Dismiss** it (reviewed, no action) or **Intervene** (mark the record and
+record guidance for stepping in after the fact — reopening the completed user task is
+not required). Over MCP / curl, `listAutoResolutions` reads the records and
+`reviewAutoResolution` (`{ id, action: "dismiss" | "intervene", note? }`) reviews one.
+
 ---
 
 ## 4. The lifecycle & statuses (so you can reason about state)
@@ -694,15 +732,13 @@ curl -sS -X POST __BASE__/actions/compile-delivery-graph \
 ```
 
 - `200 { status:"ready", message, digest, preview, reviewUrl }` — the graph compiled and is
-  **staged for operator review**. `digest` is the content-address that NAMES the proposal (so
-  you can tell the operator exactly which one to dispatch); `preview` is `{ diagram,
-  sideEffects, humanNodes }` — `diagram` is a mermaid `flowchart` of the resolved graph,
-  `humanNodes[]` are the stop-points where it waits for a person, and `sideEffects[]` are the
-  `agent`/`connector` actions it **will** perform once an operator dispatches it; `reviewUrl`
-  is a **navigational** cockpit deep-link (a pointer only — **not** a dispatch handle). The
-  response carries **no run key, no token, and no process-instance key**: nothing you can
-  replay to start a run. Your role ends here — hand the operator the `digest` (or `reviewUrl`)
-  and ask them to preview and dispatch it.
+  **staged for operator review**. `digest` is the content-address that NAMES the proposal (tell the
+  operator exactly which one to dispatch); `preview` is `{ diagram, sideEffects, humanNodes }` —
+  `diagram` is a mermaid `flowchart` of the resolved graph, `humanNodes[]` are the stop-points where
+  it waits for a person, and `sideEffects[]` are the `agent`/`connector` actions it **will** perform
+  once dispatched; `reviewUrl` is a **navigational** cockpit deep-link (a pointer only — **not** a
+  dispatch handle). The response carries **no run key, token, or process-instance key**: nothing you
+  can replay to start a run. Hand the operator the `digest` (or `reviewUrl`) and ask them to dispatch.
 - `400 { ok:false, errors:[{ path, message }] }` — every error path-qualified
   (`nodes[2].kind`, `edges[1].from`, …) for unknown kind, dangling edge, a cycle, or an
   unresolvable `from` fact. Fix and recompile; nothing is staged.
@@ -711,13 +747,16 @@ curl -sS -X POST __BASE__/actions/compile-delivery-graph \
 `start` endpoint (Decision 5/7, issue #460). Dispatch is a human action: an operator opens
 the **Delivery Graphs** page in the cockpit, reviews the staged proposal's rendered preview
 (its diagram, the human stop-points, and the side effects a dispatch authorises), and clicks
-**Dispatch** on the one they approve. The operator clicking Dispatch **is** the approval — it
-is content-addressed to the exact digest they previewed, so it cannot be a replay of some
-other graph. Once dispatched, the graph deploys + runs engine-natively and registers as a run
-aggregate, so its current phase / parked node shows in the cockpit's **Active Delivery
-Graphs** grid (e.g. *"parked on human node: manual OTP publish"*). A `human` node parks on the
-**Tasks** inbox and is answered exactly as an escalation is (§3) — its completion emits any
-declared facts, which downstream edges bind.
+**Dispatch** on the one they approve. That click **is** the approval — content-addressed to the
+exact digest previewed, so it cannot replay some other graph. Once dispatched, the graph deploys +
+runs engine-natively and registers as a run aggregate, so its current phase / parked node shows in
+the cockpit's **Active Delivery Graphs** grid (e.g. *"parked on human node: manual OTP publish"*).
+A `human` node parks on the **Tasks** inbox and is answered exactly as an escalation is (§3) — its
+completion emits any declared facts, which downstream edges bind.
+
+The dispatch body accepts the optional **`autoResolveEscalations`** boolean (issue #889, default
+`false`): when `true`, the run opts in to the escalation steward (§3) — its `human` nodes, service-node
+escalation twins, and any `converge` connector's enrolled PR become eligible for auto-resolution.
 
 > **Completing a `wait` escalation proceeds *as not-ready* — it does NOT re-arm the gate.**
 > A `wait` node with `onTimeout: "escalate"` (the default) that elapses its bound parks a
@@ -892,7 +931,7 @@ Sometimes the thing you must wait for is not one PR but a **whole epic** — an
 time. The **`wait` kind `epic`** (issue #568) gates on that epic reaching **"fully merged"**
 (every opened slice landed), keyed by its durable **`planKey`** (`owner/repo#NN` — the epic
 issue), so *"start feature B once epic A has fully landed"* is an automated edge, not a human
-babysitting a `confirm` gate.
+babysitting a gate.
 
 ```json
 {
@@ -915,26 +954,24 @@ Semantics:
 
 - **`target` is the `planKey`** (`owner/repo#NN`, the epic issue) — the *stable business id*,
   not the engine `processInstanceKey` (`64200`), so a resubmit/replay still resolves.
-- **`match.epicState`** is `merged` (default) or its synonym `done` — both mean "every opened
-  slice landed". The gate reads the app's own **aggregate** (the lineage read-model over
-  `NANO_WORKFORCE_BASE_URL`), so it is level-triggered like `pr` (no missed edge).
-- **A failed/abandoned/mixed epic never reports merged**, so it never falsely releases the
-  gate; the **bounded** wait elapses and routes via **`onTimeout`** (`escalate`/`continue`) —
-  it does **not** hang.
+- **`match.epicState`** is `merged` (default) or `done` — "every opened slice landed". The gate reads
+  the app's own **aggregate** (the lineage read-model over `NANO_WORKFORCE_BASE_URL`), so it is
+  level-triggered like `pr` (no missed edge). A failed/abandoned/mixed epic never reports merged, so
+  it never falsely releases the gate — the **bounded** wait routes via **`onTimeout`**, never hanging.
 - **Set `poll.timeoutMs` to a realistic budget.** An epic reaching "fully merged" is a
-  multi-day, human-paced event, so the example gives it `poll: { everyMs: 300000, timeoutMs:
-  259200000 }` (re-probe every 5 minutes, budget 3 days). **Omitting `poll` inherits the
-  30-minute default** (§9.1) — the gate would escalate long before the epic lands. Because this
-  gate binds `prCount`, that escalation is **validated** (§9.2): it **re-parks** unless the
-  operator supplies a valid `prCount`, rather than silently releasing `start-b` as not-ready.
+  multi-day, human-paced event, so the example budgets 3 days (`poll: { everyMs: 300000, timeoutMs:
+  259200000 }`). **Omitting `poll` inherits the 30-minute default** (§9.1) — the gate would escalate
+  long before the epic lands. Because this gate binds `prCount`, that escalation is **validated**
+  (§9.2): it **re-parks** unless the operator supplies a valid `prCount`, rather than silently
+  releasing `start-b` as not-ready.
 - On a fully-merged match it binds **`prCount`** (how many slice PRs the epic landed) as an
   output fact, so a downstream node can consume it (parity with the `pr` kind's `mergedSha`).
 - **It also gates a single-PR *feature run*, not just a plan-fanout epic.** The gate resolves the
   lineage thread whose **`rootRequestKey`** matches `target` **regardless of the thread's `kind`**
   (`feature` | `epic` | `pr` | `delivery`), and `app/lineage.ts` lands a *feature* thread on
   `stage:"merged"` once its PR merges. So `wait[epic]` targeting a feature/epic **root issue**
-  observes that thread's aggregate frontier and releases on `stage:"merged" && active:false` either
-  way — see `getDeliveryGraphVocabulary` (the `epic` probe entry) for the structured contract.
+  releases on `stage:"merged" && active:false` either way — see `getDeliveryGraphVocabulary` (the
+  `epic` probe entry) for the structured contract.
 
 ---
 
@@ -956,6 +993,8 @@ until it does, only the curl door in the third column exists on the deployment:
 | Every PR in flight (§0/§5) | `listActivePrs` | `curl __BASE__/status` |
 | List open escalations (§3) | `listEscalations` *(projected by sibling #666; curl door until then)* | `curl __BASE__/../../tasks/api/tasks` (the answerable list — carries each `userTaskKey`); `/status` filtered with the jq recipe just below this table is only a quick *indicator* (it surfaces `openEscalation` as a question string, **no `userTaskKey`**, so you can't answer from it) |
 | Answer an escalation (§3) | `completeUserTask` (agent-assignee: `agentCompleteEscalation`) | `curl -X POST __BASE__/actions/complete-user-task` |
+| List auto-resolutions (§3) | `listAutoResolutions` | `curl __BASE__/auto-resolutions` |
+| Review an auto-resolution (dismiss / intervene) (§3) | `reviewAutoResolution` | `curl -X POST __BASE__/auto-resolutions/review` |
 | Cancel an instance (record-consistent) (§7) | `cancelInstance` *(projected by sibling #667; curl door until then)* | `curl -X POST __BASE__/../actions/cancel` *(the `/app/actions/cancel` door, outside `__BASE__`)* |
 | Publish a BPMN message (§7) | `postMessage` | `curl -X POST __BASE__/actions/message` |
 | The operator guide itself | `getAgentInstructions` (full) / `getAgentGuide(section?)` (addressable) | `curl __BASE__/agent` / `curl __BASE__/agent/guide` |

package/docs/agentic-cockpit.md

@@ -124,6 +124,40 @@ when a worker ages out past the liveness TTL. On (re)mount the presence family
 reconciles the store against live connections, so a worker that vanished while
 the app was down does not linger as a ghost row after a restart.
 
+### Job ownership: authoritative reconnect resync
+
+A worker's **jobs** are tracked by the explicit job-ownership claim registry
+(`app/agentic/claim-registry.ts`): a supervisor sends a `claim` frame when a
+worker picks up a job and a `release` when it finishes. Each frame names its
+owning `instance` explicitly, so one per-host supervisor connection can carry
+many workers' ownership.
+
+On a WS reconnect a supervisor re-`claim`s every active jobKey. Those re-claims
+are **additive** on their own — a claim that is not re-asserted is never dropped
+— so a `release` lost during a hub outage would leave the job shown as *working*
+until the worker exits entirely, forcing the supervisor to buffer every RELEASE
+without limit across the outage.
+
+To close that, a supervisor may end its resync with an **authoritative
+snapshot**: a `claim` frame carrying the full set of jobKeys the instance still
+owns (`{ instance, jobKeys: [...] }` — the empty **array** is allowed, meaning
+"this instance now owns nothing", but every **element** must be a non-empty
+string). The hub validates the frame as the snapshot-or-per-job
+union (a malformed snapshot is dropped before it touches the registry — the
+*presence* of `jobKeys`, not its validity, selects the snapshot variant, so a
+present-but-malformed `jobKeys` — a non-array, a non-string element, or an
+empty-string element — is rejected rather than laundered through the
+per-job path; an empty-string element can't masquerade as an "owns nothing"
+snapshot and clear real claims) and then
+**replaces** that instance's claims with the snapshot — dropping any it did not
+re-assert. The supervisor's
+view wins, because ownership is advisory, short-lived visibility it can always
+restate (it never gates a BPMN flow, ADR 0056). A jobKey that has moved to
+another instance is never blanked by the old instance's resync, and a supervisor
+that sends no snapshot keeps the old additive behaviour. This authoritative
+contract lets a hub client (nano-supervisor#63) **bound** its RELEASE buffer
+during an outage.
+
 ## What you will NOT find here (and where it lives)
 
 - **Demand×supply matrix, missing-agent-type reds, diversity-SLO lights** →

package/docs/mcp-runbook.md

@@ -115,6 +115,8 @@ CI runs) fails if the block below drifts from the source. Never hand-edit it; ed
   "listEscalations",
   "getLineage",
   "getPrHistory",
+  "listAutoResolutions",
+  "reviewAutoResolution",
   "urban_debug_search_process_instances",
   "urban_debug_search_element_instance_wait_states",
   "urban_debug_search_incidents",