@nanobpm/nano-workforce 0.206.4 → 0.208.0

package/db/migrations/128_pull_requests_read_model_incidents.sql

@@ -0,0 +1,58 @@
+-- Re-create the `pull_requests_read_model` VIEW so it re-exports the base column added by
+-- 126_pull_requests_incident_type_since.sql (`incident_type`/`incident_since`). 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 base columns obliges a fresh
+-- VIEW definition — 094/104/118/122 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 122 with the two new base pass-throughs 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 127.
+
+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_type AS incident_type,
+  pr.incident_since AS incident_since,
+  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/129_delivery_graph_read_model_incidents.sql

@@ -0,0 +1,58 @@
+-- Re-create the `delivery_graph_read_model` VIEW so it re-exports the base column added by
+-- 127_delivery_graph_run_incidents.sql (the four `incident_*` mirror columns). 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 base columns obliges a fresh
+-- VIEW definition — 087/096/121 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 121 with the four new base pass-throughs 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 128.
+
+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,
+  dg.incident_key AS incident_key,
+  dg.incident_type AS incident_type,
+  dg.incident_message AS incident_message,
+  dg.incident_since AS incident_since,
+  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/docs/mcp-runbook.md

@@ -214,8 +214,8 @@ acceptable. When it **is set**, the guard is not mutation-only: it also covers
 reads, so read endpoints like `GET /app/api/agent` and `GET /app/api/version`
 return `401` without the `x-hook-secret` header, just as guarded mutations do. It
 is not blanket, though — a few doors stay intentionally unguarded even when the
-secret is set (e.g. the declarative Save-to-library page action, which
-structurally cannot attach the header). Put it in the server entry's
+secret is set (e.g. the declarative Save-to-library and Retry-incident page actions,
+which structurally cannot attach the header). Put it in the server entry's
 `headers`, never in chat. For a remote fleet,
 `NANO_WORKFORCE_BASE_URL` reachability rules apply unchanged. The rest of the app's
 HTTP surface follows the `network.bind` manifest setting, but the runtime-served

package/nano.app.json

@@ -144,6 +144,14 @@
       "taskType": "pr.merge",
       "handler": "workers/merge/worker.ts"
     },
+    {
+      "taskType": "pr.request-review",
+      "handler": "workers/request-review/worker.ts"
+    },
+    {
+      "taskType": "pr.reconverge",
+      "handler": "workers/reconverge/worker.ts"
+    },
     {
       "taskType": "pr.mark-merged",
       "handler": "workers/mark-merged/worker.ts"

package/openapi.yaml

@@ -93,6 +93,7 @@ components:
         - leaseUntil
         - autoResolveEscalations
         - merge
+        - incident
       properties:
         prKey:
           type: string
@@ -107,6 +108,13 @@ components:
           nullable: true
         status:
           type: string
+          description: >-
+            The run's workflow status — `converging`, `waiting_review`, `escalated`, `waiting_deps`,
+            `waiting_merge`, `queued`, `merging` — OVERLAID with `incident` (issue #931) while the
+            run's instance is parked on an ACTIVE engine incident, so a dead-in-the-water loop can
+            never again read as a healthy `converging`. The overlay is derived at read time from the
+            mirrored `incident` block; the base workflow status resumes the moment the incident
+            clears.
         round:
           type: integer
         processKey:
@@ -189,6 +197,37 @@ components:
               nullable: true
               enum: ["env", "human-approval", null]
               description: Why a requested merge will not proceed; null when effective or converge-only.
+        incident:
+          type: object
+          nullable: true
+          additionalProperties: false
+          description: >-
+            The ACTIVE engine incident parking this PR's instance (issue #931), mirrored by the
+            poller's incident pass, else null. While set, `status` reads `incident`. `key` is the
+            engine incidentKey; `type` the errorType (e.g. `JOB_NO_RETRIES`); `message` the
+            errorMessage; `since` the incident's creationTime. The operator remedy is the
+            `retryIncident` action (the Convergence/Home grids' "Retry incident" row action).
+          required:
+            - key
+            - type
+            - message
+            - since
+          properties:
+            key:
+              type: string
+              description: The engine incidentKey of the ACTIVE incident.
+            type:
+              type: string
+              nullable: true
+              description: The incident's errorType (e.g. JOB_NO_RETRIES).
+            message:
+              type: string
+              nullable: true
+              description: The incident's errorMessage.
+            since:
+              type: string
+              nullable: true
+              description: The incident's creationTime (ISO).
     ActivePrList:
       type: object
       required:
@@ -243,6 +282,7 @@ components:
         - openEscalation
         - updatedAt
         - autoResolveEscalations
+        - incident
       properties:
         runKey:
           type: string
@@ -251,6 +291,10 @@ components:
           nullable: true
         status:
           type: string
+          description: >-
+            The run's workflow status (`running`, …) OVERLAID with `incident` (issue #931) while the
+            run's instance is parked on an ACTIVE engine incident — the same read-time overlay the
+            PR rows carry.
         phase:
           type: string
           nullable: true
@@ -285,6 +329,35 @@ components:
             Whether this delivery run opted into automatic escalation resolution by the escalation
             steward (issue #889). Derived from the durable `auto_resolve_escalations` flag, never a
             clobbered process variable.
+        incident:
+          type: object
+          nullable: true
+          additionalProperties: false
+          description: >-
+            The ACTIVE engine incident parking this run's instance (issue #931), mirrored by the
+            poller's incident pass, else null. While set, `status` reads `incident`. Same shape as
+            the PR rows' `incident` block.
+          required:
+            - key
+            - type
+            - message
+            - since
+          properties:
+            key:
+              type: string
+              description: The engine incidentKey of the ACTIVE incident.
+            type:
+              type: string
+              nullable: true
+              description: The incident's errorType (e.g. JOB_NO_RETRIES).
+            message:
+              type: string
+              nullable: true
+              description: The incident's errorMessage.
+            since:
+              type: string
+              nullable: true
+              description: The incident's creationTime (ISO).
     Escalation:
       type: object
       description: >-
@@ -351,6 +424,59 @@ components:
             The denormalised decision/form context the Tasks inbox renders for this task (the same
             question + subject the deployed form is seeded with). The typed answer fields an agent
             submits depend on `kind` (e.g. a PR `{ answer }`, a plan-review `{ directive, notes }`).
+    IncidentList:
+      type: object
+      additionalProperties: false
+      required: [count, incidents]
+      properties:
+        count:
+          type: integer
+        incidents:
+          type: array
+          items:
+            $ref: "#/components/schemas/IncidentEntry"
+    IncidentEntry:
+      type: object
+      additionalProperties: false
+      required: [kind, subjectKey, processInstanceKey, incidentKey, type, message, since, retry]
+      properties:
+        kind:
+          type: string
+          enum: [pr, delivery]
+        subjectKey:
+          type: string
+          description: The PR key (owner/repo#N) or delivery-graph run key.
+        processInstanceKey:
+          type: string
+          nullable: true
+        incidentKey:
+          type: string
+        type:
+          type: string
+          nullable: true
+          description: The engine errorType (e.g. JOB_NO_RETRIES).
+        message:
+          type: string
+          nullable: true
+        since:
+          type: string
+          nullable: true
+          description: The incident's creationTime.
+        retry:
+          type: object
+          additionalProperties: false
+          required: [path, body]
+          properties:
+            path:
+              type: string
+            body:
+              type: object
+              additionalProperties: false
+              required: [processInstanceKey]
+              properties:
+                processInstanceKey:
+                  type: string
+                  nullable: true
     EscalationList:
       type: object
       additionalProperties: false
@@ -4099,6 +4225,38 @@ components:
         error:
           type: string
           description: Present on a non-terminal failure — the reason the cancel did not take, the tracked record was not reconciled, or no tracked record owns the key.
+    RetryIncidentIntent:
+      type: object
+      additionalProperties: false
+      required:
+        - processInstanceKey
+      properties:
+        processInstanceKey:
+          type: string
+          description: The engine process-instance key of the incident-parked run to retry (the `process_key` column surfaced by `listActivePrs`/the Convergence page). Must be a string — engine keys are 64-bit and a numeric value risks silent JS precision loss.
+    RetryIncidentResult:
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+        - processInstanceKey
+      properties:
+        ok:
+          type: boolean
+          description: True when the engine confirmed the incident resolution (the failed job was given a retry first, so a JOB_NO_RETRIES incident does not re-incident instantly) and the record row's mirrored incident columns were cleared. False ⇒ a 4xx/5xx body carrying the reason in `error`.
+        processInstanceKey:
+          type: string
+          description: The instance key, echoed back.
+        incidentKey:
+          type: string
+          description: The engine incidentKey that was resolved (the oldest ACTIVE incident on the instance — the same one the poller mirrors onto the record row).
+        jobKey:
+          type: string
+          nullable: true
+          description: The failed job whose retries were bumped to 1 before the resolution; null when the incident carried no job handle (a non-job fault — resolution alone unsticks it).
+        error:
+          type: string
+          description: Present on a failure — the reason the retry did not take (no tracked record owns the key, no active incident on the instance, or the engine refused the retries bump / resolution).
 # ─────────────────────────────────────────────────────────────────────────────────────────────
 # MCP tool-schema convention (epic nano-workforce#605, S0 — the shared invariant every later slice
 # inherits). The Urban runtime projects THIS document into MCP tools (ADR 0067 — zero MCP server
@@ -4199,6 +4357,61 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/incident/retry:
+    post:
+      operationId: retryIncident
+      # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): operator-only remediation door. Retrying an
+      # incident-parked run is the human unstick action on the Convergence/Home grids (the incident
+      # row's "Retry incident" button); agents diagnose through the read surface and escalate, they
+      # do not force engine retries.
+      x-mcp:
+        exclude: true
+      summary: "Retry an incident-parked run the app-owned way (issue #931): bump the failed job's retries AND resolve the ACTIVE engine incident on the run's instance, then clear the incident mirror off the record row. This is the operator remedy for a loop that shows `status: \"incident\"` — previously a hand-run engine-REST sequence (`PATCH /v2/jobs/<k> {changeset:{retries:1}}` + `POST /v2/incidents/<k>/resolution`)."
+      # Intentionally NO hookSecret security: the declarative "Retry incident" page action cannot
+      # attach x-hook-secret (see operations/retryIncident.ts).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RetryIncidentIntent"
+      responses:
+        "200":
+          description: The incident was resolved (the failed job was given a retry first) and the record row's incident mirror cleared — the `/status` row leaves `incident` immediately.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetryIncidentResult"
+        "400":
+          description: Missing/invalid `processInstanceKey`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "404":
+          description: No tracked record owns the key (a clean no-op — the engine is never touched).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetryIncidentResult"
+        "409":
+          description: The instance carries no ACTIVE incident — nothing to retry (it may already be resolved).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetryIncidentResult"
+        "502":
+          description: "The remedy did not fully take: the engine's incident search was unavailable, the job retries bump failed (the incident is left ACTIVE — never a half-applied remedy), or the resolution itself failed."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetryIncidentResult"
+        "503":
+          description: The app has no data source configured, so the record cannot be resolved.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /auto-resolutions:
     get:
       operationId: listAutoResolutions
@@ -4302,6 +4515,31 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /incidents:
+    get:
+      operationId: listIncidents
+      summary: List every tracked run parked on an ACTIVE engine incident, oldest first.
+      description: >-
+        Sibling of `/escalations` for technical liveness faults (issue #931). Read-only projection
+        over the incident mirror the poller writes onto PR and delivery-graph rows (the same source
+        as the `/status` `incident` overlay). Each entry carries the operator remedy: POST
+        `retry.path` (the `retryIncident` action) with `retry.body`.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The active incidents.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IncidentList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /escalations:
     get:
       operationId: listEscalations

package/operations/listIncidents.test.ts

@@ -0,0 +1,70 @@
+// Tests for GET /app/api/incidents operation `listIncidents` (issue #931): the incident projection
+// lists every mirrored ACTIVE incident (PR + delivery-graph rows) with its retry remedy, oldest first.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./listIncidents.ts";
+
+function memApp(stores: Record<string, Record<string, unknown>[]>): AppApi {
+  const app = {
+    data: { table: (n: string) => ({ all: async () => [...(stores[n] ?? [])] }) },
+    log: noopLog(),
+    // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  } as any as AppApi;
+  return app;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+async function call(app: AppApi): Promise<any> {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  return (await handler({ req: { headers: new Headers() } as any, params: {}, query: {}, body: undefined } as any, app)) as any;
+}
+
+test("listIncidents: lists PR + delivery incidents oldest-first with the retry remedy; skips healthy rows", async () => {
+  const app = memApp({
+    pull_requests: [
+      { pr_key: "o/r#1", process_key: "11", incident_key: null },
+      {
+        pr_key: "o/r#2",
+        process_key: "22",
+        incident_key: "i2",
+        incident_type: "JOB_NO_RETRIES",
+        incident_message: "idle",
+        incident_since: "2026-11-09T10:00:00Z",
+      },
+    ],
+    delivery_graph_runs: [
+      {
+        run_key: "run-a",
+        process_key: "33",
+        incident_key: "i3",
+        incident_type: "IO_MAPPING_ERROR",
+        incident_message: "boom",
+        incident_since: "2026-11-09T09:00:00Z",
+      },
+    ],
+  });
+  const res = await call(app);
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 2);
+  assertEquals(
+    res.body.incidents.map((i: { kind: string; subjectKey: string }) => `${i.kind}:${i.subjectKey}`),
+    ["delivery:run-a", "pr:o/r#2"],
+  );
+  assertEquals(res.body.incidents[1], {
+    kind: "pr",
+    subjectKey: "o/r#2",
+    processInstanceKey: "22",
+    incidentKey: "i2",
+    type: "JOB_NO_RETRIES",
+    message: "idle",
+    since: "2026-11-09T10:00:00Z",
+    retry: { path: "/app/api/actions/incident/retry", body: { processInstanceKey: "22" } },
+  });
+});
+
+test("listIncidents: empty when nothing is parked", async () => {
+  const res = await call(memApp({ pull_requests: [{ pr_key: "x", incident_key: null }] }));
+  assertEquals(res.body, { count: 0, incidents: [] });
+});

package/operations/listIncidents.ts

@@ -0,0 +1,78 @@
+// GET /app/api/incidents → operationId `listIncidents` (issue #931). The sibling of `/escalations`
+// for TECHNICAL liveness faults: every tracked run (PR convergence/merge loop, delivery-graph run)
+// whose engine instance is parked on an ACTIVE incident, with the `processInstanceKey` the operator
+// remedy `retryIncident` (POST /actions/incident/retry) takes.
+//
+// Read-only projection over the ONE incident mirror the poller's `pollIncidents` pass writes onto
+// the record rows (`incident_key/type/message/since`) — NOT a second engine query, so it can never
+// disagree with the `/status` rows' `incident` overlay. Oldest incident first (longest-dead first).
+//
+// The optional shared-secret guard stays HERE (mirrors `listEscalations`).
+import type { DataLayer } from "@nanobpm/urban";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export interface IncidentView {
+  kind: "pr" | "delivery";
+  subjectKey: string;
+  processInstanceKey: string | null;
+  incidentKey: string;
+  type: string | null;
+  message: string | null;
+  since: string | null;
+  retry: { path: string; body: { processInstanceKey: string | null } };
+}
+
+interface MirrorRow {
+  process_key?: string | null;
+  incident_key?: string | null;
+  incident_type?: string | null;
+  incident_message?: string | null;
+  incident_since?: string | null;
+}
+
+const RETRY_PATH = "/app/api/actions/incident/retry";
+
+function toView(kind: IncidentView["kind"], subjectKey: string, r: MirrorRow): IncidentView | null {
+  if (!r.incident_key) return null;
+  const processInstanceKey = r.process_key ?? null;
+  return {
+    kind,
+    subjectKey,
+    processInstanceKey,
+    incidentKey: r.incident_key,
+    type: r.incident_type ?? null,
+    message: r.incident_message ?? null,
+    since: r.incident_since ?? null,
+    retry: { path: RETRY_PATH, body: { processInstanceKey } },
+  };
+}
+
+/** Every mirrored ACTIVE incident across the incident-watched aggregates, oldest first (a missing
+ * `since` sorts last). */
+export async function activeIncidents(data: DataLayer): Promise<IncidentView[]> {
+  const out: IncidentView[] = [];
+  const prRows = await data.table<MirrorRow & { pr_key: string }>("pull_requests", "pr_key").all();
+  for (const r of prRows) {
+    const v = toView("pr", r.pr_key, r);
+    if (v) out.push(v);
+  }
+  const runRows = await data.table<MirrorRow & { run_key: string }>("delivery_graph_runs", "run_key").all();
+  for (const r of runRows) {
+    const v = toView("delivery", r.run_key, r);
+    if (v) out.push(v);
+  }
+  return out.sort((a, b) => (a.since ?? "\uffff").localeCompare(b.since ?? "\uffff"));
+}
+
+export default defineOperation("listIncidents", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listIncidents rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  if (!app.data) return { status: 200, body: { count: 0, incidents: [] } };
+  const incidents = await activeIncidents(app.data);
+  return { status: 200, body: { count: incidents.length, incidents } };
+});