@nanobpm/nano-workforce 0.123.2 → 0.124.0

package/app/deliveryGraphProposals.ts

@@ -0,0 +1,269 @@
+// app/deliveryGraphProposals.ts — the `staged` delivery-graph proposal AGGREGATE (ADR 0005 Decision 7,
+// issue #460). The seam that makes dispatch OPERATOR-ONLY: the agent-facing compile door persists a
+// valid compiled graph HERE as a `staged` proposal and hands the agent only a preview + a navigational
+// `reviewUrl`. There is no run key, token, or dispatch handle in that response — nothing the agent can
+// replay to start a run. A human previews the staged proposal in the cockpit and dispatches it.
+//
+// This dissolves the self-approval hole the old `approvalToken` left open: the token was a REPLAYABLE
+// content digest returned to the same caller, so any holder of the API credential self-approved. By
+// removing the dispatch affordance from the agent surface entirely (capability by absence, not by an
+// auth check), there is nothing to replay — the boundary becomes self-documenting.
+//
+// The pure helpers (`proposalLogicalKey`, `proposalExpiry`, `isProposalExpired`, `buildProposalPreview`,
+// `buildProposalRow`) are DB-free so they unit-test in isolation; `stageProposal` / `getStagedProposal`
+// supply the I/O and the supersede-by-logical-key + TTL semantics.
+
+import type { DataLayer } from "@nanobpm/urban";
+import type {
+  CompileDeliveryGraphResult,
+  DeliveryHumanStop,
+  DeliverySideEffect,
+} from "../nano-generated/api-io.d.ts";
+import { publicBaseUrl } from "./blackboard.ts";
+
+const now = () => new Date().toISOString();
+
+/** The staged-proposal TTL (24h). A staged proposal an operator never dispatches ages out of the
+ * cockpit list at `created_at + TTL`, so the surface only ever shows live, dispatchable proposals. */
+export const DELIVERY_PROPOSAL_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** The NAVIGATIONAL cockpit deep-link to a staged proposal — a pointer the agent can hand the human,
+ * NOT a dispatch handle. Points at the Delivery Graphs cockpit page (where the staged-proposals grid
+ * lives), fragment-scoped to the proposal's digest so the operator can find it. */
+export function proposalReviewUrl(digest: string, base: string = publicBaseUrl()): string {
+  return `${base}/app/pages/delivery-graphs#proposal-${encodeURIComponent(digest)}`;
+}
+
+/** The proposal lifecycle. `staged` = awaiting operator review/dispatch; `superseded` = replaced by a
+ * newer digest for the same logical graph; `dispatched` = the operator launched it; `expired` = it aged
+ * out of its TTL before an operator dispatched it. `superseded`/`dispatched`/`expired` all drop out of
+ * the cockpit's staged list (which filters to `status = 'staged'`). */
+export const DELIVERY_PROPOSAL_STATUSES = ["staged", "superseded", "dispatched", "expired"] as const;
+export type DeliveryProposalStatus = typeof DELIVERY_PROPOSAL_STATUSES[number];
+
+/** One staged delivery-graph proposal — the durable row keyed by content `digest`. `side_effecting`
+ * is a SQLite boolean (0/1); `graph`/`preview` are JSON text columns. */
+export interface DeliveryGraphProposal {
+  digest: string;
+  logical_key: string;
+  title: string | null;
+  /** The original `DeliveryGraph` JSON — retained so the cockpit dispatch action can run the previewed
+   * digest without the agent re-submitting anything. */
+  graph: string;
+  /** The rendered preview JSON (`{ diagram, sideEffects, humanNodes }`), stamped at stage time so the
+   * cockpit list renders without recompiling. */
+  preview: string;
+  node_count: number;
+  human_node_count: number;
+  side_effect_count: number;
+  side_effecting: number;
+  status: DeliveryProposalStatus;
+  created_at: string;
+  updated_at: string;
+  expires_at: string;
+}
+
+/** The rendered preview a staged proposal carries — the operator-facing view of WHAT the graph does
+ * (its diagram, the side effects a dispatch authorises, and where it parks on a person). It carries no
+ * dispatch handle by construction. */
+export interface DeliveryProposalPreview {
+  diagram: string;
+  sideEffects: DeliverySideEffect[];
+  humanNodes: DeliveryHumanStop[];
+}
+
+/** The `delivery_graph_proposals` aggregate accessor — the durable staged-proposal store keyed by
+ * content `digest`. */
+export const deliveryGraphProposals = (data: DataLayer) =>
+  data.table<DeliveryGraphProposal>("delivery_graph_proposals", "digest");
+
+/** The LOGICAL graph identity used to supersede: the graph's `name` (trimmed, when non-blank), else
+ * the content `digest`. A re-compile of a CHANGED graph (new digest) with the SAME name replaces the
+ * prior staged proposal; an unnamed graph is its own logical key (it supersedes only an identical
+ * recompile of itself). */
+export function proposalLogicalKey(name: string | undefined | null, digest: string): string {
+  const trimmed = typeof name === "string" ? name.trim() : "";
+  return trimmed || digest;
+}
+
+/** The TTL horizon for a proposal staged at `createdAt` — `createdAt + DELIVERY_PROPOSAL_TTL_MS`. */
+export function proposalExpiry(createdAtIso: string): string {
+  const created = Date.parse(createdAtIso);
+  const base = Number.isNaN(created) ? Date.now() : created;
+  return new Date(base + DELIVERY_PROPOSAL_TTL_MS).toISOString();
+}
+
+/** Whether a staged proposal has aged out (its `expires_at` is at or before `at`). A corrupt/blank
+ * `expires_at` is treated as expired so a bad row can never linger undismissable in the cockpit. */
+export function isProposalExpired(expiresAtIso: string | null | undefined, at: Date = new Date()): boolean {
+  if (typeof expiresAtIso !== "string" || expiresAtIso.trim() === "") return true;
+  const expires = Date.parse(expiresAtIso);
+  if (Number.isNaN(expires)) return true;
+  return expires <= at.getTime();
+}
+
+/** Extract the operator-facing preview from a successful compile — the diagram, the side effects a
+ * dispatch authorises, and the human stop-points. No BPMN, no digest handle beyond the content
+ * address; a preview, not a dispatch affordance. */
+export function buildProposalPreview(compiled: CompileDeliveryGraphResult): DeliveryProposalPreview {
+  return {
+    diagram: compiled.diagram,
+    sideEffects: compiled.sideEffects,
+    humanNodes: compiled.humanNodes,
+  };
+}
+
+/** Build the durable proposal row for a compiled graph at stage time. `graph` is the original
+ * `DeliveryGraph` JSON (serialised) the cockpit dispatch action re-runs; `createdAt` is preserved
+ * across an idempotent re-stage of a still-live proposal so the TTL stays anchored to the first stage
+ * (omit it — defaulting to now — to re-anchor the TTL when re-staging an already-expired digest). */
+export function buildProposalRow(input: {
+  digest: string;
+  logicalKey: string;
+  title: string | null;
+  graphJson: string;
+  preview: DeliveryProposalPreview;
+  nodeCount: number;
+  humanNodeCount: number;
+  sideEffectCount: number;
+  sideEffecting: boolean;
+  createdAt?: string;
+}): DeliveryGraphProposal {
+  const at = now();
+  const createdAt = input.createdAt ?? at;
+  return {
+    digest: input.digest,
+    logical_key: input.logicalKey,
+    title: input.title,
+    graph: input.graphJson,
+    preview: JSON.stringify(input.preview),
+    node_count: input.nodeCount,
+    human_node_count: input.humanNodeCount,
+    side_effect_count: input.sideEffectCount,
+    side_effecting: input.sideEffecting ? 1 : 0,
+    status: "staged",
+    created_at: createdAt,
+    updated_at: at,
+    expires_at: proposalExpiry(createdAt),
+  };
+}
+
+/** Persist a compiled graph as a `staged` proposal and SUPERSEDE any prior staged proposal for the
+* same logical graph. Idempotent on `digest` (a re-stage of an identical, still-live digest refreshes
+* `updated_at` but preserves `created_at`, so the TTL stays anchored to the first stage; a re-stage of
+* a digest that has already aged out re-anchors the TTL to now so it is dispatchable again). After the
+* upsert, every
+ * OTHER `staged` proposal sharing this `logical_key` is flipped to `superseded` — so the cockpit shows
+ * exactly one live proposal per logical graph (the latest digest the operator would dispatch). The
+ * supersede RECONCILES to the globally-newest staged row (`updated_at`, `digest`-tie-broken) rather than
+ * flipping only rows older than the just-written one, so concurrent stages of two different digests
+ * converge to EXACTLY ONE live proposal — never zero, and never two — regardless of arrival order. */
+export async function stageProposal(data: DataLayer, row: DeliveryGraphProposal): Promise<DeliveryGraphProposal> {
+  const table = deliveryGraphProposals(data);
+  const existing = await table.get(row.digest);
+  const toWrite = existing
+    ? buildProposalRow({
+        digest: row.digest,
+        logicalKey: row.logical_key,
+        title: row.title,
+        graphJson: row.graph,
+        preview: JSON.parse(row.preview),
+        nodeCount: row.node_count,
+        humanNodeCount: row.human_node_count,
+        sideEffectCount: row.side_effect_count,
+        sideEffecting: row.side_effecting === 1,
+        // Re-stage: if the existing row is STILL LIVE, preserve its original stage time so the TTL
+        // stays anchored to the first stage. But if it has already aged out of its TTL (or was
+        // dispatched/superseded long ago), reusing the stale `created_at` would yield a past
+        // `expires_at`, leaving the "re-staged" row immediately non-dispatchable (`getStagedProposal`
+        // rejects it as expired) while the preview claims it is staged. In that case re-anchor the TTL
+        // to now (omit `createdAt`) so a re-proposed digest is genuinely live again.
+        createdAt: isProposalExpired(existing.expires_at) ? undefined : existing.created_at,
+      })
+    : row;
+  if (existing) {
+    const { digest, ...patch } = toWrite;
+    await table.update(row.digest, patch);
+  } else {
+    await table.insert(toWrite);
+  }
+  // Reconcile to EXACTLY ONE live proposal per logical graph: supersede every `staged` row for this
+  // `logical_key` that has a strictly-NEWER staged sibling (by `updated_at`, with a deterministic
+  // `digest` tie-breaker), leaving only the globally-newest live. This is ORDER-INDEPENDENT — it never
+  // references the just-written digest, so it converges to a single live row regardless of the
+  // interleaving of concurrent stages. A supersede pass keyed to "only flip rows older than the one *I*
+  // just wrote" leaves TWO live proposals when an OLDER stage's pass runs AFTER a newer stage already
+  // committed (the older pass won't flip the newer row, and the newer pass ran before the older row
+  // existed) — and an unordered supersede-all leaves ZERO. Anchoring on the newest staged sibling avoids
+  // both: the newest row is never superseded (no newer sibling), so it stays staged throughout the
+  // statement and every older row's `EXISTS` is satisfied by it. Idempotent: a no-op once one row remains.
+  await data
+    .open()
+    .exec(
+      `UPDATE "delivery_graph_proposals" SET "status" = 'superseded', "updated_at" = ? WHERE "logical_key" = ? AND "status" = 'staged' AND EXISTS (SELECT 1 FROM "delivery_graph_proposals" AS "newer" WHERE "newer"."logical_key" = "delivery_graph_proposals"."logical_key" AND "newer"."status" = 'staged' AND ("newer"."updated_at" > "delivery_graph_proposals"."updated_at" OR ("newer"."updated_at" = "delivery_graph_proposals"."updated_at" AND "newer"."digest" > "delivery_graph_proposals"."digest")))`,
+      [now(), row.logical_key],
+    );
+  return toWrite;
+}
+
+/** Load a proposal that is live and dispatchable RIGHT NOW: it exists, is `staged` (not superseded or
+ * already dispatched), and has not aged out of its TTL. Returns null otherwise, so the cockpit
+ * dispatch action refuses a stale/unknown/already-dispatched digest cleanly. */
+export async function getStagedProposal(
+  data: DataLayer,
+  digest: string,
+  at: Date = new Date(),
+): Promise<DeliveryGraphProposal | null> {
+  const row = await deliveryGraphProposals(data).get(digest);
+  if (!row) return null;
+  if (row.status !== "staged") return null;
+  if (isProposalExpired(row.expires_at, at)) return null;
+  return row;
+}
+
+/** Mark a staged proposal `dispatched` once the operator launches it — it drops out of the cockpit's
+ * staged list (the run then shows in the in-flight grid). */
+export async function markProposalDispatched(data: DataLayer, digest: string): Promise<void> {
+  await deliveryGraphProposals(data).update(digest, { status: "dispatched", updated_at: now() });
+}
+
+/** Retire a proposal by flipping it to `expired` — its `graph` payload is unusable (e.g. corrupt JSON
+ * detected at dispatch), so it can never launch. Reuses the terminal `expired` status the sweep already
+ * uses, so a fail-closed retirement drops the row out of the cockpit's staged grid instead of leaving an
+ * undismissable `staged` row that fails every dispatch attempt the same way. */
+export async function markProposalExpired(data: DataLayer, digest: string): Promise<void> {
+  await deliveryGraphProposals(data).update(digest, { status: "expired", updated_at: now() });
+}
+
+/** Age out every `staged` proposal whose TTL has elapsed by flipping it to `expired`, so it drops out
+ * of the cockpit's staged grid (which filters to `status = 'staged'`). The grid's datasource filter can
+ * only express equality/set-membership — not an `expires_at > now` comparison — so an expired-but-still-
+ * `staged` row would otherwise linger in the list indefinitely, only to fail dispatch with "no live
+ * staged proposal". This reconciliation sweep (driven by the poller) is the single writer that realises
+ * the TTL, reusing the canonical `isProposalExpired` predicate so there is no second definition of
+ * "expired". Returns the number of proposals swept. Idempotent: a proposal already terminal (superseded/
+ * dispatched/expired) is left untouched.
+ *
+ * The expiry flip is a GUARDED UPDATE (`... WHERE digest=? AND status='staged'`), not a blind
+ * update-by-key. The initial `find()` and the per-row write are separate statements, so a proposal can
+ * be dispatched (or superseded) in the window between them; a blind `table.update(digest, …)` would
+ * clobber that newer terminal status back to `expired`, silently re-hiding a run the operator just
+ * launched. The `status='staged'` guard makes the write a no-op when the row has already moved on, and
+ * we count only rows that actually changed (`res.changed`) so the returned tally stays honest. */
+export async function sweepExpiredProposals(data: DataLayer, at: Date = new Date()): Promise<number> {
+  const table = deliveryGraphProposals(data);
+  const staged = await table.find({ status: "staged" });
+  const ts = now();
+  const db = data.open();
+  let swept = 0;
+  for (const row of staged) {
+    if (isProposalExpired(row.expires_at, at)) {
+      const res = await db.exec(
+        `UPDATE "delivery_graph_proposals" SET "status" = 'expired', "updated_at" = ? WHERE "digest" = ? AND "status" = 'staged'`,
+        [ts, row.digest],
+      );
+      swept += res.changed;
+    }
+  }
+  return swept;
+}

package/app/deliveryGraphRun.test.ts

@@ -1,9 +1,9 @@
-// Unit coverage for the S5 dispatch-door aggregate (ADR 0005 Decision 7) — the pure decision helpers
-// (the idempotency key, the approval gate, the parked human-label map, the derived parked-node phase),
-// plus the durable at-most-once launch-claim fence (`claimRunForLaunch`) exercised against the real
-// provisioned SQLite data layer so its actual `status <> 'running'` compare-and-swap SQL is validated,
-// not just modelled. The integration test (operations/startDeliveryGraph.integration.test.ts) proves
-// the COMPOSED behaviour at the edge.
+// Unit coverage for the delivery-graph run aggregate (ADR 0005 Decision 7) — the pure decision helpers
+// (the idempotency key, the parked human-label map, the derived parked-node phase), plus the durable
+// at-most-once launch-claim fence (`claimRunForLaunch`) exercised against the real provisioned SQLite
+// data layer so its actual `status <> 'running'` compare-and-swap SQL is validated, not just modelled.
+// The COMPOSED dispatch behaviour at the edge is proven by operations/dispatchDeliveryGraph.test.ts
+// and app/deliveryGraphDispatch.test.ts (the operator dispatch action).
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -21,8 +21,6 @@ import {
   DELIVERY_PHASE,
   deliveryGraphRuns,
   humanTaskElementId,
-  isDeliveryGraphApproved,
-  parkRunFencedAgainstLaunch,
   parseHumanLabels,
 } from "./deliveryGraphRun.ts";
 import { pollDeliveryGraphPhase } from "./service.ts";
@@ -124,36 +122,6 @@ test("pollDeliveryGraphPhase: a numeric engine processInstanceKey still matches
   });
 });
 
-// ── parkRunFencedAgainstLaunch: the approval-park write never clobbers a launched claim ────────────
-test("parkRunFencedAgainstLaunch: an approval-park write onto a launched `running` claim is a no-op — the at-most-once dispatch fence survives (no clobber back to awaiting-approval, no nulled process_key)", async () => {
-  await withData(async (data) => {
-    const runs = deliveryGraphRuns(data);
-    // A concurrent APPROVED submit already launched: the row is `running` with a live instance key.
-    await runs.insert({ ...claimRow("running"), process_key: "PI-1" });
-    // A racing UNAPPROVED submit that read the pre-launch row now tries to (re-)park it. The guarded
-    // write must refuse to overwrite the launched claim — otherwise a later re-submit double-launches.
-    await parkRunFencedAgainstLaunch(data, true, claimRow("awaiting-approval"));
-    const row = await runs.get("rk");
-    assertEquals(row?.status, "running"); // NOT clobbered back to awaiting-approval
-    assertEquals(row?.process_key, "PI-1"); // instance key preserved
-  });
-});
-
-test("parkRunFencedAgainstLaunch: a first park INSERTs the row; a park onto a still-parked row idempotently re-parks it (metadata refreshed, status stays awaiting-approval)", async () => {
-  await withData(async (data) => {
-    const runs = deliveryGraphRuns(data);
-    // First unapproved submit: no row yet → INSERT.
-    await parkRunFencedAgainstLaunch(data, false, claimRow("awaiting-approval"));
-    assertEquals((await runs.get("rk"))?.status, "awaiting-approval");
-    // A second unapproved submit onto the existing parked row: guarded UPDATE re-parks it (status is
-    // not `running`, so it applies) without duplicating the row.
-    await parkRunFencedAgainstLaunch(data, true, { ...claimRow("awaiting-approval"), digest: "d2" });
-    const row = await runs.get("rk");
-    assertEquals(row?.status, "awaiting-approval");
-    assertEquals(row?.digest, "d2");
-  });
-});
-
 // ── computeRunKey ─────────────────────────────────────────────────────────────
 test("computeRunKey: a non-blank caller key wins; a blank/absent key falls back to the digest", () => {
   assertEquals(computeRunKey("run-1", "digestX"), "run-1");
@@ -164,20 +132,6 @@ test("computeRunKey: a non-blank caller key wins; a blank/absent key falls back
   assertEquals(computeRunKey(undefined, "digestX"), "digestX");
 });
 
-// ── isDeliveryGraphApproved ───────────────────────────────────────────────────
-test("isDeliveryGraphApproved: a non-side-effecting graph needs no approval", () => {
-  assertEquals(isDeliveryGraphApproved(false, null, "d"), true);
-  assertEquals(isDeliveryGraphApproved(false, "wrong", "d"), true);
-});
-
-test("isDeliveryGraphApproved: a side-effecting graph dispatches ONLY with the matching content token", () => {
-  assertEquals(isDeliveryGraphApproved(true, "d", "d"), true);
-  assertEquals(isDeliveryGraphApproved(true, "  d  ", "d"), true); // trimmed
-  assertEquals(isDeliveryGraphApproved(true, "wrong", "d"), false);
-  assertEquals(isDeliveryGraphApproved(true, null, "d"), false);
-  assertEquals(isDeliveryGraphApproved(true, "", "d"), false);
-});
-
 // ── buildHumanLabels / parseHumanLabels ───────────────────────────────────────
 test("buildHumanLabels: maps each human node's compiled user-task element id → its instruction label", async () => {
   const graph = {

package/app/deliveryGraphRun.ts

@@ -1,23 +1,27 @@
-// app/deliveryGraphRun.ts — the `startDeliveryGraph` run AGGREGATE (ADR 0005 Decision 7, slice S5).
+// app/deliveryGraphRun.ts — the delivery-graph run AGGREGATE (ADR 0005 Decision 7).
 //
-// 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 cockpit dispatch action (`app/deliveryGraphDispatch.ts`, invoked from `dispatchDeliveryGraph`)
+// turns a staged, agent-authored `DeliveryGraph` into a RUNNING engine-native process (via the S4
+// runner). Because these graphs merge PRs and publish packages, dispatch must be idempotent and
+// at-most-once. This module is the durable aggregate that makes that true and gives the cockpit a row
+// to show WHERE a run is:
 //
 //   • 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
+//     content digest). A re-dispatch 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 content digest — `digest` is the content-address of the compiled definition, persisted so
+//     the cockpit and reconcilers can relate a run to the proposal it came from.
 //   • 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.
+// The pure helpers here (`computeRunKey`, `buildHumanLabels`, `deriveDeliveryPhase`) are engine/DB-free
+// so they unit-test in isolation; the dispatch action and the poller supply the I/O.
+//
+// NOTE (issue #460): the `awaiting-approval` status remains a RESERVED member of the lifecycle union
+// (like `abandoned`) but is no longer produced — dispatch is now an operator action in the cockpit, so
+// there is no agent-facing approval gate to park a run at. The old replayable `approvalToken` and the
+// approval-park write were removed with the agent `start` door.
 
 import type { DataLayer, ProcessInstanceState } from "@nanobpm/urban";
 import type { CompileDeliveryGraphResult } from "../nano-generated/api-io.d.ts";
@@ -26,7 +30,7 @@ import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.
 
 const now = () => new Date().toISOString();
 
-/** One `startDeliveryGraph` run — the durable row. `side_effecting` is a SQLite boolean (0/1). */
+/** One delivery-graph run — the durable row. `side_effecting` is a SQLite boolean (0/1). */
 export interface DeliveryGraphRun {
   run_key: string;
   process_key: string | null;
@@ -45,8 +49,9 @@ export interface DeliveryGraphRun {
   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. */
+/** The run lifecycle. `awaiting-approval` is RESERVED but no longer produced (issue #460 moved dispatch
+ * to an operator action, so runs are only ever created at launch) — kept in the union to preserve the
+ * durable enum. `running` = dispatched to the engine; `done`/`failed`/`abandoned` = terminal. */
 export const DELIVERY_GRAPH_RUN_STATUSES = [
   "awaiting-approval",
   "running",
@@ -142,74 +147,14 @@ export async function claimRunForLaunch(
   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
+ * present and non-blank, else the graph's content `digest`. So two dispatches 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 {

package/app/deliveryGraphText.ts

@@ -1,9 +1,9 @@
 // app/deliveryGraphText.ts — the shared PARSE step for the human-facing UI JSON-paste ingress
 // (issue #386, ADR 0005). The Delivery Graphs page (`pages/delivery-graphs.page.json`) submits the
 // operator's pasted delivery-graph as a raw JSON STRING (`graphJson`) — the page's text field cannot
-// submit a structured object — so the preview/dispatch ingress operations parse it here before handing
-// the resulting object to the SAME pure `compileDeliveryGraph` compiler / gated `startDeliveryGraph`
-// door the agent-facing paths use. This is a UI text adapter, NOT a parallel compile/dispatch path.
+// submit a structured object — so the preview+stage ingress operation parses it here before handing
+// the resulting object to the SAME pure `compileDeliveryGraph` compiler the agent-facing compile door
+// uses. This is a UI text adapter, NOT a parallel compile path.
 //
 // PURE and I/O-free so it unit-tests in isolation. A blank field, non-JSON text, or a non-object JSON
 // value maps to a clean `{ ok:false, error }` the ingress surfaces as a 400 with a human banner —

package/app/deliveryRunner.ts

@@ -20,9 +20,10 @@ import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery } from "./readiness.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. */
+ * content-addressed deploy id (`delivery-graph-<digest>`) AND the dispatch fence's default idempotency
+ * key + the staged-proposal primary key. The runner (deploy id), `app/deliveryGraphDispatch` (dedupe
+ * key), and `app/deliveryGraphProposals` (proposal digest) all derive from THIS one function so they
+ * 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);
 }

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";
@@ -2304,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,
@@ -2479,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/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/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