@nanobpm/nano-workforce 0.115.0 → 0.117.0

package/app/deliveryGraphRun.ts

@@ -0,0 +1,323 @@
+// app/deliveryGraphRun.ts — the `startDeliveryGraph` run AGGREGATE (ADR 0005 Decision 7, slice S5).
+//
+// The dispatch door (`operations/startDeliveryGraph.ts`) turns an agent-authored `DeliveryGraph` into
+// a RUNNING engine-native process (via the S4 runner) — but because these graphs merge PRs and publish
+// packages, dispatch is GATED on an approval of the rendered preview and must be idempotent. This
+// module is the durable aggregate that makes both properties true and gives the cockpit a row to show
+// WHERE a run is parked:
+//
+//   • the idempotency fence — a run is keyed by `run_key` (a caller `idempotencyKey`, else the graph's
+//     content digest). A re-POST collapses onto the same row, so an in-flight run short-circuits
+//     instead of double-launching (mirrors `plans`' `alreadyRunning`).
+//   • the approval token — `digest` is the content-address a side-effecting graph must present as its
+//     `approvalToken` to dispatch. Persisted so a second POST re-derives + re-checks it.
+//   • the derived parked-node phase — `phase`/`phase_node_id` is the display-only "where is it parked"
+//     projection `pollDeliveryGraphPhase` recomputes from engine truth (the running instance's open
+//     user tasks), generalising the `epic_phase` derived-phase machinery to a DYNAMIC compiled process.
+//
+// The pure helpers here (`computeRunKey`, `isDeliveryGraphApproved`, `buildHumanLabels`,
+// `deriveDeliveryPhase`) are engine/DB-free so they unit-test in isolation; the door and the poller
+// supply the I/O.
+
+import type { DataLayer, ProcessInstanceState } from "@nanobpm/urban";
+import type { CompileDeliveryGraphResult } from "../nano-generated/api-io.d.ts";
+import { isUniqueConstraintFence } from "./dbFence.ts";
+import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
+
+const now = () => new Date().toISOString();
+
+/** One `startDeliveryGraph` run — the durable row. `side_effecting` is a SQLite boolean (0/1). */
+export interface DeliveryGraphRun {
+  run_key: string;
+  process_key: string | null;
+  process_definition_id: string | null;
+  digest: string;
+  status: DeliveryGraphRunStatus;
+  side_effecting: number;
+  node_count: number;
+  human_node_count: number;
+  side_effect_count: number;
+  title: string | null;
+  phase: string | null;
+  phase_node_id: string | null;
+  human_labels: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/** The run lifecycle. `awaiting-approval` = a side-effecting graph parked at the approval gate (no
+ * instance started); `running` = dispatched to the engine; `done`/`failed`/`abandoned` = terminal. */
+export const DELIVERY_GRAPH_RUN_STATUSES = [
+  "awaiting-approval",
+  "running",
+  "done",
+  "failed",
+  "abandoned",
+] as const;
+export type DeliveryGraphRunStatus = typeof DELIVERY_GRAPH_RUN_STATUSES[number];
+
+/** The ACTIVE statuses — a run in one of these is still in flight and shows in the cockpit's active
+ * grid (`pages/overview.page.json`'s "Active Delivery Graphs" filter). Note this is the DISPLAY set,
+ * broader than the instanceTracking binding: only `running` is backed by a live engine instance
+ * (non-null `process_key`), so ONLY `running` is instance-tracked (nano.app.json). A parked
+ * `awaiting-approval` run has no instance (`process_key` NULL) — it is shown here but not reconciled
+ * by the `process_key`-keyed reconciler. */
+export const DELIVERY_GRAPH_ACTIVE_STATUSES: readonly DeliveryGraphRunStatus[] = [
+  "awaiting-approval",
+  "running",
+];
+
+/** The terminal statuses — a run in one of these is done and drops out of the active grid. Mirrors
+ * `PLAN_TERMINAL_STATUSES`; the idempotency short-circuit only fires for a NON-terminal run. */
+export const DELIVERY_GRAPH_TERMINAL_STATUSES: readonly DeliveryGraphRunStatus[] = [
+  "done",
+  "failed",
+  "abandoned",
+];
+
+/** The display phases for a run's derived projection. `Parked on human node: <label>` is built at
+ * derivation time from the parked user task's label, so it is not a member here. */
+export const DELIVERY_PHASE = {
+  AWAITING_APPROVAL: "Awaiting approval",
+  RUNNING: "Running",
+  COMPLETED: "Completed",
+  FAILED: "Failed",
+} as const;
+
+/** The `delivery_graph_runs` aggregate accessor — the durable run store keyed by `run_key`. */
+export const deliveryGraphRuns = (data: DataLayer) =>
+  data.table<DeliveryGraphRun>("delivery_graph_runs", "run_key");
+
+/** Atomically claim a run for LAUNCH — the at-most-once dispatch fence. Returns `true` iff THIS caller
+ * won the claim and must proceed to `runDeliveryGraph`; `false` iff a concurrent submit already claimed
+ * it (the caller must short-circuit as `alreadyRunning` instead of double-launching). Two fences, one
+ * per starting state, so dispatch is at-most-once from EITHER — the `run_key` PK guards a first launch
+ * and a compare-and-swap on `status` guards a relaunch off a persisted row:
+ *   • no row yet (`existing` null) → INSERT the claim, fenced by the `run_key` PRIMARY KEY: a racing
+ *     loser hits `UNIQUE constraint failed` and returns `false`.
+ *   • a persisted NON-running row (a parked `awaiting-approval` row now being approved, or a terminal
+ *     row being re-run) → a single guarded UPDATE (`SET status='running' … WHERE status <> 'running'`).
+ *     It is ONE statement, so the check-and-flip is atomic even across the delegate's `await` points:
+ *     of two concurrent approved re-submits that both read the same parked row, exactly one flips it
+ *     (`changed === 1`) and the other matches zero rows (`changed === 0`). This closes the double-launch
+ *     hole the PK fence alone left open — an `update`-on-existing path has no unique collision to lose,
+ *     so without this guard both racers would `update` then both launch. The winner writes the run's
+ *     full metadata afterwards (safe: it is now the sole caller past the fence).
+ *
+ * The CAS also CLEARS the instance-bound columns (`process_key`, `process_definition_id`, `phase`,
+ * `phase_node_id`) to the fresh claim's values IN THE SAME statement. A re-run off a terminal row (or
+ * any persisted row) still carries the PRIOR run's `process_key`; flipping `status` alone would make
+ * the row briefly visible as `running` while still pointing at the OLD instance key, so the
+ * `process_key`-keyed instance-tracking reconciler / poller could act on (and mis-reconcile against)
+ * the stale instance before the winner's follow-up metadata write lands. Clearing them atomically with
+ * the flip means a claimed `running` row can never be observed with a stale instance key. */
+export async function claimRunForLaunch(
+  data: DataLayer,
+  existing: boolean,
+  claim: DeliveryGraphRun,
+): Promise<boolean> {
+  if (!existing) {
+    try {
+      await deliveryGraphRuns(data).insert(claim);
+      return true;
+    } catch (err) {
+      if (!isUniqueConstraintFence(err)) throw err;
+      return false;
+    }
+  }
+  const res = await data
+    .open()
+    .exec(
+      `UPDATE "delivery_graph_runs" SET "status" = ?, "process_key" = ?, "process_definition_id" = ?, "phase" = ?, "phase_node_id" = ?, "updated_at" = ? WHERE "run_key" = ? AND "status" <> 'running'`,
+      [
+        claim.status,
+        claim.process_key,
+        claim.process_definition_id,
+        claim.phase,
+        claim.phase_node_id,
+        claim.updated_at,
+        claim.run_key,
+      ],
+    );
+  return res.changed === 1;
+}
+
+/** Persist a PARKED (non-launch) run row — the approval-gate write for an unapproved side-effecting
+ * graph — WITHOUT ever clobbering a concurrently-launched `running` claim. Two concurrent submits of
+ * one graph (same `run_key`) can race an APPROVED launch (which inserts/flips a `running` claim via
+ * `claimRunForLaunch`) against an UNAPPROVED park: a blind insert-or-update would let the park
+ * overwrite that `running` claim back to `awaiting-approval` and null its `process_key`, breaking the
+ * at-most-once dispatch fence and letting a later re-submit double-launch the graph's side effects.
+ * So mirror the launch fence exactly — a first write is the `run_key` PK insert; on a unique
+ * collision (a concurrent submit already wrote the row) OR when a row already exists, re-apply via a
+ * single atomic guarded UPDATE `… WHERE status <> 'running'`. One statement, so the check-and-write
+ * is atomic even across the delegate's `await` points: a racing `running` claim matches zero rows and
+ * survives untouched, while a still-parked or terminal row is idempotently (re-)parked. */
+export async function parkRunFencedAgainstLaunch(
+  data: DataLayer,
+  existing: boolean,
+  row: DeliveryGraphRun,
+): Promise<void> {
+  if (!existing) {
+    try {
+      await deliveryGraphRuns(data).insert(row);
+      return;
+    } catch (err) {
+      if (!isUniqueConstraintFence(err)) throw err;
+    }
+  }
+  await data
+    .open()
+    .exec(
+      `UPDATE "delivery_graph_runs" SET "process_key" = ?, "process_definition_id" = ?, "digest" = ?, "status" = ?, "side_effecting" = ?, "node_count" = ?, "human_node_count" = ?, "side_effect_count" = ?, "title" = ?, "phase" = ?, "phase_node_id" = ?, "human_labels" = ?, "updated_at" = ? WHERE "run_key" = ? AND "status" <> 'running'`,
+      [
+        row.process_key,
+        row.process_definition_id,
+        row.digest,
+        row.status,
+        row.side_effecting,
+        row.node_count,
+        row.human_node_count,
+        row.side_effect_count,
+        row.title,
+        row.phase,
+        row.phase_node_id,
+        row.human_labels,
+        row.updated_at,
+        row.run_key,
+      ],
+    );
+}
+
+/** The idempotency key for a submitted graph: a caller-supplied `idempotencyKey` (trimmed) when
+ * present and non-blank, else the graph's content `digest`. So two POSTs of the SAME graph (no
+ * explicit key) collapse onto one run, and a caller can force a fresh run with an explicit key. */
+export function computeRunKey(idempotencyKey: string | undefined | null, digest: string): string {
+  const trimmed = typeof idempotencyKey === "string" ? idempotencyKey.trim() : "";
+  return trimmed || digest;
+}
+
+/** The approval decision (Decision 7). A graph with NO side-effecting nodes (only `wait`/`human`)
+ * needs no approval and dispatches straight away. A SIDE-EFFECTING graph dispatches only when the
+ * caller presents `approvalToken == digest` — an approval OF the rendered preview, content-addressed
+ * so it cannot be replayed against a different graph. */
+export function isDeliveryGraphApproved(
+  sideEffecting: boolean,
+  approvalToken: string | undefined | null,
+  digest: string,
+): boolean {
+  if (!sideEffecting) return true;
+  return typeof approvalToken === "string" && approvalToken.trim() === digest;
+}
+
+/** The compiled human-task element id for a node's compiled BPMN element (`delivery-human-task__n3`) —
+ * the exact id the S4 compiler inlines and the engine reports as a user task's `elementId`. */
+export function humanTaskElementId(element: string): string {
+  return `${DELIVERY_HUMAN_ELEMENT}__${element}`;
+}
+
+/** The first non-blank line of a multi-line instruction, clamped, for a compact parked-node label. */
+function firstLine(text: string | undefined | null): string {
+  if (typeof text !== "string") return "";
+  const line = text.split("\n").map((l) => l.trim()).find((l) => l.length > 0) ?? "";
+  return line.length > 80 ? `${line.slice(0, 77)}…` : line;
+}
+
+/** Map each human node's compiled user-task element id → a display label (its instruction's first
+ * line, else its author node id), from the S1 compile result. Stamped on the run row at dispatch so
+ * the poller renders the parked-node phase without recompiling the graph. */
+export function buildHumanLabels(compiled: CompileDeliveryGraphResult): Record<string, string> {
+  const elementByNodeId = new Map(compiled.resolved.nodes.map((n) => [n.id, n.element]));
+  const labels: Record<string, string> = {};
+  for (const stop of compiled.humanNodes) {
+    const element = elementByNodeId.get(stop.nodeId);
+    if (element === undefined) continue;
+    labels[humanTaskElementId(element)] = firstLine(stop.prompt) || stop.nodeId;
+  }
+  return labels;
+}
+
+/** Parse a run row's stored `human_labels` JSON back into a map, tolerating a null/blank/corrupt
+ * value (→ empty map) so a bad column can never crash the poller. */
+export function parseHumanLabels(raw: string | null | undefined): Record<string, string> {
+  if (typeof raw !== "string" || raw.trim() === "") return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (typeof v === "string") out[k] = v;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/** The derived (status, phase, parked-node) projection for a RUNNING run, from engine truth. PURE —
+ * the poller supplies the instance state + open user tasks, this maps them to the stored projection:
+ *   • COMPLETED  → `done`   (instanceTracking does NOT reconcile COMPLETED — this poller owns it).
+ *   • TERMINATED → `failed` (a safety net; the instanceTracking `onTerminated` edge also flips it).
+ *   • ACTIVE parked on a human node → `running`, phase `Parked on human node: <label>`.
+ *   • ACTIVE otherwise (watching a wait/agent node) → `running`, phase `Running`. */
+export interface DeliveryPhaseProjection {
+  status: DeliveryGraphRunStatus;
+  phase: string;
+  phase_node_id: string | null;
+}
+
+export function deriveDeliveryPhase(
+  state: ProcessInstanceState | null | undefined,
+  openUserTasks: readonly { elementId?: string }[],
+  humanLabels: Record<string, string>,
+): DeliveryPhaseProjection {
+  if (state === "COMPLETED") return { status: "done", phase: DELIVERY_PHASE.COMPLETED, phase_node_id: null };
+  if (state === "TERMINATED") return { status: "failed", phase: DELIVERY_PHASE.FAILED, phase_node_id: null };
+  const parkedOn = openUserTasks
+    .map((t) => t.elementId)
+    .filter((id): id is string => typeof id === "string" && isDeliveryHumanElement(id))
+    .sort()[0];
+  if (parkedOn !== undefined) {
+    const label = humanLabels[parkedOn] ?? parkedOn;
+    return { status: "running", phase: `Parked on human node: ${label}`, phase_node_id: parkedOn };
+  }
+  return { status: "running", phase: DELIVERY_PHASE.RUNNING, phase_node_id: null };
+}
+
+/** Build the durable row for a run at a given lifecycle point — the SINGLE row-shape builder both the
+ * approval-park and the dispatch write go through, so the two can't drift on which columns a run
+ * carries. `createdAt` is preserved across an update (the door passes the existing row's value). */
+export function buildDeliveryGraphRunRow(input: {
+  runKey: string;
+  digest: string;
+  status: DeliveryGraphRunStatus;
+  sideEffecting: boolean;
+  nodeCount: number;
+  humanNodeCount: number;
+  sideEffectCount: number;
+  title: string | null;
+  phase: string;
+  processKey?: string | null;
+  processDefinitionId?: string | null;
+  humanLabels?: Record<string, string>;
+  createdAt?: string;
+}): DeliveryGraphRun {
+  const at = now();
+  return {
+    run_key: input.runKey,
+    process_key: input.processKey ?? null,
+    process_definition_id: input.processDefinitionId ?? null,
+    digest: input.digest,
+    status: input.status,
+    side_effecting: input.sideEffecting ? 1 : 0,
+    node_count: input.nodeCount,
+    human_node_count: input.humanNodeCount,
+    side_effect_count: input.sideEffectCount,
+    title: input.title,
+    phase: input.phase,
+    phase_node_id: null,
+    human_labels: input.humanLabels ? JSON.stringify(input.humanLabels) : null,
+    created_at: input.createdAt ?? at,
+    updated_at: at,
+  };
+}

package/app/deliveryRunner.ts

@@ -18,6 +18,14 @@ import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 
+/** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
+ * content-addressed deploy id (`delivery-graph-<digest>`) AND the S5 dispatch door's approval token /
+ * default idempotency key. Both the runner (deploy id) and `operations/startDeliveryGraph` (approval +
+ * dedupe key) derive from THIS one function so the two can never drift on how a graph is addressed. */
+export function deliveryGraphDigest(bpmn: string): string {
+  return createHash("sha256").update(bpmn).digest("hex").slice(0, 12);
+}
+
 /** The bounded-timeout / SLA envelope every node inherits (Decision: bounded → escalate). ISO-8601
  * durations. Defaults are conservative; a caller (the S5 door) may tighten them per run. */
 export interface DeliveryRunTimeouts {
@@ -89,7 +97,7 @@ export function prepareDeliveryGraph(graph: DeliveryGraph, options: DeliveryRunO
   const compiled = compileDeliveryGraph(graph);
   if (!compiled.ok) return { ok: false, errors: compiled.errors };
 
-  const digest = createHash("sha256").update(compiled.bpmn).digest("hex").slice(0, 12);
+  const digest = deliveryGraphDigest(compiled.bpmn);
   const processDefinitionId = `${DELIVERY_GRAPH_PROCESS_ID}-${digest}`;
   const bpmn = rewriteProcessId(compiled.bpmn, processDefinitionId);
 

package/app/instance-tracking.test.ts

@@ -12,6 +12,7 @@ import { TERMINAL_STATUSES } from "./delivery.ts";
 import { PLAN_TERMINAL_STATUSES } from "./plan.ts";
 import { FEATURE_TERMINAL_STATUSES } from "./feature.ts";
 import { CONFORMANCE_REVIEWING_STATUS } from "./conformance.ts";
+import { DELIVERY_GRAPH_TERMINAL_STATUSES } from "./deliveryGraphRun.ts";
 
 interface Binding {
   table: string;
@@ -141,3 +142,34 @@ test("instanceTracking: plan_conformance onTerminated status is not active", asy
     `onTerminated review_status "${String(settled)}" must not be listed active`,
   );
 });
+
+// The delivery_graph_runs binding tracks ONLY the engine-instance-backed status. Unlike PR/plan/
+// feature bindings, its active set is DELIBERATELY narrower than the code's DISPLAY active set
+// (DELIVERY_GRAPH_ACTIVE_STATUSES = awaiting-approval + running): a parked `awaiting-approval` run
+// has a null `process_key`, so the `process_key`-keyed reconciler cannot track it. Tie the manifest
+// to that invariant so a future change can't silently (a) list a terminal status active — the
+// reconciler would clobber a settled run — or (b) add `awaiting-approval`, which would make the
+// reconciler flip every parked run to `failed` on its next pass (a null key never matches a live
+// instance → "vanished" → onTerminated).
+test("instanceTracking: delivery_graph_runs activeStatuses excludes every terminal status", async () => {
+  const b = bindingFor(await bindings(), "delivery_graph_runs");
+  for (const terminal of DELIVERY_GRAPH_TERMINAL_STATUSES) {
+    assert(!b.activeStatuses?.includes(terminal), `terminal status "${terminal}" must not be active`);
+  }
+});
+
+test("instanceTracking: delivery_graph_runs activeStatuses is exactly the instance-backed status (running)", async () => {
+  const b = bindingFor(await bindings(), "delivery_graph_runs");
+  assertEquals([...(b.activeStatuses ?? [])].sort(), ["running"]);
+  // A parked run has no engine instance (process_key NULL) — it must NOT be reconciled by this binding.
+  assert(!b.activeStatuses?.includes("awaiting-approval"), "awaiting-approval (null process_key) must not be instance-tracked");
+});
+
+test("instanceTracking: delivery_graph_runs onTerminated status is not active", async () => {
+  const b = bindingFor(await bindings(), "delivery_graph_runs");
+  const settled = b.onTerminated.set.status;
+  assert(
+    typeof settled === "string" && !b.activeStatuses?.includes(settled),
+    `onTerminated status "${String(settled)}" must not be listed active`,
+  );
+});

package/app/persist-escalation.test.ts

@@ -212,36 +212,3 @@ test("a control-flow arm with a blank question opens nothing so gw-escalated re-
   assertEquals(inserts.escalations.length, 0, "no dead escalation is fabricated");
   assertEquals(updates.pull_requests?.length ?? 0, 0, "the PR is never flipped to escalated");
 });
-
-// The scope-integrity arm (persist-escalation-blockedcomments) binds the escalation to the reviewed
-// commit (issue #395): it stamps `head_sha` and marks `scope_block` so the converge-gate can honour
-// a same-HEAD human answer as an override instead of re-deriving the block and re-escalating forever.
-test("persist-escalation binds a scope-integrity escalation to the reviewed HEAD (head_sha + scope_block)", async () => {
-  const { app, inserts } = fakeApp();
-  const job = {
-    variables: {
-      prKey: "o/r#5",
-      round: 2,
-      status: "blocked",
-      question: "Scope integrity blocked: ...",
-      recordRound: false,
-      headSha: "HEAD1",
-      scopeBlock: true,
-    },
-  };
-  await handler(job as any, app as any);
-  assertEquals(inserts.escalations.length, 1);
-  assertEquals((inserts.escalations[0] as any).head_sha, "HEAD1", "the escalation carries the reviewed commit");
-  assertEquals((inserts.escalations[0] as any).scope_block, 1, "flagged as a scope-integrity block");
-});
-
-// Every other escalation arm (agent verdict, no-progress, max-rounds, stalled) omits the scope
-// binding: head_sha stays absent and scope_block defaults to 0, so the override door opens ONLY for
-// the block a human can actually answer.
-test("persist-escalation: a non-scope escalation records no HEAD binding and scope_block 0", async () => {
-  const { app, inserts } = fakeApp();
-  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "max rounds" } };
-  await handler(job as any, app as any);
-  assertEquals((inserts.escalations[0] as any).head_sha, undefined, "no reviewed HEAD to bind");
-  assertEquals((inserts.escalations[0] as any).scope_block, 0, "not a scope-integrity block");
-});

package/app/service.ts

@@ -28,6 +28,7 @@ import {
 } from "./conformance.ts";
 import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
+import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { backfillFeatureStages, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
 import {
@@ -2196,6 +2197,43 @@ async function sweepOpenEscalationTasks(base: string, headers: Record<string, st
  * completed task's row is deleted (answered here, via the task inbox, or out-of-band) and `showCount`
  * reflects live pending work. Best-effort + idempotent — per-instance failures are isolated so one bad
  * instance never stalls the pass. */
+/** Poll pass (ADR 0005 slice S5): reconcile each RUNNING delivery-graph run's derived phase from
+ * engine truth, and complete it when its instance ends. A delivery graph is a DYNAMIC compiled
+ * process with no happy-path host worker, so — unlike `plans`/`feature_runs`, whose spine workers
+ * write their own terminal row — this pass owns both the parked-node projection AND the COMPLETED→done
+ * transition (instanceTracking's `onTerminated` edge reconciles only TERMINATED, never COMPLETED, so
+ * a graph that ends normally would otherwise stay `running` forever). Generalises the `epic_phase`
+ * derived-phase machinery to a graph whose element ids aren't known ahead of time: the parked-node
+ * label is derived from the run row's stamped `human_labels` + the instance's OPEN user tasks. Scoped
+ * to `running` rows (an `awaiting-approval` run has no instance yet), so it stays O(in-flight). */
+export async function pollDeliveryGraphPhase(
+  data: DataLayer,
+  engine: Pick<EngineClient, "searchProcessInstances" | "searchUserTasks">,
+) {
+  for (const run of await deliveryGraphRuns(data).find({ status: "running" })) {
+    if (!run.process_key) continue;
+    const processKey = run.process_key;
+    try {
+      const [snapshots, tasks] = await Promise.all([
+        engine.searchProcessInstances({ processInstanceKeys: [processKey] }),
+        engine.searchUserTasks({ processInstanceKey: processKey, state: "CREATED" }),
+      ]);
+      const state = snapshots.find((s) => String(s.processInstanceKey) === processKey)?.state ?? null;
+      const projection = deriveDeliveryPhase(state, tasks, parseHumanLabels(run.human_labels));
+      if (run.status !== projection.status || run.phase !== projection.phase || run.phase_node_id !== projection.phase_node_id) {
+        await deliveryGraphRuns(data).update(run.run_key, {
+          status: projection.status,
+          phase: projection.phase,
+          phase_node_id: projection.phase_node_id,
+          updated_at: now(),
+        });
+      }
+    } catch (err) {
+      console.error(`[poller] delivery graph ${run.run_key}: ${err}`);
+    }
+  }
+}
+
 export async function pollUserTasks(
   data: DataLayer,
   engine: EngineClient,
@@ -2384,6 +2422,7 @@ export async function pollOnce(
   await pollLineage(data);
   await pollMergesPerDay(data);
   await pollUserTasks(data, engine, engineRest);
+  await pollDeliveryGraphPhase(data, engine);
   if (engineRest) {
     const base = engineRest.restAddress.replace(/\/+$/, "");
     const headers: Record<string, string> = { "content-type": "application/json" };

package/db/migrations/057_drop_escalation_head_override.sql

@@ -0,0 +1,16 @@
+-- Contract phase for the escalation scope-override columns (migration 056, issue #395).
+--
+-- Migration 056 added `escalations.head_sha` + `escalations.scope_block` to give the DETERMINISTIC
+-- scope-integrity gate a human-override door: it bound a scope escalation to the reviewed HEAD so a
+-- same-HEAD human answer could override the block instead of re-escalating forever. That whole
+-- deterministic gate has since been replaced by the `senior:scope-classify` AGENT classifier, which
+-- reads each closed issue's acceptance criteria and honours the recorded human `answer` directly —
+-- so nothing writes or reads these two columns any more. They are dead schema (a drift surface with
+-- no source of truth behind them), so drop them.
+--
+-- 056 is forward-only and immutable (its ledger row stays), so this is the standard expand→contract
+-- follow-up rather than an edit to 056. Both drops are safe: the columns were nullable/defaulted and
+-- have no remaining writer or reader. Numbered after the current highest prefix (056); the runner
+-- wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE escalations DROP COLUMN scope_block;
+ALTER TABLE escalations DROP COLUMN head_sha;

package/db/migrations/058_delivery_graph_runs.sql

@@ -0,0 +1,58 @@
+-- The `startDeliveryGraph` run aggregate (ADR 0005 Decision 7, slice S5). The dispatch door
+-- (`operations/startDeliveryGraph.ts`, POST /app/api/actions/start/delivery-graph) turns an
+-- agent-authored `DeliveryGraph` into a RUNNING engine-native process (via the S4 runner) — but
+-- because these graphs merge PRs and publish packages, dispatch is GATED on an approval of the
+-- rendered preview and must be idempotent. This table is the aggregate that makes both properties
+-- durable and gives the cockpit a row to show WHERE a run is parked:
+--
+--   • run_key (PK) — the idempotency key: a caller-supplied `idempotencyKey` or, by default, the
+--     graph's content digest (`sha256(compiled.bpmn)[:12]`). A re-POST of the same graph collapses
+--     onto the same row, so an in-flight (`running`) run short-circuits instead of double-launching
+--     (mirrors `startPlan`'s `alreadyRunning`). The UNIQUE PK is the durable at-most-once fence.
+--   • status — the run lifecycle: `awaiting-approval` (a side-effecting graph parked at the approval
+--     gate — no instance started yet), `running` (dispatched to the engine), `done` (the instance
+--     COMPLETED), `failed` (the instance TERMINATED, or instance-tracking reconciled a vanished
+--     running instance — nano.app.json's `delivery_graph_runs` binding maps `onTerminated` to
+--     `failed`), `abandoned` (a reserved terminal status in the lifecycle union, not currently
+--     produced by the reconciler). `awaiting-approval`/`running` are the ACTIVE (in-flight) statuses shown in
+--     the cockpit's active grid; only `running` is engine-instance-backed and thus instance-tracked
+--     (nano.app.json keys off process_key), while `awaiting-approval` has no instance (process_key
+--     NULL) and is display-only. The terminal three drop out of the cockpit's active grid.
+--   • digest — the content-addressed approval token: a side-effecting graph dispatches only when the
+--     caller presents `approvalToken == digest`. Persisted so a resumed/second POST can re-derive and
+--     re-check it without recompiling out of band.
+--   • phase / phase_node_id — the derived, display-only "where is it parked" projection the poller
+--     (`pollDeliveryGraphPhase`) recomputes from the running instance's open user tasks (generalising
+--     the epic_phase derived-phase machinery): e.g. "Parked on human node: manual OTP publish" vs a
+--     bare "Running". The door seeds `phase` at write time — `Awaiting approval` for a parked
+--     (awaiting-approval) row, `Running` at dispatch — and the poller then refines it from engine truth
+--     for a running instance; `phase_node_id` is NULL until the poller projects a parked human node.
+--
+-- process_key is the started instance key (NULL while `awaiting-approval`); the counts are the
+-- compiled graph's shape (nodes / human stop-points / side effects), stamped at dispatch so the grid
+-- and the approval gate need no recompile to render.
+CREATE TABLE IF NOT EXISTS delivery_graph_runs (
+  run_key TEXT PRIMARY KEY,
+  process_key TEXT,
+  process_definition_id TEXT,
+  digest TEXT NOT NULL,
+  status TEXT NOT NULL,
+  side_effecting INTEGER NOT NULL DEFAULT 0,
+  node_count INTEGER NOT NULL DEFAULT 0,
+  human_node_count INTEGER NOT NULL DEFAULT 0,
+  side_effect_count INTEGER NOT NULL DEFAULT 0,
+  title TEXT,
+  phase TEXT,
+  phase_node_id TEXT,
+  -- JSON map of compiled human-task element id (`delivery-human-task__<element>`) → a display label
+  -- (the human node's instruction first line, else its author node id). Stamped at dispatch so
+  -- `pollDeliveryGraphPhase` can render "Parked on human node: <label>" from the run row + the open
+  -- user tasks alone — no recompile of the graph in the poller.
+  human_labels TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+-- The instance-tracking reconciler and pollDeliveryGraphPhase both scan by process instance key.
+CREATE INDEX IF NOT EXISTS ix_delivery_graph_runs_process_key
+  ON delivery_graph_runs (process_key);

package/e2e/convergence-escalation.e2e.ts

@@ -87,6 +87,12 @@ describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
       capturedAnswer = (job.variables as Record<string, unknown>).answer;
       return { status: "converged", summary: "resolved after the human answer" };
     });
+    // `senior:scope-classify` is likewise an externalTaskType (no app worker): the converged round
+    // routes through it before finalizing. Stub it as "scope delivered" so the happy path reaches
+    // persist-converged rather than parking on an unserviced agent job.
+    await app.engine.registerWorker("senior:scope-classify", () => {
+      return { scopeBlocked: false, scopeBlockReason: "" };
+    });
   });
 
   after(async () => {