@nanobpm/nano-workforce 0.123.1 → 0.124.0

package/app/pollUserTasks.test.ts

@@ -584,3 +584,30 @@ test("pollUserTasks (engine-first): a delivery-human task on an UNTRACKED run st
   assertEquals(byKey["35002"].subject_type, "delivery");
   assertEquals(byKey["35002"].subject_key, "dg-9"); // instance fallback — non-blank so it renders
 });
+
+test("pollUserTasks (typed-seam fallback): projects an inlined delivery-human task on a RUNNING run, bucketed `delivery` (issue #442)", async () => {
+  // The reduced-capability host (no raw-REST surface) discovers open tasks by scanning each active
+  // subject's instance through the typed `openUserTasks` seam. A delivery-graph `human` node parks on its
+  // RUNNING run's instance, so that instance MUST be scanned here too — else the inlined
+  // `delivery-human-task__<node>` gate is dropped on this path even though its leak guard would accept it.
+  // Guards the OTHER discovery path the engine-first sweep tests don't reach.
+  const { data, stores } = memData({
+    delivery_graph_runs: [
+      { run_key: "delivery-graph-403eb22e", process_key: "dg-1", status: "running", title: "release runbook" },
+      { run_key: "delivery-graph-pending", process_key: null, status: "awaiting-approval", title: "not launched yet" },
+    ],
+  });
+  const engine = fakeEngine({
+    "dg-1": [{ userTaskKey: "35002", elementId: "delivery-human-task__n1" }],
+  });
+
+  await pollUserTasks(data, engine); // no engineRest → typed-seam fallback
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["35002"]);
+  assertEquals(byKey["35002"].element_id, "delivery-human-task__n1");
+  assertEquals(byKey["35002"].kind_label, "Delivery: human step");
+  assertEquals(byKey["35002"].subject_type, "delivery");
+  assertEquals(byKey["35002"].subject_key, "delivery-graph-403eb22e");
+  assertEquals(byKey["35002"].subject_title, "release runbook");
+});

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 { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
 import { isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
@@ -51,7 +52,12 @@ import {
 } from "./github.ts";
 import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
-import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
+import {
+  freshHeadRunAction,
+  headRunPresenceCount,
+  loadMergeProtocol,
+  type MergeProtocol,
+} from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
 import {
   capabilityGates,
@@ -178,7 +184,7 @@ export const MERGE_ADMIN = ["1", "true", "on", "yes"].includes(
 
 const now = () => new Date().toISOString();
 
-interface PullRequest {
+export interface PullRequest {
   pr_key: string;
   repo: string;
   number: number;
@@ -1099,6 +1105,41 @@ async function advanceIfTerminalOutOfBand(
   return true;
 }
 
+/** Frugal-CI fresh-head-run self-heal, shared by the `"waiting"` and `"draft"` merge verdicts
+ * (issue #454). Both verdicts feed the same {@link freshHeadRunAction} decision — when the repo's
+ * merge protocol wants a fresh head run and this head has not been nudged yet, produce one
+ * (mark-ready / reopen) and record the head so we fire at most once per landing attempt. Returns
+ * `true` only when the self-heal was **actually applied** (the caller should re-poll); returns
+ * `false` when no self-heal applies **or** the action was selected but failed (`ok === false`, e.g.
+ * missing permission / repo policy) — so a caller that gates escalation on this (the `"draft"`
+ * branch) falls through to the actionable escalation instead of `continue`-looping forever on a
+ * self-heal that can never succeed. One implementation so the two verdicts can never drift (attempt
+ * de-dupe, persistence, logging). `ensure` is injectable for tests; production uses the real
+ * {@link ensureFreshHeadRun}. */
+export async function maybeEnsureFreshHeadRun(
+  data: DataLayer,
+  repo: string,
+  number: number,
+  prKey: string,
+  protocol: MergeProtocol,
+  verdict: "ready" | "waiting" | "conflict" | "blocked" | "draft",
+  st: PrState,
+  pr: PullRequest,
+  ensure: typeof ensureFreshHeadRun = ensureFreshHeadRun,
+): Promise<boolean> {
+  const action = freshHeadRunAction(protocol, verdict, headRunPresenceCount(protocol, st), st.isDraft, {
+    headRefOid: st.headRefOid,
+    lastActionHeadRefOid: pr.fresh_head_run_head,
+  });
+  if (!action) return false;
+  const ok = await ensure(repo, number, action).catch(() => false);
+  if (ok && st.headRefOid) {
+    await prs(data).update(prKey, { fresh_head_run_head: st.headRefOid, updated_at: now() });
+  }
+  console.log(`[poller] ${verdict} -> fresh head run (${action}) ${ok ? "requested" : "skipped"} -> ${prKey}`);
+  return ok;
+}
+
 /** Merge-stage poll pass (SPEC §11). Four durable waits, each keyed off the PR's `status`, are
  * advanced by correlating a message — mirroring the review-ready pattern so the process owns
  * the wait and this glue only signals when a GitHub condition is met:
@@ -1159,6 +1200,35 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
       // the PR as UNSTABLE. The same handle is reused by the frugal-CI fresh-head-run branch below.
       const protocol = await loadMergeProtocol(repo, token).catch(() => null);
       const verdict = classifyMergeability(st, protocol ?? undefined);
+      if (verdict === "draft") {
+        // A draft PR is never landable — GitHub refuses the merge outright (issue #454). Two remedies,
+        // in order: (1) self-heal — when the repo's merge protocol has a mark-ready capability
+        // (`freshHeadRun: "ready"`/`"ready-or-reopen"`), mark the PR ready ourselves (the frugal-CI
+        // path), which both un-drafts it and produces the required run, then re-poll; a `"reopen"`-only
+        // protocol has NO mark-ready capability, so `freshHeadRunAction` returns null for a draft (a
+        // reopen can't un-draft) and this falls straight through to (2). (2) otherwise — no self-heal
+        // applies, OR the self-heal was attempted but could not be performed (e.g. missing permission /
+        // repo policy) — escalate with an ACTIONABLE "mark it ready" message, instead of
+        // `continue`-looping forever on a self-heal that can never succeed or surfacing GitHub's opaque
+        // "blocked" refusal.
+        if (protocol) {
+          if (await maybeEnsureFreshHeadRun(data, repo, number, prKey, protocol, verdict, st, pr)) {
+            continue; // re-poll: the mark-ready both un-drafts the PR and produces the required run
+          }
+        }
+        // No applicable (or successful) protocol-driven self-heal → escalate so a human marks it ready.
+        await flipToMergingThenPublish(data, engine, prKey, "waiting_merge", {
+          name: "merge-ready",
+          correlationKey: prKey,
+          variables: {
+            mergeState: verdict, // "draft" → gw-mergeable default → merge-esc-conflict (draft-aware FEEL)
+            failingChecks: st.failingChecks,
+            failingChecksList: st.failingCheckNames.join("\n"),
+          },
+        });
+        console.log(`[poller] draft (no self-heal) -> escalate mark-ready -> ${prKey}`);
+        continue;
+      }
       if (verdict === "waiting") {
         // Frugal-CI remedy (#43): when the repo publishes a merge protocol that wants a fresh
         // head run and the PR has NO required head run yet, review has converged but the last push
@@ -1170,17 +1240,7 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
         // `headRefOid`, so downstream merge-train PRs get a new nudge after every post-rebase
         // landing attempt.
         if (protocol) {
-          const action = freshHeadRunAction(protocol, verdict, headRunPresenceCount(protocol, st), st.isDraft, {
-            headRefOid: st.headRefOid,
-            lastActionHeadRefOid: pr.fresh_head_run_head,
-          });
-          if (action) {
-            const ok = await ensureFreshHeadRun(repo, number, action).catch(() => false);
-            if (ok && st.headRefOid) {
-              await prs(data).update(prKey, { fresh_head_run_head: st.headRefOid, updated_at: now() });
-            }
-            console.log(`[poller] fresh head run (${action}) ${ok ? "requested" : "skipped"} -> ${prKey}`);
-          }
+          await maybeEnsureFreshHeadRun(data, repo, number, prKey, protocol, verdict, st, pr);
         }
         continue; // GitHub still computing / checks pending
       }
@@ -2245,6 +2305,19 @@ export async function pollDeliveryGraphPhase(
   }
 }
 
+/** Poll pass (ADR 0005 Decision 7): age out staged delivery-graph proposals whose TTL has elapsed by
+ * flipping them to `expired`, so they drop out of the cockpit's staged grid rather than lingering there
+ * only to fail dispatch. The grid filters purely on `status = 'staged'` (its datasource cannot express an
+ * `expires_at > now` comparison), so this reconciliation sweep is what realises the proposal TTL. It is
+ * data-only and idempotent — a proposal already terminal is left untouched. */
+export async function pollDeliveryProposals(data: DataLayer) {
+  try {
+    await sweepExpiredProposals(data);
+  } catch (err) {
+    console.error(`[poller] delivery graph proposals sweep: ${err}`);
+  }
+}
+
 export async function pollUserTasks(
   data: DataLayer,
   engine: EngineClient,
@@ -2381,6 +2454,11 @@ export async function pollUserTasks(
     for (const status of PLAN_ACTIVE_STATUSES) for (const plan of await plans(data).find({ status })) await scanInstance(plan.process_key);
     for (const status of PR_ACTIVE_STATUSES) for (const pr of await prs(data).find({ status })) await scanInstance(pr.process_key);
     for (const review of await activeConformanceReviews(data)) await scanInstance(review.process_key);
+    // A delivery-graph `human` node parks on its RUNNING run's engine instance (an awaiting-approval run
+    // has no instance yet — mirrors `pollDeliveryGraphPhase`). Scan it too so the inlined
+    // `delivery-human-task__<node>` gate surfaces on this reduced-capability path exactly as it does on
+    // the engine-first sweep — otherwise the typed-seam host silently drops every delivery human gate.
+    for (const run of await deliveryGraphRuns(data).find({ status: "running" })) await scanInstance(run.process_key);
   }
 
   const desired = [...desiredByKey.values()];
@@ -2415,6 +2493,7 @@ export async function pollOnce(
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
   await pollDeliveryGraphPhase(data, engine);
+  await pollDeliveryProposals(data);
   if (engineRest) {
     const base = engineRest.restAddress.replace(/\/+$/, "");
     const headers: Record<string, string> = { "content-type": "application/json" };

package/app/stage.test.ts

@@ -68,14 +68,28 @@ test("skipped: the three converge/auto_merge cases", () => {
   assertEquals(deriveStage(base({ status: "running", converge: 1, auto_merge: 1 })).skipped, "");
 });
 
-test("attention: derives from status alone (blocked, escalation, none)", () => {
-  // Issue #332 dropped the denormalised escalation pointer/question columns; `attention` is now a pure
-  // function of `status` — `awaiting_operator` (a parked blocked run) → "blocked", `escalated` → "⚠".
-  assertEquals(deriveStage(base({ status: "awaiting_operator" })).attention, "blocked");
-  assertEquals(deriveStage(base({ status: "escalated" })).attention, "⚠");
+test("attention: derives from OPEN user-task engine truth (blocked, escalation, none), NOT from status", () => {
+  // Issue #422: `attention` is a pure function of whether an OPEN native user task exists for the run
+  // (the `user_tasks` inbox — the authoritative "who is waiting on a human" set), never of the sticky
+  // `status` variable. An open `feature-blocked` task → "blocked"; an open `feature-escalation` task → "⚠".
+  assertEquals(deriveStage(base({ status: "awaiting_operator", hasOpenBlockedTask: true })).attention, "blocked");
+  assertEquals(deriveStage(base({ status: "escalated", hasOpenEscalationTask: true })).attention, "⚠");
   assertEquals(deriveStage(base({ status: "running" })).attention, null);
 });
 
+test("attention #422: an ANSWERED escalation (status still 'escalated' but NO open task) shows NO badge", () => {
+  // The answer-loop returns the token to `implement-task` with no status reset, so `status` reads a
+  // stale "escalated" while the escalation user task is already gone. Sourcing the badge from engine
+  // truth (no open task) clears the ⚠ — the drift the old `status`-derived badge produced.
+  assertEquals(deriveStage(base({ status: "escalated" })).attention, null);
+  assertEquals(deriveStage(base({ status: "escalated", hasOpenEscalationTask: false })).attention, null);
+  // And an escalated run WHOSE task is genuinely open still shows ⚠.
+  assertEquals(deriveStage(base({ status: "escalated", hasOpenEscalationTask: true })).attention, "⚠");
+  // Symmetrically for the blocked/operator wait.
+  assertEquals(deriveStage(base({ status: "awaiting_operator" })).attention, null);
+  assertEquals(deriveStage(base({ status: "awaiting_operator", hasOpenBlockedTask: true })).attention, "blocked");
+});
+
 // The three parked-status rows called out by the plan review.
 test("escalated WITH pr_key → PR open / null", () => {
   const d = deriveStage(base({ status: "escalated", pr_key: "o/r#5" }));
@@ -89,8 +103,8 @@ test("escalated WITHOUT pr_key → Implementing / null", () => {
   assertEquals(d.state, null);
 });
 
-test("awaiting_operator WITHOUT pr_key → Implementing / null, attention 'blocked' when parked", () => {
-  const d = deriveStage(base({ status: "awaiting_operator", pr_key: null }));
+test("awaiting_operator WITHOUT pr_key → Implementing / null, attention 'blocked' when its task is open", () => {
+  const d = deriveStage(base({ status: "awaiting_operator", pr_key: null, hasOpenBlockedTask: true }));
   assertEquals(d.stage, "Implementing");
   assertEquals(d.state, null);
   assertEquals(d.attention, "blocked");

package/app/stage.ts

@@ -43,6 +43,14 @@ export interface StageInput {
   pr_key?: string | null;
   converge?: number | boolean | null;
   auto_merge?: number | boolean | null;
+  /** Engine truth for the `attention` badge (issue #422): whether an OPEN native user task of each
+   * human-wait kind currently exists for this run, from the `user_tasks` inbox (`pollUserTasks`, the
+   * authoritative "who is waiting on a human" set). `attention` derives from THESE, never from the
+   * drift-prone `status` variable — so once an escalation is answered (its `user_tasks` row deleted)
+   * the badge clears immediately even while `status` still reads a stale `"escalated"`. Omitted/false
+   * ⇒ no open task ⇒ no badge. `feature_read_model` (075) mirrors this with correlated EXISTS lookups. */
+  hasOpenBlockedTask?: boolean | null;
+  hasOpenEscalationTask?: boolean | null;
 }
 
 /** The derived pipeline projection for one run. `skipped` is a space-separated set of stage keys not
@@ -91,11 +99,16 @@ export function deriveStage(run: StageInput): DerivedStage {
 
   // `attention`: a short badge for the active stage (the renderer colours it from `state`). This is how
   // a parked `awaiting_operator`/`escalated` run surfaces as attention WITHOUT altering its stage.
-  // Derived from `status` alone (issue #332): the parked-task pointers that used to source it were
-  // dropped with the denormalised escalation surface, and the authoritative "who is waiting on a human"
-  // list now lives on the `user_tasks` Tasks inbox. `awaiting_operator` (parked at `feature-blocked`)
-  // shows the blocked glyph; `escalated` (parked at `feature-escalation`) shows the ⚠ badge.
-  const attention = status === "awaiting_operator" ? "blocked" : status === "escalated" ? "⚠" : null;
+  // Derived from ENGINE TRUTH — the presence of an OPEN native user task (issue #422), NOT from the
+  // `status` variable. `status` is worker-written imperatively and goes stale on the answer-loop back
+  // into `implement-task` (the process does not reset it), so a run whose escalation was already
+  // ANSWERED still reads `status="escalated"` until its next job completes; sourcing the badge from
+  // that value made the read model lie (a resolved run flagged ⚠ on Overview). The authoritative
+  // "who is waiting on a human" set is the `user_tasks` inbox (`pollUserTasks`), which holds a row
+  // IFF the task is open and deletes it the moment it is answered — so a run shows the blocked glyph
+  // IFF an open `feature-blocked` task exists, and ⚠ IFF an open `feature-escalation` task exists.
+  // Once answered, the row is gone and the badge clears regardless of the stale `status`.
+  const attention = truthy(run.hasOpenBlockedTask) ? "blocked" : truthy(run.hasOpenEscalationTask) ? "⚠" : null;
 
   return { stage, state, skipped: skippedKeys.join(" "), attention };
 }

package/db/migrations/075_delivery_graph_proposals.sql

@@ -0,0 +1,48 @@
+-- The `staged` delivery-graph proposal store (ADR 0005 Decision 7, issue #460). This realises
+-- `propose → preview → approve → dispatch` as intended: the agent-facing surface ends at
+-- propose → compile → STAGE, and a HUMAN dispatches the staged proposal from the cockpit. The old
+-- `approvalToken` was a REPLAYABLE content digest handed back to the same caller, so any holder of
+-- the API credential self-approved. Removing the dispatch affordance from the agent surface (there is
+-- no `start` endpoint) dissolves that hole: the compile door persists the compiled graph HERE as a
+-- `staged` proposal and returns only a preview + a navigational `reviewUrl` — nothing that can trigger
+-- a run. The cockpit lists these rows, renders the preview, and dispatches the one the operator picks.
+--
+--   • digest (PK) — the content address of the compiled graph (`sha256(compiled.bpmn)[:12]`), the
+--     SAME digest the runner uses for the content-addressed deploy id. It NAMES the proposal so the
+--     agent can hand the operator an unambiguous "dispatch <digest>" and the operator dispatches
+--     EXACTLY the digest they previewed. A re-compile of the same bytes is idempotent (same PK).
+--   • logical_key — the LOGICAL graph identity (the graph's `name`, else the digest) used to
+--     SUPERSEDE: staging a changed graph (new digest) for the same logical key retires the prior
+--     staged proposal, so the cockpit shows one live proposal per logical graph, not every recompile.
+--   • graph — the original `DeliveryGraph` JSON, retained so the cockpit dispatch action can run the
+--     runner for the previewed digest without the agent re-submitting anything.
+--   • preview — the rendered preview JSON (`{ diagram, sideEffects, humanNodes }`) the cockpit shows,
+--     stamped at stage time so the list renders without recompiling.
+--   • status — `staged` (awaiting operator review), `superseded` (replaced by a newer digest for its
+--     logical key), `dispatched` (the operator launched it), or `expired` (aged out of its TTL before
+--     dispatch). Only `staged` rows show in the cockpit; the poller sweeps aged-out `staged` rows to
+--     `expired` (the grid's datasource filter is equality-only, so expiry is realised by that status
+--     flip, not an `expires_at > now` clause).
+--   • expires_at — the TTL horizon. Staged proposals age out of the cockpit list so a stale entry an
+--     operator never dispatched does not linger; the poller flips an aged-out `staged` row to `expired`.
+CREATE TABLE IF NOT EXISTS delivery_graph_proposals (
+  digest TEXT PRIMARY KEY,
+  logical_key TEXT NOT NULL,
+  title TEXT,
+  graph TEXT NOT NULL,
+  preview TEXT NOT NULL,
+  node_count INTEGER NOT NULL DEFAULT 0,
+  human_node_count INTEGER NOT NULL DEFAULT 0,
+  side_effect_count INTEGER NOT NULL DEFAULT 0,
+  side_effecting INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL DEFAULT 'staged',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL
+);
+
+-- Supersede scans by logical_key; the cockpit list filters by status + expiry.
+CREATE INDEX IF NOT EXISTS ix_delivery_graph_proposals_logical
+  ON delivery_graph_proposals (logical_key);
+CREATE INDEX IF NOT EXISTS ix_delivery_graph_proposals_status
+  ON delivery_graph_proposals (status);

package/db/migrations/075_feature_read_model_attention_from_user_tasks.sql

@@ -0,0 +1,113 @@
+-- Feature-run `attention` badge: derive it from engine truth (an OPEN native user task), not from the
+-- drift-prone `status` variable (issue #422 — the L1 surface closure #439 named but did not ship).
+--
+-- 073_feature_read_model.sql retired the WRITE-TIME display projection (L2) into this VIEW, but it
+-- still derived `attention` from the row's own `status` column:
+--     WHEN fr.status = 'awaiting_operator' THEN 'blocked'
+--     WHEN fr.status = 'escalated'         THEN '⚠'
+-- `status` is a process-scope variable set imperatively by the workers on the happy path. The `feature`
+-- process loops the answer arm (`w_answerLoop`, resolution="answer") straight back into `implement-task`
+-- with NO reset step, so after an escalation is ANSWERED the token is ACTIVE again at `implement-task`
+-- while `status` still reads the previous iteration's `"escalated"` until the re-running agent job
+-- completes and overwrites it (issue #422, observed live on merlin: feature instance 31779 showing ⚠
+-- on Overview though its escalation was resolved and it was back implementing). Deriving the badge from
+-- that sticky value makes the read model LIE — the exact "projected state maintained imperatively at
+-- write time" defect class #439 set out to close ("derive it, don't maintain it — No Drift Surfaces").
+--
+-- The authoritative "who is waiting on a human" set is NOT `status` — it is the `user_tasks` inbox
+-- (034_user_tasks_inbox.sql): `pollUserTasks` (app/service.ts) reconciles exactly one row per CURRENTLY
+-- OPEN escalation user task from the engine and DELETES the row the moment the task closes (answered
+-- here, via the Tasks inbox, or out-of-band). So a run is:
+--   * awaiting an operator (blocked glyph) IFF an open `feature-blocked`     user task exists for it, and
+--   * escalated            (⚠     badge)  IFF an open `feature-escalation`   user task exists for it.
+-- Deriving `attention` from that presence (engine truth) instead of `status` closes the surface: once
+-- the escalation is answered the `user_tasks` row is gone, so ⚠ clears immediately REGARDLESS of the
+-- stale `status`. There is no stored column and no write path any writer can leave stale — the badge is
+-- a pure function of the live open-task set, recomputed on every read. `deriveStage` (app/stage.ts)
+-- remains the canonical TS oracle: it now takes the same open-task signals, and
+-- app/featureReadModel.test.ts pins the VIEW to it in lockstep over the full status × open-task matrix
+-- (including the #422 case: status='escalated' with NO open task → attention NULL).
+--
+-- pollUserTasks keys these rows `subject_type='feature'`, `subject_key=<feature_key>` (app/service.ts
+-- DEFAULT_SUBJECT_TYPE / contextFor), so the correlated match is on `fr.feature_key`. `stage` is
+-- deliberately UNCHANGED — an escalated/awaiting_operator run maps to `Implementing`, which is correct
+-- whether or not the flag is stale (a run back at `implement-task` IS implementing); only the attention
+-- badge was drifting, so only it moves to engine-truth derivation.
+--
+-- Forward-only, non-additive to `feature_runs` (a VIEW redefinition): `DROP VIEW` then `CREATE VIEW`,
+-- plus one idempotent `CREATE INDEX IF NOT EXISTS` on `user_tasks` to front the correlated `attention`
+-- lookups (see the trailing index comment).
+-- 073 is a MERGED, IMMUTABLE migration — never edited; this is a NEW migration that supersedes its VIEW
+-- definition. `user_tasks` (034) already exists earlier in the chain, so the correlated subquery
+-- resolves. A single plain `CREATE VIEW … SELECT … FROM feature_runs fr` (the `user_tasks` lookups are
+-- nested EXISTS subqueries at paren depth ≥ 1, so `feature_runs fr` stays the sole top-level FROM and
+-- every output column stays aliased — the static pages↔schema contract guard, scripts/pages-contract.
+-- test.ts, still parses the projection). Numbered after the current highest prefix on origin/main (074).
+-- The runner wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+DROP VIEW IF EXISTS feature_read_model;
+
+CREATE VIEW feature_read_model AS
+SELECT
+  fr.feature_key AS feature_key,
+  fr.repo AS repo,
+  fr.issue_number AS issue_number,
+  fr.issue_url AS issue_url,
+  fr.title AS title,
+  fr.base_branch AS base_branch,
+  fr.status AS status,
+  fr.process_key AS process_key,
+  fr.pr_key AS pr_key,
+  fr.converge AS converge,
+  fr.auto_merge AS auto_merge,
+  fr.outcome AS outcome,
+  fr.delivery_label AS delivery_label,
+  fr.acknowledged_at AS acknowledged_at,
+  fr.created_at AS created_at,
+  fr.updated_at AS updated_at,
+  (CASE
+    WHEN fr.status IN ('merged', 'converged', 'blocked', 'failed', 'skipped', 'abandoned') THEN 'Done'
+    WHEN fr.status = 'converging' THEN 'Converging'
+    WHEN (fr.pr_key IS NOT NULL AND fr.pr_key <> '') OR fr.status = 'opened' THEN 'PR open'
+    WHEN fr.status IN ('running', 'escalated', 'awaiting_operator') THEN 'Implementing'
+    ELSE 'Requested'
+  END) AS stage,
+  (CASE
+    WHEN fr.status IN ('merged', 'converged') THEN 'ok'
+    WHEN fr.status = 'blocked' THEN 'blocked'
+    WHEN fr.status IN ('failed', 'skipped', 'abandoned') THEN 'failed'
+    ELSE NULL
+  END) AS stage_state,
+  (CASE
+    WHEN NOT (fr.converge IS NOT NULL AND fr.converge <> 0) THEN 'Converging Merging'
+    WHEN NOT (fr.auto_merge IS NOT NULL AND fr.auto_merge <> 0) THEN 'Merging'
+    ELSE ''
+  END) AS stage_skipped,
+  (CASE
+    WHEN EXISTS (
+      SELECT 1 FROM user_tasks ut
+      WHERE ut.subject_type = 'feature' AND ut.subject_key = fr.feature_key
+        AND ut.element_id = 'feature-blocked'
+    ) THEN 'blocked'
+    WHEN EXISTS (
+      SELECT 1 FROM user_tasks ut
+      WHERE ut.subject_type = 'feature' AND ut.subject_key = fr.feature_key
+        AND ut.element_id = 'feature-escalation'
+    ) THEN '⚠'
+    ELSE NULL
+  END) AS attention,
+  (CASE
+    WHEN fr.status IN ('merged', 'converged', 'blocked', 'failed', 'skipped', 'abandoned') AND fr.acknowledged_at IS NOT NULL THEN 'history'
+    ELSE 'active'
+  END) AS list_bucket
+FROM feature_runs fr;
+
+-- Supporting index for the correlated `attention` EXISTS lookups above. Each row of
+-- `feature_read_model` probes `user_tasks` by `(subject_type, subject_key, element_id)` (twice: once
+-- for `feature-blocked`, once for `feature-escalation`); the only prior index (034) is on
+-- `(element_id, updated_at)`, which does not front the equality on `subject_type`/`subject_key`, so a
+-- page reading many `feature_runs` rows would repeat a `user_tasks` scan per row. A composite index on
+-- the exact equality tuple turns each probe into an index seek. `IF NOT EXISTS` keeps the migration
+-- idempotent on any DB that already carries the index.
+CREATE INDEX IF NOT EXISTS idx_user_tasks_subject_element
+  ON user_tasks(subject_type, subject_key, element_id);

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -160,6 +160,11 @@ shared JSON contract means either can be swapped in later without touching the a
 
 ### 7. Submission is propose → preview → approve → dispatch, idempotent, over the self-describing endpoint
 
+> **Superseded — see the *Amendment (issue #460)* at the end of this section.** The `POST
+> /actions/start/delivery-graph` agent endpoint described in the following paragraph was **never
+> shipped and has been removed**; the agent surface ends at propose → compile → stage and dispatch is
+> operator-only. The paragraph below is retained as the original (Proposed) decision record.
+
 Graphs are submitted exactly as epics are today — via a **new (proposed)** `POST
 /actions/start/delivery-graph` endpoint (paths are relative to the agent guide's `__BASE__` prefix,
 matching the guide's style) with the JSON body, discovered via the agent guide (which already
@@ -174,6 +179,19 @@ at-least-once execution (mirroring the release workflow's `npx semantic-release`
 "skip already-published" discipline — `.github/workflows/release.yml`) so a
 resume cannot double-fire.
 
+> **Amendment (issue #460): dispatch is operator-only.** As implemented, the "approve → dispatch"
+> half of this decision is **not** an agent endpoint. The agent surface ends at **propose → compile →
+> stage**: the `POST /actions/compile-delivery-graph` door validates + previews the graph and, on
+> success, **stages** it as a proposal (a durable `delivery_graph_proposals` row, content-addressed by
+> `digest`, superseded per logical graph + TTL-bounded), returning only a preview + a navigational
+> `reviewUrl` — no run key, token, or PIK. A **human dispatches** the staged proposal from the cockpit's
+> Delivery Graphs page (`POST /actions/delivery-graph/dispatch` by `digest`, an operator route). The
+> originally-proposed agent `POST /actions/start/delivery-graph` door — where the same caller was handed
+> a content-addressed `approvalToken` to re-submit with — was **removed**: that "approval" was a
+> **replayable** digest returned to the approver, so any holder of the API credential self-approved.
+> Dispatch-by-absence (there is no agent start door) closes that hole categorically; the idempotent
+> at-most-once launch fence is retained on the operator dispatch path.
+
 ## Consequences
 
 - nwf gains a **generic delivery-graph runner** that composes its existing primitives; the motivating