@nanobpm/nano-workforce 0.206.3 → 0.207.0

package/app/service.ts

@@ -388,13 +388,16 @@ export interface PullRequest {
   // running agent curls (GET /app/api/hooks/abandon?token=…) to learn whether this run was cancelled before
   // it performs a side effect. Minted at submit, reused across the convergence + merge instances.
   abandon_token: string | null;
-  // Technical-incident surfacing (017_pr_incident.sql, issue #94), written by the poller's
-  // `pollIncidents` pass. `incident_key` is the engine incidentKey of the ACTIVE incident parking
-  // this PR's instance and `incident_message` its errorMessage; both NULL when the instance has no
-  // active incident. Orthogonal to `status` — an incident is a cross-cutting liveness fault, not a
-  // workflow stage.
+  // Technical-incident surfacing (017_pr_incident.sql, issue #94; enriched 126, issue #931), written
+  // by the poller's `pollIncidents` pass. `incident_key` is the engine incidentKey of the ACTIVE
+  // incident parking this PR's instance, `incident_type` its errorType, `incident_message` its
+  // errorMessage and `incident_since` its creationTime; all NULL when the instance has no active
+  // incident. Orthogonal to `status` — an incident is a cross-cutting liveness fault, not a
+  // workflow stage. `/status` derives the `incident` overlay from these columns (see `activePrs`).
   incident_key: string | null;
+  incident_type: string | null;
   incident_message: string | null;
+  incident_since: string | null;
   // Lineage projection (037_lineage.sql, issue #245): the stable ORIGIN identity (the issue =
   // feature_key / plan_key) threaded onto this PR by `submitPr`, and passed as a `createInstance`
   // variable onto the convergence + merge instances so every descendant carries the root. For a
@@ -1057,6 +1060,40 @@ export interface MergePolicy {
   blockedBy: "env" | "human-approval" | null;
 }
 
+/** The status `/status` reports for a run whose instance is parked on an ACTIVE engine incident
+ * (issue #931). Derived at READ time from the mirrored `incident_*` columns — the base `status`
+ * workflow transient is never overwritten, so the overlay can never wedge the status machine and
+ * lifts the moment the incident clears. */
+export const INCIDENT_STATUS = "incident";
+
+/** The incident block every `/status` row carries (issue #931): the ACTIVE engine incident the
+ * poller mirrored onto the record, else null. `key` is the engine incidentKey (the handle the
+ * `retryIncident` action resolves), `type` the errorType (e.g. `JOB_NO_RETRIES`), `message` the
+ * errorMessage, `since` the incident's creationTime. */
+export interface StatusIncident {
+  key: string;
+  type: string | null;
+  message: string | null;
+  since: string | null;
+}
+
+/** Derive the `/status` incident block from a row's mirrored incident columns (issue #931). Null
+ * when the row carries no active incident. */
+function statusIncidentFor(row: {
+  incident_key: string | null;
+  incident_type: string | null;
+  incident_message: string | null;
+  incident_since: string | null;
+}): StatusIncident | null {
+  if (!row.incident_key) return null;
+  return {
+    key: row.incident_key,
+    type: row.incident_type ?? null,
+    message: row.incident_message ?? null,
+    since: row.incident_since ?? null,
+  };
+}
+
 /** A PR currently in flight, as reported by the status endpoint. */
 export interface ActivePr {
   prKey: string;
@@ -1081,6 +1118,9 @@ export interface ActivePr {
   /** The effective merge policy (issue #916): what the run intends (`requested`), what the
    * deployment allows (`enabled`), and what will actually happen (`effective`/`blockedBy`). */
   merge: MergePolicy;
+  /** The ACTIVE engine incident parking this PR's instance (issue #931), mirrored by the poller's
+   * `pollIncidents` pass; null when none. While set, `status` reads `incident`. */
+  incident: StatusIncident | null;
 }
 
 /** Every tracked PR not in a terminal state (converged/abandoned), newest-updated first. Backs
@@ -1135,23 +1175,30 @@ export async function activePrs(
       mergeByPr.set(p.pr_key, await mergePolicyFor(p.process_key ?? null, engine));
     }),
   );
-  return active.map((p) => ({
-    prKey: p.pr_key,
-    repo: p.repo,
-    number: p.number,
-    url: p.url,
-    title: p.title ?? null,
-    status: p.status,
-    round: p.current_round,
-    processKey: p.process_key ?? null,
-    waitingSince: p.waiting_since ?? null,
-    openEscalation: openEscByPr.get(p.pr_key) ?? null,
-    updatedAt: p.updated_at,
-    activeWorker: p.active_worker ?? null,
-    leaseUntil: p.lease_until ?? null,
-    autoResolveEscalations: p.auto_resolve_escalations === 1,
-    merge: mergeByPr.get(p.pr_key) ?? mergePolicyDefault(),
-  }));
+  return active.map((p) => {
+    // Issue #931: an ACTIVE engine incident parked on the loop's instance must be VISIBLE — the row
+    // kept reading `converging` for hours while nothing ran. Overlay the derived `incident` status
+    // (the base `status` column is never touched) and carry the mirrored incident block.
+    const incident = statusIncidentFor(p);
+    return {
+      prKey: p.pr_key,
+      repo: p.repo,
+      number: p.number,
+      url: p.url,
+      title: p.title ?? null,
+      status: incident ? INCIDENT_STATUS : p.status,
+      round: p.current_round,
+      processKey: p.process_key ?? null,
+      waitingSince: p.waiting_since ?? null,
+      openEscalation: openEscByPr.get(p.pr_key) ?? null,
+      updatedAt: p.updated_at,
+      activeWorker: p.active_worker ?? null,
+      leaseUntil: p.lease_until ?? null,
+      autoResolveEscalations: p.auto_resolve_escalations === 1,
+      merge: mergeByPr.get(p.pr_key) ?? mergePolicyDefault(),
+      incident,
+    };
+  });
 }
 
 /** The default merge policy when no instance variables are readable (mid-handoff row, engine
@@ -1225,6 +1272,9 @@ export interface ActiveDelivery {
    * eligible for steward auto-resolution. Derived from the durable `auto_resolve_escalations` flag,
    * never a clobbered process variable. Shown in `/status` per delivery. */
   autoResolveEscalations: boolean;
+  /** The ACTIVE engine incident parking this run's instance (issue #931), mirrored by the poller's
+   * `pollIncidents` pass; null when none. While set, `status` reads `incident`. */
+  incident: StatusIncident | null;
 }
 
 /** Every delivery-graph run not in a terminal state (done/failed/abandoned), newest-updated first.
@@ -1248,16 +1298,22 @@ export async function activeDeliveries(data: DataLayer): Promise<ActiveDelivery[
     if (openEscByRun.has(t.subject_key)) continue;
     openEscByRun.set(t.subject_key, toOpenEscalation(t));
   }
-  return active.map((r) => ({
-    runKey: r.run_key,
-    title: r.title ?? null,
-    status: r.status,
-    phase: r.phase ?? null,
-    processKey: r.process_key ?? null,
-    openEscalation: openEscByRun.get(r.run_key) ?? null,
-    updatedAt: r.updated_at,
-    autoResolveEscalations: r.auto_resolve_escalations === 1,
-  }));
+  return active.map((r) => {
+    // Issue #931: same incident overlay as the PR rows — a delivery run parked on an engine
+    // incident must not keep reading `running`.
+    const incident = statusIncidentFor(r);
+    return {
+      runKey: r.run_key,
+      title: r.title ?? null,
+      status: incident ? INCIDENT_STATUS : r.status,
+      phase: r.phase ?? null,
+      processKey: r.process_key ?? null,
+      openEscalation: openEscByRun.get(r.run_key) ?? null,
+      updatedAt: r.updated_at,
+      autoResolveEscalations: r.auto_resolve_escalations === 1,
+      incident,
+    };
+  });
 }
 
 /** One review-ready poll pass (SPEC §10): for every PR waiting on a review, fetch its GitHub
@@ -2351,30 +2407,88 @@ export async function pollJobActivationImpl(
 }
 
 /** The subset of a Camunda-8 `/v2/incidents/search` result item this app reads. `incidentKey` is
- * the unique incident id; `errorMessage` is the human-readable fault; `state` is the incident
- * lifecycle (`ACTIVE` while it parks the token, `RESOLVED` once cleared); `creationTime` orders
- * concurrent incidents. */
-interface IncidentSearchItem {
+ * the unique incident id; `errorType` the machine fault class (e.g. `JOB_NO_RETRIES`);
+ * `errorMessage` is the human-readable fault; `state` is the incident lifecycle (`ACTIVE` while it
+ * parks the token, `RESOLVED` once cleared); `creationTime` orders concurrent incidents and is
+ * surfaced as the incident's `since`. */
+export interface IncidentSearchItem {
   incidentKey?: string;
+  errorType?: string | null;
   errorMessage?: string | null;
   state?: string;
   creationTime?: string | null;
+  /** The job the incident sits on (a `JOB_NO_RETRIES` incident parks until that job carries
+   * retries again) — the handle the `retryIncident` action bumps. */
+  jobKey?: string;
+}
+
+/** The four mirrored incident columns every incident-watched aggregate carries (PRs since #94/#931,
+ * delivery-graph runs since #931). All-or-nothing: a row with no ACTIVE incident reads NULL on all
+ * four. */
+interface IncidentMirror {
+  incident_key: string | null;
+  incident_type: string | null;
+  incident_message: string | null;
+  incident_since: string | null;
 }
 
-/** Incident-surfacing poll pass (issue #94). A convergence or merge process instance can hit a
- * *technical* incident — an unhandled engine error that parks the token — and nothing on the PR
- * row reflected it: the grid kept showing the last workflow status (`converging`, `merging`, …)
- * while the run was actually dead in the water (a PR sat "converging" all day on an incident).
+/** Pick the ACTIVE incident to mirror for one instance: the OLDEST active one (the first thing that
+ * broke — a stable choice if the instance somehow parks more than one). Re-filters on state
+ * defensively in case the wire filter is ignored. An incident with no `creationTime` sorts *last*,
+ * so a missing timestamp can never masquerade as the oldest. Returns null when none is active. */
+export function oldestActiveIncident(items: IncidentSearchItem[] | undefined): IncidentSearchItem | null {
+  return (
+    (items ?? [])
+      .filter((i) => (i.state ?? "ACTIVE") === "ACTIVE")
+      .sort((a, b) => (a.creationTime ?? "\uffff").localeCompare(b.creationTime ?? "\uffff"))[0] ?? null
+  );
+}
+
+/** Query the engine for the OLDEST ACTIVE incident on one process instance. Returns the incident,
+ * `null` when the instance has no active incident, or `undefined` when the transport failed (the
+ * caller keeps the last-known mirror and retries next pass — a failed query must never clear a real
+ * incident nor invent one). */
+export async function fetchActiveIncident(
+  base: string,
+  headers: Record<string, string>,
+  processInstanceKey: string,
+): Promise<IncidentSearchItem | null | undefined> {
+  try {
+    const res = await fetch(`${base}/incidents/search`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        filter: { processInstanceKey, state: "ACTIVE" },
+        page: { limit: 20 },
+      }),
+    });
+    if (!res.ok) return undefined; // engine unhappy → unknown, retry next pass
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const body = (await res.json()) as { items?: IncidentSearchItem[] };
+    return oldestActiveIncident(body.items);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Incident-surfacing poll pass (issue #94; enriched and extended to delivery-graph runs in issue
+ * #931). A convergence, merge, or delivery-graph process instance can hit a *technical* incident —
+ * an unhandled engine error that parks the token — and nothing on the record row reflected it: the
+ * grid kept showing the last workflow status (`converging`, `merging`, `running`, …) while the run
+ * was actually dead in the water (a PR sat "converging" all day on an incident; on merlin two loops
+ * sat dead for 1.3h/5h before anyone found them via a hand-run engine query).
  *
- * This pass reads the engine's Camunda-8 `/v2/incidents/search` for each PR that still has a live
- * instance (has a `process_key`, non-terminal status) and mirrors an ACTIVE incident onto two
- * orthogonal columns — `incident_key` + `incident_message` — leaving `status` untouched. An
- * incident is a cross-cutting liveness fault, not a workflow stage, so it must not overload the
- * status machine. Clearing is idempotent: when the instance has no active incident (resolved, or
- * never had one) the columns are nulled, so an incident raised or resolved out-of-band converges
- * to the truth on the next pass. Best-effort transport: a failed query leaves the last-known
- * values untouched and the next pass retries. Updates (and bumps `updated_at`) only on an actual
- * change so a steady state doesn't churn the grid. */
+ * This pass reads the engine's Camunda-8 `/v2/incidents/search` for each tracked record that still
+ * has a live instance (has a `process_key`, non-terminal derived status) and mirrors an ACTIVE
+ * incident onto four orthogonal columns — `incident_key`, `incident_type`, `incident_message`,
+ * `incident_since` — leaving `status` untouched. An incident is a cross-cutting liveness fault, not
+ * a workflow stage, so it must not overload the status machine (`/status` derives the `incident`
+ * overlay at READ time — see `activePrs`/`activeDeliveries`). Clearing is idempotent: when the
+ * instance has no active incident (resolved, or never had one) the columns are nulled, so an
+ * incident raised or resolved out-of-band converges to the truth on the next pass. Best-effort
+ * transport: a failed query leaves the last-known values untouched and the next pass retries.
+ * Updates (and bumps `updated_at`) only on an actual change so a steady state doesn't churn the
+ * grid. */
 async function pollIncidents(
   data: DataLayer,
   restAddress: string,
@@ -2387,12 +2501,24 @@ async function pollIncidents(
 }
 
 /** Testable core of {@link pollIncidents}: given the normalised `base` URL and prepared auth
- * `headers`, reconcile every PR row against the engine's active incidents. Split out so tests can
- * exercise the reconciliation with a stubbed `fetch` without re-deriving transport wiring. */
+ * `headers`, reconcile every incident-watched record row (PRs and delivery-graph runs) against the
+ * engine's active incidents. Split out so tests can exercise the reconciliation with a stubbed
+ * `fetch` without re-deriving transport wiring. */
 export async function pollIncidentsImpl(
   data: DataLayer,
   base: string,
   headers: Record<string, string>,
+) {
+  await reconcilePrIncidents(data, base, headers);
+  await reconcileDeliveryIncidents(data, base, headers);
+}
+
+/** The PR half of {@link pollIncidentsImpl}: mirror the oldest ACTIVE incident of each live PR
+ * instance onto the PR row's four incident columns. */
+async function reconcilePrIncidents(
+  data: DataLayer,
+  base: string,
+  headers: Record<string, string>,
 ) {
   const all = await prsTracking(data).all();
   for (const pr of all) {
@@ -2404,58 +2530,83 @@ export async function pollIncidentsImpl(
     // instance. Reuses the canonical `TERMINAL_STATUSES` so incident logic can't drift from the rest
     // of the status machine. Writes stay on the base `prs`.
     if (!pr.process_key || TERMINAL_STATUSES.includes(pr.derived_status)) {
-      if (pr.incident_key || pr.incident_message) {
-        await prs(data).update(pr.pr_key, {
-          incident_key: null,
-          incident_message: null,
-          updated_at: now(),
-        });
-      }
+      await clearIncidentMirror(pr, (patch) => prs(data).update(pr.pr_key, patch));
       continue;
     }
 
-    let incidentKey: string | null = null;
-    let incidentMessage: string | null = null;
+    let active: IncidentSearchItem | null | undefined;
     try {
-      const res = await fetch(`${base}/incidents/search`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-          filter: { processInstanceKey: pr.process_key, state: "ACTIVE" },
-          page: { limit: 20 },
-        }),
-      });
-      if (!res.ok) continue; // engine unhappy → keep last-known, retry next pass
-      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-      const body = (await res.json()) as { items?: IncidentSearchItem[] };
-      // Surface the oldest ACTIVE incident (the first thing that broke — a stable choice if the
-      // instance somehow parks more than one). Re-filter on state defensively in case the wire
-      // filter is ignored. An incident with no `creationTime` sorts *last*, so a missing timestamp
-      // can never masquerade as the oldest.
-      const active = (body.items ?? [])
-        .filter((i) => (i.state ?? "ACTIVE") === "ACTIVE")
-        .sort((a, b) =>
-          (a.creationTime ?? "\uffff").localeCompare(b.creationTime ?? "\uffff")
-        )[0];
-      if (active) {
-        incidentKey = active.incidentKey ?? null;
-        incidentMessage = active.errorMessage ?? null;
-      }
+      active = await fetchActiveIncident(base, headers, pr.process_key);
     } catch (err) {
       console.error(`[poller] incidents ${pr.pr_key}: ${err}`);
       continue;
     }
+    if (active === undefined) continue; // transport unhappy → keep last-known, retry next pass
 
-    if (
-      incidentKey !== (pr.incident_key ?? null) ||
-      incidentMessage !== (pr.incident_message ?? null)
-    ) {
-      await prs(data).update(pr.pr_key, {
-        incident_key: incidentKey,
-        incident_message: incidentMessage,
-        updated_at: now(),
-      });
+    await writeIncidentMirror(pr, active, (patch) => prs(data).update(pr.pr_key, patch));
+  }
+}
+
+/** The delivery-graph half of {@link pollIncidentsImpl} (issue #931): a delivery RUN's instance
+ * parks on an incident exactly as a convergence loop does, and was just as invisible — `/status`
+ * kept reporting `running`. Mirror onto the run row's four incident columns. */
+async function reconcileDeliveryIncidents(
+  data: DataLayer,
+  base: string,
+  headers: Record<string, string>,
+) {
+  const terminal: readonly string[] = DELIVERY_GRAPH_TERMINAL_STATUSES;
+  const all = await deliveryGraphRunsTracking(data).all();
+  for (const run of all) {
+    if (!run.process_key || terminal.includes(run.derived_status)) {
+      await clearIncidentMirror(run, (patch) => deliveryGraphRuns(data).update(run.run_key, patch));
+      continue;
+    }
+
+    let active: IncidentSearchItem | null | undefined;
+    try {
+      active = await fetchActiveIncident(base, headers, run.process_key);
+    } catch (err) {
+      console.error(`[poller] incidents ${run.run_key}: ${err}`);
+      continue;
     }
+    if (active === undefined) continue;
+
+    await writeIncidentMirror(run, active, (patch) => deliveryGraphRuns(data).update(run.run_key, patch));
+  }
+}
+
+/** Null all four incident columns when any is set (a terminal / instance-less record must not keep
+ * a stale mirror). Shared by both reconcile halves so the clearing shape can never drift. */
+async function clearIncidentMirror(
+  row: IncidentMirror,
+  update: (patch: IncidentMirror & { updated_at: string }) => Promise<unknown>,
+) {
+  if (row.incident_key || row.incident_type || row.incident_message || row.incident_since) {
+    await update({ incident_key: null, incident_type: null, incident_message: null, incident_since: null, updated_at: now() });
+  }
+}
+
+/** Write the mirrored incident onto the row — or clear it when `active` is null — updating (and
+ * bumping `updated_at`) only on an actual change so a steady state doesn't churn the grid. */
+async function writeIncidentMirror(
+  row: IncidentMirror,
+  active: IncidentSearchItem | null,
+  update: (patch: IncidentMirror & { updated_at: string }) => Promise<unknown>,
+) {
+  const next: IncidentMirror = {
+    incident_key: active?.incidentKey ?? null,
+    incident_type: active?.errorType ?? null,
+    incident_message: active?.errorMessage ?? null,
+    incident_since: active?.creationTime ?? null,
+  };
+  if (
+    next.incident_key !== (row.incident_key ?? null) ||
+    next.incident_type !== (row.incident_type ?? null) ||
+    next.incident_message !== (row.incident_message ?? null) ||
+    next.incident_since !== (row.incident_since ?? null)
+  ) {
+    await update({ ...next, updated_at: now() });
   }
 }
 

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.206.3",
-  "gitSha": "f731dc60dc0cb7480b425e88d1d216b95d63a5c1",
-  "gitTag": "v0.206.3",
-  "builtAt": "2026-11-09T21:25:41.376Z"
+  "version": "0.207.0",
+  "gitSha": "e3955c8145a966a29806400872b7a9c362d1d992",
+  "gitTag": "v0.207.0",
+  "builtAt": "2026-11-09T23:52:15.727Z"
 }

package/db/migrations/126_pull_requests_incident_type_since.sql

@@ -0,0 +1,8 @@
+-- Incident enrichment (issue #931). The #94 mirror carried only `incident_key` + `incident_message`
+-- — enough to light a badge, not enough to answer "WHAT broke and SINCE WHEN" from the row, which is
+-- what an operator triaging a parked loop needs (the merlin incidents were `JOB_NO_RETRIES` idle
+-- timeouts; the errorType is the tell). `incident_type` is the engine incident's `errorType`;
+-- `incident_since` its `creationTime` (ISO). Both NULL when the instance has no active incident —
+-- the poller's `pollIncidents` pass clears all four columns together, idempotently.
+ALTER TABLE pull_requests ADD COLUMN incident_type TEXT;   -- the active incident's errorType (e.g. JOB_NO_RETRIES); NULL when none
+ALTER TABLE pull_requests ADD COLUMN incident_since TEXT;  -- the active incident's creationTime (ISO); NULL when none

package/db/migrations/127_delivery_graph_run_incidents.sql

@@ -0,0 +1,60 @@
+-- Delivery-graph incident mirroring (issue #931). A delivery-graph RUN's engine instance can park
+-- on a technical incident exactly as a convergence loop can — and was just as invisible: `/status`
+-- kept reporting `running` while nothing moved. These four columns are the delivery-side twin of
+-- the PR incident mirror (017 + 126), written by the SAME `pollIncidents` pass and surfaced on the
+-- `/status` delivery rows. All NULL when the run's instance has no active incident.
+ALTER TABLE delivery_graph_runs ADD COLUMN incident_key TEXT;      -- engine incidentKey of the active incident parking this run's instance; NULL when none
+ALTER TABLE delivery_graph_runs ADD COLUMN incident_type TEXT;     -- the active incident's errorType; NULL when none
+ALTER TABLE delivery_graph_runs ADD COLUMN incident_message TEXT;  -- the active incident's errorMessage; NULL when none
+ALTER TABLE delivery_graph_runs ADD COLUMN incident_since TEXT;    -- the active incident's creationTime (ISO); NULL when none
+
+-- Mirror the new columns through the `delivery_units` aggregate (ADR 0006) so the
+-- `delivery_graph_runs__units` compat VIEW stays row-for-row with the base table (as 120 did for
+-- `auto_resolve_escalations`): add the columns, then re-create the delivery-graph sync triggers and
+-- the compat VIEW with them.
+ALTER TABLE delivery_units ADD COLUMN incident_key TEXT;
+ALTER TABLE delivery_units ADD COLUMN incident_type TEXT;
+ALTER TABLE delivery_units ADD COLUMN incident_message TEXT;
+ALTER TABLE delivery_units ADD COLUMN incident_since TEXT;
+
+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, incident_key, incident_type, incident_message, incident_since, 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.incident_key, NEW.incident_type, NEW.incident_message, NEW.incident_since, 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, incident_key, incident_type, incident_message, incident_since, 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.incident_key, NEW.incident_type, NEW.incident_message, NEW.incident_since, NEW.created_at, NEW.updated_at);
+END;
+
+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,
+  du.incident_key AS incident_key,
+  du.incident_type AS incident_type,
+  du.incident_message AS incident_message,
+  du.incident_since AS incident_since
+FROM delivery_units du
+WHERE du.kind = 'delivery-graph';
+

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/agent-guide.md

@@ -359,7 +359,10 @@ instruction to the agent's prompt automatically when the node declares `emits`.
 omits the fact, the `default` branch is taken.
 
 **Result statuses are added automatically. Don't write them into your prompt.** Every agent
-node's prompt gets the allowed terminal statuses (`done` / `opened` / `skipped`). A completion
+node's prompt gets the allowed terminal statuses (`done` / `opened` / `skipped`, plus the
+unambiguous affirmative-completion aliases `completed` / `succeeded` / `success` — issue #932:
+a fully-delivered node reporting one of those is a terminal success, never a contract
+violation). A completion
 moves on only with one of those statuses and every required emit present. Anything else parks
 the run on a human `__contract` escalation — **except** an absent/null `status`, which a legacy
 worker that populates its required emits may still advance with (the status contract binds only