@nanobpm/nano-workforce 0.134.0 → 0.136.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.136.0](https://github.com/nanobpm/nano-workforce/compare/v0.135.0...v0.136.0) (2026-08-24)
+
+### Features
+
+* **delivery:** agent-node classifier-emit contract so S7 guarded branches fire ([#506](https://github.com/nanobpm/nano-workforce/issues/506)) ([#509](https://github.com/nanobpm/nano-workforce/issues/509)) ([f3acd5b](https://github.com/nanobpm/nano-workforce/commit/f3acd5bd5977fe3b12797f7d1e3acb7d5e67eb8c))
+
+### Bug Fixes
+
+* **deps:** update dependency @nanobpm/urban to ^0.82.0 ([#482](https://github.com/nanobpm/nano-workforce/issues/482)) ([81decc1](https://github.com/nanobpm/nano-workforce/commit/81decc1b8ebd53b2835aaecbb369c5347371ceb3))
+
+## [0.135.0](https://github.com/nanobpm/nano-workforce/compare/v0.134.0...v0.135.0) (2026-08-24)
+
+### Features
+
+* **delivery-graph:** preview DI for agent-staged proposals ([#511](https://github.com/nanobpm/nano-workforce/issues/511)) ([#513](https://github.com/nanobpm/nano-workforce/issues/513)) ([34f0950](https://github.com/nanobpm/nano-workforce/commit/34f0950fdbb7a9eec9e09d6f84cff46de09ea830))
+
 ## [0.134.0](https://github.com/nanobpm/nano-workforce/compare/v0.133.1...v0.134.0) (2026-08-24)
 
 ### Features

package/app/deliveryGraphDeploy.test.ts

@@ -277,6 +277,110 @@ test("S7 deploy+route: the green default branch SKIPS `migrate` and rides the el
   assert(r.releaseRan, "the green outcome still reaches `release` via the else-flow (proof the exclusive merge fires on one token)");
 });
 
+// ── #506: the REAL agentic-worker classifier-emit contract drives a guarded split ──────────────────
+// The S7 stubs above (`() => ({ result: outcome })`) prove the ENGINE routes on a published fact, but a
+// bare `{ result }` is NOT what a real `senior:*` fleet agent returns — it completes with the whole
+// Output-contract envelope (`{ status, summary, pr, … }`) and never a bare fact. So the gap #506 closes
+// is: (a) the node's declared `emits` must be threaded into the agent's `appendPrompt` so a real agent
+// is TOLD to surface the fact, and (b) the fact rides that SAME envelope as an extra top-level field.
+// This graph proves both against the real engine: the `adopt` node declares `emits: [result]` and is
+// serviced by a worker that (1) ASSERTS the emit contract reached it via `appendPrompt` — proving the
+// runner actually delivers the instruction, not a test stub — and (2) returns the full envelope with the
+// fact folded in, exactly as a contract-following agent would. Both branches are driven end to end.
+const GUARDED_ADOPT_REAL: DeliveryGraph = {
+  name: "adopt runbook (real agent)",
+  nodes: [
+    {
+      id: "adopt",
+      kind: "agent",
+      agent: { jobType: "senior:feature", prompt: "Adopt the published package into this consumer and open a PR." },
+      emits: [{ name: "result", type: "string", description: "breaking | compatible" }],
+    },
+    { id: "migrate", kind: "agent", agent: { jobType: "senior:migrate" } },
+    { id: "release", kind: "connector", connector: { target: "npm:publish", dedupeKey: "rel-real-1" } },
+  ],
+  edges: [
+    { from: "adopt", to: "migrate", when: "adopt.result", equals: "breaking" },
+    { from: "adopt", to: "release", default: true },
+    { from: "migrate", to: "release" },
+  ],
+};
+
+/** Drive `GUARDED_ADOPT_REAL` with a worker that behaves like a REAL contract-following `senior:feature`
+ *  agent: it reads the emit contract the runner threaded into its `appendPrompt`, then completes with the
+ *  full Output-contract envelope carrying the classifier fact as a top-level field. Returns whether the
+ *  contract actually reached the agent, plus which branches ran. */
+async function driveGuardedRealAgent(outcome: "breaking" | "compatible"): Promise<{
+  state: string;
+  contractDelivered: boolean;
+  factSurfaced: boolean;
+  migrateRan: boolean;
+  releaseRan: boolean;
+}> {
+  const engine = await createWasmEngineClient();
+  try {
+    let contractDelivered = false;
+    let factSurfaced = false;
+    let migrateRan = false;
+    let releaseRan = false;
+
+    await engine.registerWorker("senior:feature", async (job) => {
+      const appendPrompt = String((job.variables as Record<string, unknown> | undefined)?.appendPrompt ?? "");
+      // (a) The classifier emit contract MUST have reached the agent via its steering channel — this is
+      //     the #506 fix (a plain `senior:feature` seed would carry no such instruction).
+      contractDelivered =
+        appendPrompt.includes("Classifier emit contract") &&
+        appendPrompt.includes("`result`") &&
+        appendPrompt.includes("AGENT_RESULT_FILE");
+      factSurfaced = appendPrompt.includes("`result`");
+      // (b) A real agent completes with the WHOLE Output-contract envelope, folding the declared fact in
+      //     as an extra top-level field — NOT a bare `{ result }` stub.
+      return { status: "opened", summary: `adopt done (${outcome})`, pr: "owner/repo#900", result: outcome };
+    });
+    await engine.registerWorker("senior:migrate", async () => {
+      migrateRan = true;
+      return { status: "opened", summary: "migrated", pr: "owner/repo#901" };
+    });
+    await engine.registerWorker(DELIVERY_CONNECTOR_TASK_TYPE, async () => {
+      releaseRan = true;
+      return {};
+    });
+
+    const run = await runDeliveryGraph(engine, GUARDED_ADOPT_REAL);
+    assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
+    const key = run.handle.processInstanceKey;
+
+    let state = "?";
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+      await engine.drain();
+      const [pi] = await engine.searchProcessInstances({ processInstanceKeys: [key] });
+      assert(pi, `no process instance snapshot for ${key}`);
+      state = pi.state ?? "?";
+      if (state === "COMPLETED" || state === "TERMINATED") break;
+    }
+    return { state, contractDelivered, factSurfaced, migrateRan, releaseRan };
+  } finally {
+    await engine.close();
+  }
+}
+
+test("#506 deploy+route: a REAL contract-following agent's envelope carries the classifier fact and routes the BREAKING branch through `migrate`", async () => {
+  const r = await driveGuardedRealAgent("breaking");
+  assert(r.contractDelivered, "the emit contract must reach the agent via its threaded appendPrompt (the #506 fix)");
+  assert(r.factSurfaced, "the declared fact must be named to the agent");
+  assertEquals(r.state, "COMPLETED", "the breaking branch must run to a COMPLETED instance");
+  assert(r.migrateRan, "the breaking outcome (returned inside the real Output-contract envelope) must route through `migrate`");
+  assert(r.releaseRan, "both branches must re-converge on `release`");
+});
+
+test("#506 deploy+route: the SAME real agent returning `compatible` in its envelope rides the default flow, SKIPPING `migrate`", async () => {
+  const r = await driveGuardedRealAgent("compatible");
+  assert(r.contractDelivered, "the emit contract must reach the agent via its threaded appendPrompt (the #506 fix)");
+  assertEquals(r.state, "COMPLETED", "the compatible branch must run to a COMPLETED instance");
+  assert(!r.migrateRan, "the compatible outcome must NOT route through `migrate` — the envelope's `result` rides the default flow");
+  assert(r.releaseRan, "the compatible outcome still reaches `release` via the else-flow");
+});
+
 test("S7 deploy+route: mutually-exclusive leaves join End on an exclusive merge — the untaken leaf never blocks completion", async () => {
   // Mode D: `adopt` routes a missing surface to an escalate (human) leaf, else to a `done` connector
   // leaf. On the default path the escalate leaf never fires; an exclusive End merge must still let the

package/app/deliveryGraphProposals.ts

@@ -221,6 +221,22 @@ export async function getStagedProposal(
   return row;
 }
 
+/** Every LIVE staged proposal — `status = 'staged'` AND not aged out of its TTL — newest first. The
+ * staged App-View (`pages/delivery-graphs/staged.mount.js`) polls this to render the Preview-DI +
+ * Dispatch list. Mirrors `getStagedProposal`'s freshness guard (`isProposalExpired`) so an
+ * expired-but-not-yet-swept row is never offered for preview/dispatch, unlike a raw
+ * `status = 'staged'` datasource filter which cannot express a `expires_at > now` cutoff and so lingers
+ * an aged-out row until the sweep realises the TTL. Read-only; no write. */
+export async function listStagedProposals(
+  data: DataLayer,
+  at: Date = new Date(),
+): Promise<DeliveryGraphProposal[]> {
+  const rows = await deliveryGraphProposals(data).find({ status: "staged" });
+  return rows
+    .filter((row) => !isProposalExpired(row.expires_at, at))
+    .sort((a, b) => b.created_at.localeCompare(a.created_at));
+}
+
 /** 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> {

package/app/deliveryRunner.test.ts

@@ -119,6 +119,39 @@ test("the human node seeds prompt/nodeId/emits; a click-done (no-emit, no-prompt
   assertEquals(ack?.nodeId, "ack");
 });
 
+test("agent node classifier-emit contract (#506): a declared `emits` threads the emit instruction into appendPrompt; a no-emit node leaves it untouched", async () => {
+  // #506: a guarded split (S7) routes on a producer's emitted scalar, published from the engine
+  // variable named exactly after the fact. A real `senior:*` agent completes with the Output-contract
+  // envelope and would never return that fact unless TOLD — so an agent node that declares `emits`
+  // must carry the emit contract in its `appendPrompt` (its only steering channel), while a plain
+  // implementation node (no emits) must be byte-for-byte unchanged.
+  const graph: DeliveryGraph = {
+    name: "classifier",
+    nodes: [
+      { id: "adopt", kind: "agent", agent: { jobType: "senior:feature", prompt: "adopt the package" }, emits: [{ name: "result", type: "string", description: "breaking | compatible" }] },
+      { id: "plain", kind: "agent", agent: { jobType: "senior:feature", prompt: "just implement it" } },
+    ],
+    edges: [{ from: "adopt.result", to: "plain", when: "adopt.result", equals: "breaking" }, { from: "adopt", to: "plain", default: true }],
+  };
+  const p = await prepareOk(graph);
+  const agents = Object.values(p.nodeInputs).filter((v) => "jobType" in v) as Array<Record<string, unknown>>;
+  const adopt = agents.find((v) => String(v.appendPrompt).startsWith("adopt the package"));
+  const plain = agents.find((v) => String(v.appendPrompt).startsWith("just implement it"));
+
+  // The emit-declaring node keeps its authored prompt AND gains the emit contract naming its fact.
+  assert(adopt, "the emit-declaring agent node must be seeded");
+  const adoptPrompt = String(adopt?.appendPrompt);
+  assert(adoptPrompt.startsWith("adopt the package"), "the authored prompt is preserved as the prefix");
+  assert(adoptPrompt.includes("Classifier emit contract"), `the emit contract must be threaded in, got: ${adoptPrompt}`);
+  assert(adoptPrompt.includes("`result`") && adoptPrompt.includes("(string)"), "the declared fact name + type must be surfaced to the agent");
+  assert(adoptPrompt.includes("breaking | compatible"), "the fact's optional description rides the contract");
+  assert(adoptPrompt.includes("AGENT_RESULT_FILE"), "the contract names the completion channel the fact rides");
+
+  // A node that declares NO facts is untouched — appendPrompt is exactly the authored prompt.
+  assertEquals(plain?.appendPrompt, "just implement it");
+});
+
+
 test("wait gateKeys default to a fresh per-run token so concurrent runs of one graph never cross-correlate", async () => {
   const gateKeyOf = (p: Awaited<ReturnType<typeof prepareOk>>) =>
     (Object.values(p.nodeInputs).find((v) => "gateKey" in v) as { gateKey?: string } | undefined)?.gateKey;

package/app/deliveryRunner.ts

@@ -170,6 +170,39 @@ function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
     .replace(`bpmnElement="${DELIVERY_GRAPH_PROCESS_ID}"`, `bpmnElement="${processDefinitionId}"`);
 }
 
+/** Render the classifier-emit contract appended to an `agent` node's `appendPrompt` (issue #506) — the
+ * instruction that turns a declared `emits[]` into completion variables a downstream guarded split (S7)
+ * can route on. A `senior:*` fleet agent completes with the Output-contract envelope (`status`,
+ * `summary`, `pr`, …); the delivery output ioMapping instead publishes the engine variable named exactly
+ * after each fact (`factSourceVar` → `fact.name`), so the agent must ALSO return each declared fact as a
+ * TOP-LEVEL field of that same result JSON. This block tells it so, deriving entirely from the node's
+ * declared `emits` (no second source of truth). Empty for a no-emit node → the prompt is unchanged, so a
+ * plain implementation node behaves exactly as before. Deterministic: fixed wording, facts in declared
+ * order, so identical graphs still compile+seed byte-identically. */
+export function renderEmitContract(emits: readonly DeliveryFact[]): string {
+  if (emits.length === 0) return "";
+  const facts = emits.map((f) => `- \`${f.name}\` (${f.type})${f.description ? ` — ${f.description}` : ""}`);
+  return [
+    "",
+    "",
+    "---",
+    "",
+    "## Classifier emit contract (delivery graph)",
+    "",
+    "This node is a PRODUCER in a delivery graph: a downstream **guarded split** routes on the typed",
+    "fact(s) below. In ADDITION to your normal result fields (`status`, `summary`, `pr`, …), the",
+    "structured result you write to `AGENT_RESULT_FILE` MUST include these TOP-LEVEL fields, each a",
+    "bare scalar of the declared type:",
+    "",
+    ...facts,
+    "",
+    "The value you return for each fact IS the routing decision — a downstream edge fires only when the",
+    "fact equals a specific literal, otherwise the graph takes the `default` (else) branch. If you",
+    "genuinely cannot determine a fact, OMIT it (the default branch is taken) rather than guessing.",
+  ].join("\n");
+}
+
+
 /** Build the `nodeInputs.<element>` seed for one node, per its kind — the exact fields the compiled
  * subProcess ioMapping pulls. Total over the closed kind set. */
 function buildNodeInput(
@@ -177,8 +210,21 @@ function buildNodeInput(
   ctx: { runKey: string; element: string; nodeTimeout: string; probeTimeout: string; probePollEvery: string; escalationSlaTimeout: string; escalationAssignee: string | null },
 ): NodeInput {
   switch (node.kind) {
-    case "agent":
-      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
+    case "agent": {
+      // Classifier-emit contract (issue #506). A `senior:*` fleet agent's real completion is the
+      // Output-contract envelope (`{ status, summary, pr, … }`) — it does NOT return a bare fact, so a
+      // node's declared `emits` would never appear and a downstream GUARDED split (S7) could only ever
+      // take its `default` branch. Close the gap the same way `factSourceVar` already reads it: the
+      // output ioMapping publishes the engine variable named exactly after each fact, so the agent must
+      // return `{ <fact>: <value> }` AS A TOP-LEVEL field of its result JSON (the same channel that
+      // carries `status`/`summary`/`pr`). The agent only knows to do this if it is TOLD — so the
+      // declared emits are rendered into the node's `appendPrompt` (its sole steering channel; the
+      // delivery agent node carries no base-prompt resource), keeping `emits` the single source of
+      // truth. A no-emit node appends nothing, so a plain implementation node is unchanged.
+      const basePrompt = node.agent.prompt ?? "";
+      const emits = Array.isArray(node.emits) ? node.emits.map((f) => ({ ...f })) : [];
+      return { jobType: node.agent.jobType, appendPrompt: basePrompt + renderEmitContract(emits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
+    }
     case "wait": {
       const probe = parseProbe(node.wait);
       return {

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

@@ -268,6 +268,32 @@ resume cannot double-fire.
 > Determinism is preserved: gateway ids are positional over id-sorted nodes, so a graph with no guards
 > compiles byte-for-byte as before.
 
+> **Amendment (issue #506): the agent-node classifier-emit contract.** S7 (above) routes a guarded
+> split on a producer's emitted scalar, published to `<producerElement>_<fact>` by the node's output
+> ioMapping — which, for an `agent`/`connector` node, reads the engine variable named exactly after the
+> fact (`factSourceVar` → `fact.name`). A REAL `senior:*` fleet agent, though, completes with its
+> **Output-contract envelope** (`{ status, summary, pr, question, delta }`) and never a bare
+> `{ <fact>: <value> }`, so a guarded split authored on a `senior:feature` node compiled + was
+> deadlock-safe (the `default` else-flow fires when the fact is unset) but its non-default branch was
+> **inert** — the migrate/escalate arm never fired. The contract that closes this:
+> - An `agent` node's declared `emits[]` is threaded into the node's `appendPrompt` (its sole steering
+>   channel — the delivery agent node carries no base-prompt resource) as a **classifier emit contract**
+>   block (`deliveryRunner.renderEmitContract`), instructing the servicing agent to ALSO return each
+>   declared fact as a **top-level field** of its result JSON — the very same `AGENT_RESULT_FILE`
+>   channel that already carries `status`/`summary`/`pr`. The fleet harness merges that JSON into the
+>   job completion variables, so `<fact.name>` lands in scope exactly where the output ioMapping reads
+>   it. `emits` stays the single source of truth: the contract text is derived from it, never a parallel
+>   declaration.
+> - The convention a graph author relies on: declare `emits: [{ name, type }]` on the agent node and
+>   guard the downstream edge with `when: "<node>.<name>"` + `equals: <literal>`; a contract-following
+>   agent returns `{ …, <name>: <value> }` and the split routes on it. Omitting the fact (the agent
+>   could not decide) takes the `default` branch — the deadlock-safe fallback S7 already guarantees.
+> - A no-emit agent node appends nothing, so a plain implementation node is byte-for-byte unchanged.
+>   The `deploy+route` coverage now drives BOTH branches with a **real contract-following worker** (it
+>   asserts the emit contract reached it via `appendPrompt`, then completes with the full envelope
+>   carrying the fact), not a bare-`{ result }` stub — proving the instruction is actually delivered and
+>   the real completion shape routes.
+
 ## Open questions
 
 - **Compiler target for the first cut** — confirm compile-to-native (diagram + native scheduling) vs a

package/docs/agent-guide.md

@@ -448,6 +448,23 @@ A **typed fact** (`emits[]` entry) is `{ name, type, description? }` where
 downstream as `<nodeId>.<name>`. A "click done" human node or a pass-through node declares
 no facts.
 
+**Guarded routing + the agent classifier-emit contract.** An edge may carry a **guard** —
+`when: "<nodeId>.<fact>"` + `equals: <scalar>` — or be the split's single `default: true`
+else-branch (S7). A node whose out-edges are guarded is a **data-based exclusive split**: at
+runtime exactly one branch fires, chosen by the producer's emitted fact. For an **`agent`**
+node the fact is late-bound from the servicing job's completion: the delivery output-mapping
+publishes the engine variable named **exactly after the fact** (e.g. a fact `result` reads the
+completion variable `result`). A real `senior:*` fleet agent completes with its **Output
+contract** envelope (`{ status, summary, pr, question, delta }`), so — to make a guarded split
+fire — an agent node that declares `emits` has a **classifier emit contract** automatically
+appended to its prompt at dispatch: the agent MUST return each declared fact as an **extra
+top-level field of the same result JSON** (the `AGENT_RESULT_FILE` it already writes
+`status`/`summary`/`pr` to). Author side, this means: declare `emits: [{ name, type }]` on the
+agent node and guard the downstream edge on `<node>.<name>`; a contract-following agent returns
+`{ …, <name>: <value> }` and the split routes on it. If the agent cannot decide the fact it
+**omits** it, and the split takes its `default` (else) branch — the deadlock-safe fallback. A
+node that declares no `emits` gets no contract text and behaves exactly as before.
+
 ### 9.2 The agent loop: draft → compile → stage → ask an operator to dispatch
 
 ```

package/openapi.yaml

@@ -1392,7 +1392,17 @@ components:
           properties:
             id: { type: string }
             kind: { type: string, enum: [agent] }
-            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            emits:
+              type: array
+              items: { $ref: "#/components/schemas/DeliveryFact" }
+              description: >-
+                The typed facts this agent node hands forward (issue #506 — the classifier-emit
+                contract). Each declared fact is appended to the node's dispatch prompt as an
+                instruction the servicing `senior:*` agent MUST honour: return the fact as an extra
+                TOP-LEVEL field of its result JSON (the same `AGENT_RESULT_FILE` envelope that carries
+                `status`/`summary`/`pr`). The delivery output-mapping publishes that completion variable
+                (named exactly after the fact) so a downstream guarded edge (`when: "<node>.<fact>"` +
+                `equals`) routes on it; an omitted fact takes the split's `default` branch.
             agent:
               type: object
               additionalProperties: false
@@ -1673,6 +1683,62 @@ components:
             The compiled BPMN 2.0 XML INCLUDING diagram interchange (`bpmndi:BPMNDiagram`), recompiled
             deterministically from the staged graph — byte-identical to what a dispatch would deploy.
             Rendered read-only in the host explorer's definition preview. Nothing is deployed.
+    StagedProposalSummary:
+      description: >-
+        One LIVE staged delivery-graph proposal (issue #511) — the metadata the staged App-View renders
+        as a Preview-DI + Dispatch row. A projection of the durable `delivery_graph_proposals` row; the
+        `graph`/`preview` payloads are omitted (the App-View recompiles by `digest` for the DI preview).
+      type: object
+      additionalProperties: false
+      required:
+        - digest
+        - title
+        - nodeCount
+        - humanNodeCount
+        - sideEffectCount
+        - sideEffecting
+        - createdAt
+        - expiresAt
+      properties:
+        digest:
+          type: string
+          description: The proposal's content digest — the handle the Preview-DI and Dispatch doors take.
+        title:
+          type: string
+          nullable: true
+          description: The graph's name, when it carried one.
+        nodeCount:
+          type: integer
+          description: Total nodes in the compiled graph.
+        humanNodeCount:
+          type: integer
+          description: How many nodes park on a person.
+        sideEffectCount:
+          type: integer
+          description: How many nodes perform a side effect (merge/publish) once dispatched.
+        sideEffecting:
+          type: boolean
+          description: True when the graph has any side-effecting node — dispatching it authorises those actions.
+        createdAt:
+          type: string
+          description: When the proposal was staged (ISO-8601).
+        expiresAt:
+          type: string
+          description: When the proposal ages out of its TTL if never dispatched (ISO-8601).
+    StagedProposalList:
+      description: The live staged delivery-graph proposals awaiting dispatch (issue #511), newest first.
+      type: object
+      additionalProperties: false
+      required:
+        - count
+        - proposals
+      properties:
+        count:
+          type: integer
+        proposals:
+          type: array
+          items:
+            $ref: "#/components/schemas/StagedProposalSummary"
     DeliveryGraphTextResult:
       description: >-
         The delivery-graph text-ingress outcome (issue #460) — a single shape covering the JSON-paste
@@ -2927,6 +2993,32 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/DeliveryGraphProposalBpmnResult"
+  /delivery-graph/staged:
+    get:
+      operationId: listStagedProposals
+      summary: List the LIVE staged delivery-graph proposals awaiting dispatch (issue #511), newest first.
+      description: >-
+        The read behind the staged-proposals App-View: every `staged` delivery-graph proposal that has
+        not aged out of its TTL, newest first, projected to the Preview-DI + Dispatch metadata (the
+        `graph`/`preview` payloads are omitted — the App-View recompiles by `digest` for the DI preview).
+        Mirrors the `previewProposalBpmn`/`dispatchDeliveryGraph` freshness guard so an expired-but-not-
+        yet-swept row is never listed. Read-only.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The live staged proposals.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StagedProposalList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/start/feature:
     post:
       operationId: startFeature

package/operations/listStagedProposals.test.ts

@@ -0,0 +1,159 @@
+// Integration coverage for GET /app/api/delivery-graph/staged operation `listStagedProposals` (issue
+// #511) — the read behind the Staged proposals App-View. It lists every LIVE staged delivery-graph
+// proposal (not aged out of its TTL), newest first, projected to the Preview-DI + Dispatch metadata.
+// These tests drive the REAL door through `bootTestApp`'s api driver: stage via the compile door, then
+// list; assert the staged proposal appears with its counts, that dispatching drops it off the list, and
+// that the `graph`/`preview` payloads are NOT leaked into the lean list projection.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { noopLog } from "../test/log.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GITHUB_ENV: Record<string, string> = { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "" };
+
+const SIDE_EFFECTING = {
+  name: "release runbook",
+  nodes: [
+    { id: "open-b", kind: "agent", agent: { jobType: "senior:demo", prompt: "un-draft + merge #B" } },
+    { id: "cut", kind: "agent", agent: { jobType: "senior:demo", prompt: "cut the release" } },
+  ],
+  edges: [{ from: "open-b", to: "cut" }],
+};
+
+const WAIT_ONLY = {
+  name: "soak only",
+  nodes: [
+    { id: "soak", kind: "wait", wait: { kind: "github-check", target: "owner/repo@main" } },
+    { id: "done", kind: "human", human: { prompt: "Confirm the soak looked clean." } },
+  ],
+  edges: [{ from: "soak", to: "done" }],
+};
+
+interface StagedProposalSummary {
+  digest: string;
+  title: string | null;
+  nodeCount: number;
+  humanNodeCount: number;
+  sideEffectCount: number;
+  sideEffecting: boolean;
+  createdAt: string;
+  expiresAt: string;
+}
+type ListResponse = { count: number; proposals: StagedProposalSummary[] };
+
+describe("listStagedProposals — the live staged-proposals list", () => {
+  const dirs: string[] = [];
+  const apps: TestApp[] = [];
+  after(async () => {
+    for (const app of apps) await app.stop?.();
+    for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  });
+  const boot = async (): Promise<TestApp> => {
+    const d = mkdtempSync(join(tmpdir(), "nwf-list-staged-"));
+    dirs.push(d);
+    const app = await bootTestApp(APP_ROOT, { env: { ...GITHUB_ENV, NANO_APP_DB_URL: `file:${join(d, "app.db")}` } });
+    apps.push(app);
+    return app;
+  };
+
+  test("no staged proposals → 200 with an empty list", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const res = await app.api.call<ListResponse>("listStagedProposals", {});
+    assert.equal(res.status, 200);
+    assert.equal(res.body.count, 0);
+    assert.deepEqual(res.body.proposals, []);
+  });
+
+  test("a staged graph appears with its projected counts; no graph/preview payload is leaked", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SIDE_EFFECTING });
+    const digest = staged.body.digest;
+
+    const res = await api.call<ListResponse>("listStagedProposals", {});
+    assert.equal(res.status, 200);
+    assert.equal(res.body.count, 1);
+    const row = res.body.proposals[0];
+    assert.equal(row.digest, digest);
+    assert.equal(row.title, "release runbook");
+    assert.equal(row.nodeCount, 2);
+    assert.equal(row.humanNodeCount, 0);
+    assert.equal(row.sideEffectCount, 2);
+    assert.equal(row.sideEffecting, true);
+    assert.ok(typeof row.createdAt === "string" && row.createdAt.length > 0);
+    assert.ok(typeof row.expiresAt === "string" && row.expiresAt.length > 0);
+    // The list is a lean projection — the heavy graph/preview JSON is NOT included (the App-View
+    // recompiles by digest through previewProposalBpmn for the DI preview).
+    assert.ok(!("graph" in row), "the list must not leak the stored graph JSON");
+    assert.ok(!("preview" in row), "the list must not leak the stored preview JSON");
+  });
+
+  test("a wait/human-only graph is reported as not side-effecting", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    await api.call<{ digest: string }>("compileDeliveryGraph", { body: WAIT_ONLY });
+    const res = await api.call<ListResponse>("listStagedProposals", {});
+    assert.equal(res.body.count, 1);
+    const row = res.body.proposals[0];
+    assert.equal(row.sideEffecting, false);
+    assert.equal(row.sideEffectCount, 0);
+    assert.equal(row.humanNodeCount, 1);
+  });
+
+  test("dispatching a staged proposal drops it off the live list", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SIDE_EFFECTING });
+    const digest = staged.body.digest;
+    assert.equal((await api.call<ListResponse>("listStagedProposals", {})).body.count, 1);
+
+    const dispatched = await api.call<{ ok: boolean }>("dispatchDeliveryGraph", { body: { digest } });
+    assert.equal(dispatched.body.ok, true);
+
+    const after = await api.call<ListResponse>("listStagedProposals", {});
+    assert.equal(after.body.count, 0, "a dispatched proposal is no longer staged");
+  });
+
+  // The optional shared-secret guard is enforced in the handler (not by OpenAPI `security`), mirroring
+  // the other read doors (getLineage / listActivePrs). `SECRET` is captured at module import, so we
+  // cache-bust re-import the handler with NANO_PR_WEBHOOK_SECRET set to exercise both the rejected and
+  // authorized paths, driving it directly against a real booted data layer.
+  test("shared-secret guard: 401 without x-hook-secret, 200 with it", async () => {
+    const app = await boot();
+    const stubApp = { log: noopLog(), data: app.db } as any;
+    const ctx = (headers: Record<string, string> = {}) => ({
+      req: {
+        method: "GET",
+        path: "/app/api/delivery-graph/staged",
+        query: new URLSearchParams(),
+        headers: new Headers(headers),
+        text: async () => "",
+      } as any,
+      params: {},
+      query: {},
+      body: undefined,
+    });
+    const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+    process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+    try {
+      const mod = await import(`./listStagedProposals.ts?guard=${Date.now()}`);
+      const guarded = mod.default as (c: unknown, a: unknown) => Promise<{ status: number; body: any }>;
+      const bad = await guarded(ctx(), stubApp);
+      assert.equal(bad.status, 401);
+      const ok = await guarded(ctx({ "x-hook-secret": "s3cr3t" }), stubApp);
+      assert.equal(ok.status, 200);
+      assert.ok(Array.isArray(ok.body.proposals));
+    } finally {
+      if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+      else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+    }
+  });
+});

package/operations/listStagedProposals.ts

@@ -0,0 +1,37 @@
+// GET /app/api/delivery-graph/staged → operationId `listStagedProposals` (issue #511). The read behind
+// the staged-proposals App-View: every LIVE `staged` delivery-graph proposal (not aged out of its TTL),
+// newest first, projected to the metadata the Preview-DI + Dispatch list renders.
+//
+// It replaces the declarative `dataGrid` datasource the staged grid used, so the list can live in an
+// App-View (JS) that CAN drive the `nano-navigate` DI-preview bridge — a declarative grid row-action
+// can POST but cannot hand the recompiled BPMN up to the host explorer. The `graph`/`preview` payloads
+// are deliberately omitted: the App-View recompiles by `digest` through `previewProposalBpmn` for the DI
+// preview, so the list stays lean.
+//
+// The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): when
+// NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header — mirroring the
+// other read doors (getLineage / listActivePrs).
+import { listStagedProposals } from "../app/deliveryGraphProposals.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("listStagedProposals", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listStagedProposals rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const rows = await listStagedProposals(app.data);
+  const proposals = rows.map((row) => ({
+    digest: row.digest,
+    title: row.title,
+    nodeCount: row.node_count,
+    humanNodeCount: row.human_node_count,
+    sideEffectCount: row.side_effect_count,
+    sideEffecting: row.side_effecting === 1,
+    createdAt: row.created_at,
+    expiresAt: row.expires_at,
+  }));
+  return { status: 200, body: { count: proposals.length, proposals } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.134.0",
+  "version": "0.136.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.4.0",
-    "@nanobpm/urban": "^0.81.0",
+    "@nanobpm/urban": "^0.82.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {

package/pages/delivery-graphs/staged-embed.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Delivery graphs — staged proposals (preview · dispatch) (App View embed)</title>
+    <link rel="stylesheet" href="./delivery-graphs.css" />
+    <style>
+      html, body { margin: 0; height: 100%; background: #0b0f14; }
+    </style>
+  </head>
+  <body>
+    <!--
+      Console App-View embed (ADR 0057, issue #511). The console loads this document into its App-View
+      surface and hands it a host element; we mount the SAME staged-proposals list (Preview DI + Dispatch)
+      via the SAME ./staged.mount.js as the standalone shell — only the host and the injected endpoint
+      config differ, so the view renders identically. When the console injects endpoint config via
+      `window.__NANO_APP_VIEW__`, it wins.
+    -->
+    <main id="delivery-graphs-staged-root"></main>
+    <script type="module">
+      import { mountStagedProposals } from "./staged.mount.js";
+
+      const cfg = window.__NANO_APP_VIEW__ ?? {};
+      mountStagedProposals(cfg.host ?? document.getElementById("delivery-graphs-staged-root"), {
+        stagedUrl: cfg.stagedUrl,
+        dispatchUrl: cfg.dispatchUrl,
+        proposalBpmnUrl: cfg.proposalBpmnUrl,
+        hookSecret: cfg.hookSecret,
+      });
+    </script>
+  </body>
+</html>

package/pages/delivery-graphs/staged-standalone.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>Delivery graphs — staged proposals (preview · dispatch)</title>
+    <link rel="stylesheet" href="./delivery-graphs.css" />
+    <style>
+      html, body { margin: 0; height: 100%; background: #0b0f14; }
+    </style>
+  </head>
+  <body>
+    <!--
+      Standalone shell (phone / direct link). Loads the SAME ./staged.mount.js the console App-View embed
+      uses, so the standalone and embedded views render identically. Endpoints default to the current
+      origin; override the list/dispatch/preview endpoints via ?staged= / ?dispatch= / ?proposal-bpmn=.
+      For a secured deployment, pass the guard secret via the URL fragment #secret= (sent as
+      x-hook-secret) — NOT the query string, so it never leaks via server access logs, browser history,
+      or the Referer header. The fragment is stripped from the address bar immediately after it is read.
+      Note: "Preview generated DI" needs the host console explorer to render into, so it only works when
+      embedded — standalone it reports that instead of failing silently.
+    -->
+    <main id="delivery-graphs-staged-root"></main>
+    <script type="module">
+      import { mountStagedProposals } from "./staged.mount.js";
+
+      const params = new URLSearchParams(location.search);
+      const secrets = new URLSearchParams(location.hash.slice(1));
+      const hookSecret = secrets.get("secret") ?? undefined;
+      if (location.hash) {
+        history.replaceState(null, "", location.pathname + location.search);
+      }
+      mountStagedProposals(document.getElementById("delivery-graphs-staged-root"), {
+        stagedUrl: params.get("staged") ?? undefined,
+        dispatchUrl: params.get("dispatch") ?? undefined,
+        proposalBpmnUrl: params.get("proposal-bpmn") ?? undefined,
+        hookSecret,
+      });
+    </script>
+  </body>
+</html>

package/pages/delivery-graphs/staged.mount.js

@@ -0,0 +1,284 @@
+// pages/delivery-graphs/staged.mount.js — the Staged proposals App-View (ADR 0005 Decision 7, issues
+// #460 + #511). The OPERATOR surface for the delivery-graph proposals an agent (or the compose view)
+// has staged: it lists every LIVE staged proposal and, per row, offers
+//   • Preview DI  — recompile the proposal's BPMN (with diagram interchange) and hand it UP to the host
+//     console's process explorer over the `nano-navigate` bridge, rendered read-only BEFORE dispatch;
+//   • Dispatch    — the operator's launch action (#460): POST the proposal's `digest` to the dispatch
+//     door. Clicking Dispatch IS the approval, content-addressed to exactly the graph previewed.
+//
+// It REPLACES the old declarative `dataGrid` (a grid row-action can POST but cannot take the recompiled
+// BPMN and `postMessage` it to the explorer — so a staged proposal had a Dispatch button but no way to
+// SEE the graph, #511). This is a THIN UI over EXISTING doors — the list read (`listStagedProposals`),
+// the DI recompile (`previewProposalBpmn`), and the dispatch (`dispatchDeliveryGraph`) — with no
+// parallel logic. Dispatch stays OPERATOR-ONLY: this surface only ever posts a `digest` that is already
+// staged; it never compiles or stages (that is the compose view), so the #460 boundary holds.
+//
+// A self-contained, dependency-free renderer in the SAME shape as the compose view (./mount.js) and the
+// demand×supply board (pages/board/mount.js): the SAME module mounts embedded in the console (App View)
+// and standalone — only the host element and injected endpoint config differ.
+
+// The read behind the list: every live staged proposal, newest first (base-relative — a leading-slash
+// path resolves against the console iframe ORIGIN, not the app-view base, and 404s the door, #279).
+const DEFAULT_STAGED_URL = "app/api/delivery-graph/staged";
+// The operator dispatch door: POST { digest } → launches the staged graph engine-natively (#460).
+const DEFAULT_DISPATCH_URL = "app/api/actions/delivery-graph/dispatch";
+// The read-only DI preview door: recompiles a staged proposal's BPMN (with diagram interchange) so its
+// generated diagram can be rendered in the host explorer BEFORE dispatch. No deploy, no dispatch.
+const DEFAULT_PROPOSAL_BPMN_URL = "app/api/actions/delivery-graph/proposal-bpmn";
+
+// How often the list re-polls the read door so a freshly-staged (or just-dispatched) proposal appears
+// (or drops off) without a manual refresh — mirrors the 5s cadence the old declarative grid used.
+const DEFAULT_REFRESH_MS = 5000;
+
+// A bounded timeout for every door request. Without it a hung door leaves the fetch promise pending
+// forever, so the busy() lock never clears and the UI is stranded; on timeout the AbortController
+// rejects the fetch, surfacing as an error banner and re-enabling the controls via the finally blocks.
+const REQUEST_TIMEOUT_MS = 30000;
+
+// The confirm shown before a dispatch — dispatching authorises every side-effecting node, so the
+// operator acknowledges that the launch (and its side effects) is content-addressed to this graph.
+const DISPATCH_CONFIRM =
+  "Dispatch this staged delivery graph? This launches the graph engine-natively — any side-effecting " +
+  "node (it merges PRs / publishes packages) will run. Clicking Dispatch IS the approval, " +
+  "content-addressed to exactly the graph you previewed.";
+
+/** Escape untrusted strings before they touch innerHTML. */
+function esc(value) {
+  return String(value ?? "").replace(
+    /[&<>"']/g,
+    (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[ch],
+  );
+}
+
+/** Format an ISO timestamp for the operator, falling back to the raw value if unparseable. */
+function fmtTime(iso) {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return esc(iso);
+  return esc(new Date(t).toLocaleString());
+}
+
+/** Render one staged proposal as a card row with Preview-DI + Dispatch actions. */
+function renderProposal(p) {
+  const title = p.title ? `<code>${esc(p.title)}</code>` : '<span class="muted">(unnamed)</span>';
+  const gate = p.sideEffecting
+    ? '<span class="pill pill-connector">side-effecting</span>'
+    : '<span class="pill pill-wait">no side effects</span>';
+  return `<section class="card">
+    <h2>${title} ${gate}</h2>
+    <div class="chips">
+      <span class="chip">Nodes <b>${esc(p.nodeCount)}</b></span>
+      <span class="chip">Human <b>${esc(p.humanNodeCount)}</b></span>
+      <span class="chip">Side effects <b>${esc(p.sideEffectCount)}</b></span>
+      <span class="chip">Staged <b>${fmtTime(p.createdAt)}</b></span>
+      <span class="chip">Expires <b>${fmtTime(p.expiresAt)}</b></span>
+      <span class="chip">Digest <code>${esc(p.digest)}</code></span>
+    </div>
+    <div class="actions">
+      <button class="btn btn-ghost" type="button" data-preview-di="${esc(p.digest)}">Preview generated DI</button>
+      <button class="btn btn-primary" type="button" data-dispatch="${esc(p.digest)}">Dispatch</button>
+    </div>
+  </section>`;
+}
+
+/** Render the whole list (or the empty state). */
+function renderList(proposals) {
+  if (!Array.isArray(proposals) || proposals.length === 0) {
+    return `<section class="card">
+      <h2>Staged proposals <span class="count">0</span></h2>
+      <p class="muted">No staged proposals awaiting dispatch. Compile a graph (as an agent) or preview + stage one in the compose view above, then Preview &amp; Dispatch it here.</p>
+    </section>`;
+  }
+  const header = `<section class="card card-ok">
+    <h2>Staged proposals <span class="count">${proposals.length}</span></h2>
+    <p class="ok">Awaiting an operator. <b>Preview generated DI</b> renders the laid-out BPMN in the process explorer; <b>Dispatch</b> launches it (dispatch is the approval, #460).</p>
+  </section>`;
+  return header + proposals.map(renderProposal).join("");
+}
+
+/**
+ * Mount the staged-proposals list into `host`.
+ * @param {Element|null} host — the element to render into (or null → look up #delivery-graphs-staged-root).
+ * @param {{stagedUrl?:string, dispatchUrl?:string, proposalBpmnUrl?:string, hookSecret?:string, refreshMs?:number}} [config]
+ */
+export function mountStagedProposals(host, config = {}) {
+  const isElement = host != null && host.nodeType === 1 && typeof host.innerHTML === "string";
+  const root = isElement ? host : document.getElementById("delivery-graphs-staged-root");
+  if (!root) return () => {};
+
+  const stagedUrl = config.stagedUrl ?? DEFAULT_STAGED_URL;
+  const dispatchUrl = config.dispatchUrl ?? DEFAULT_DISPATCH_URL;
+  const proposalBpmnUrl = config.proposalBpmnUrl ?? DEFAULT_PROPOSAL_BPMN_URL;
+  const refreshMs = typeof config.refreshMs === "number" && config.refreshMs > 0 ? config.refreshMs : DEFAULT_REFRESH_MS;
+  const headers = () => ({
+    "content-type": "application/json",
+    ...(config.hookSecret ? { "x-hook-secret": config.hookSecret } : {}),
+  });
+
+  root.innerHTML = `<div class="dg">
+    <div class="actions">
+      <span id="dg-staged-status" class="status"></span>
+    </div>
+    <div id="dg-staged-list"></div>
+  </div>`;
+
+  const statusEl = root.querySelector("#dg-staged-status");
+  const listEl = root.querySelector("#dg-staged-list");
+
+  function setStatus(text, tone) {
+    statusEl.textContent = text || "";
+    statusEl.className = "status" + (tone ? " status-" + tone : "");
+  }
+
+  let busyCount = 0;
+  // A re-render (renderList → new buttons) resets every button to enabled, so the disabled state is
+  // NOT stored on the elements — it is derived from busyCount and re-applied after each render (below)
+  // and on every busy()/idle() transition. That keeps a poll or dispatch-driven refresh from silently
+  // re-enabling the buttons while a Preview/Dispatch request is still in flight.
+  function applyDisabled() {
+    const disabled = busyCount > 0;
+    for (const btn of listEl.querySelectorAll("button")) btn.disabled = disabled;
+  }
+  function busy(on) {
+    busyCount += on ? 1 : -1;
+    applyDisabled();
+  }
+
+  /** Fetch JSON from a door and return { status, body } (never throws on an HTTP error). Rejects
+   * (AbortError) if the request outlives REQUEST_TIMEOUT_MS so a hung door can't wedge the busy lock. */
+  async function request(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, { ...init, headers: headers(), signal: controller.signal });
+      let body = {};
+      try {
+        body = await res.json();
+      } catch (_e) {
+        body = {};
+      }
+      return { status: res.status, body };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  const get = (url) => request(url, { method: "GET" });
+  const post = (url, payload) => request(url, { method: "POST", body: JSON.stringify(payload) });
+
+  let disposed = false;
+  // True while the last completed load failed — so a subsequent successful load knows to clear its own
+  // stale error banner, WITHOUT clobbering a transient action toast (Preview/Dispatch ok/err message).
+  let loadErrorShown = false;
+
+  async function refresh() {
+    try {
+      const { status, body } = await get(stagedUrl);
+      if (disposed) return;
+      if (status === 200 && Array.isArray(body.proposals)) {
+        listEl.innerHTML = renderList(body.proposals);
+        applyDisabled();
+        if (loadErrorShown) {
+          setStatus("");
+          loadErrorShown = false;
+        }
+      } else {
+        listEl.innerHTML = renderList([]);
+        applyDisabled();
+        setStatus(body && body.error ? body.error : "Could not load staged proposals.", "err");
+        loadErrorShown = true;
+      }
+    } catch (err) {
+      if (disposed) return;
+      setStatus(err && err.message ? err.message : "Staged-proposals request failed.", "err");
+      loadErrorShown = true;
+    }
+  }
+
+  // "Preview generated DI": recompile the proposal's BPMN (with diagram interchange) and hand it to the
+  // host console's process explorer, which renders it read-only in a definition-preview view. We run
+  // inside the console App-View iframe, so we fetch from our OWN nwf door (same origin as this app) and
+  // pass the XML UP to the console over the nano-navigate bridge — the XML is far larger than a URL
+  // budget, so it travels in the message, not the path. Standalone (not embedded) there is no host
+  // explorer to drive, so we say so instead of failing silently.
+  const isEmbedded = typeof window !== "undefined" && window.parent && window.parent !== window;
+  async function doPreviewDi(digest) {
+    const staged = typeof digest === "string" ? digest.trim() : "";
+    if (staged === "") return;
+    if (!isEmbedded) {
+      setStatus("Open this page inside the console cockpit to preview the generated DI.", "err");
+      return;
+    }
+    busy(true);
+    setStatus("Compiling DI…");
+    try {
+      const { status, body } = await post(proposalBpmnUrl, { digest: staged });
+      if (status === 200 && body.ok && typeof body.bpmn === "string" && body.bpmn.trim() !== "") {
+        window.parent.postMessage(
+          { type: "nano-navigate", target: "definitionPreview", params: { xml: body.bpmn } },
+          window.location.origin,
+        );
+        setStatus("\u2713 Opening the generated DI in the process explorer…", "ok");
+      } else {
+        setStatus(body && body.error ? body.error : "Could not compile the DI for this proposal.", "err");
+      }
+    } catch (err) {
+      setStatus(err && err.message ? err.message : "DI preview request failed.", "err");
+    } finally {
+      busy(false);
+    }
+  }
+
+  // "Dispatch": the operator's launch (#460). Confirm (dispatch authorises every side-effecting node),
+  // then POST the digest to the dispatch door; on success the proposal flips to `dispatched` and drops
+  // off the list on the next poll — refresh immediately so the operator sees it leave.
+  async function doDispatch(digest) {
+    const staged = typeof digest === "string" ? digest.trim() : "";
+    if (staged === "") return;
+    if (typeof window !== "undefined" && typeof window.confirm === "function" && !window.confirm(DISPATCH_CONFIRM)) {
+      return;
+    }
+    busy(true);
+    setStatus("Dispatching…");
+    try {
+      const { status, body } = await post(dispatchUrl, { digest: staged });
+      if ((status === 202 || status === 200) && body.ok) {
+        setStatus("\u2713 Dispatched — the run is now in flight.", "ok");
+        await refresh();
+      } else {
+        setStatus(body && body.error ? body.error : "Dispatch failed.", "err");
+      }
+    } catch (err) {
+      setStatus(err && err.message ? err.message : "Dispatch request failed.", "err");
+    } finally {
+      busy(false);
+    }
+  }
+
+  listEl.addEventListener("click", (ev) => {
+    const previewBtn = ev.target && ev.target.closest ? ev.target.closest("[data-preview-di]") : null;
+    if (previewBtn) {
+      ev.preventDefault();
+      doPreviewDi(previewBtn.getAttribute("data-preview-di"));
+      return;
+    }
+    const dispatchBtn = ev.target && ev.target.closest ? ev.target.closest("[data-dispatch]") : null;
+    if (dispatchBtn) {
+      ev.preventDefault();
+      doDispatch(dispatchBtn.getAttribute("data-dispatch"));
+    }
+  });
+
+  refresh();
+  // Skip a scheduled poll while a Preview/Dispatch request is in flight: re-rendering the list mid-
+  // request would drop the in-flight button (and its disabled state) out from under the user. The
+  // dispatch path drives its own refresh() on completion, so nothing is missed.
+  const timer = setInterval(() => {
+    if (busyCount === 0) refresh();
+  }, refreshMs);
+
+  return () => {
+    disposed = true;
+    clearInterval(timer);
+    root.innerHTML = "";
+  };
+}

package/pages/delivery-graphs.page.json

@@ -85,50 +85,13 @@
       }
     },
     {
-      "type": "dataGrid",
+      "type": "appView",
       "id": "delivery-graphs-staged",
       "props": {
         "title": "Staged proposals",
-        "collapsible": true,
-        "defaultCollapsed": false,
-        "showCount": true,
-        "rowKey": "digest",
-        "refreshMs": 5000,
-        "empty": "No staged proposals awaiting dispatch. Compile a graph (as an agent) or preview + stage one above, then Dispatch it here.",
-        "data": {
-          "kind": "datasource",
-          "source": "app",
-          "table": "delivery_graph_proposals",
-          "orderBy": { "field": "created_at", "dir": "desc" },
-          "filter": [{ "field": "status", "in": ["staged"] }]
-        },
-        "columns": [
-          { "field": "title", "template": "{{title}}", "header": "Graph", "subtitleField": "digest", "truncate": true, "width": "34%" },
-          { "field": "node_count", "header": "Nodes" },
-          { "field": "human_node_count", "header": "Human" },
-          { "field": "side_effect_count", "header": "Side effects" },
-          { "field": "created_at", "header": "Staged", "width": "9rem", "format": "datetime" },
-          { "field": "expires_at", "header": "Expires", "width": "9rem", "format": "datetime" }
-        ],
-        "rowActions": [
-          {
-            "label": "Dispatch",
-            "confirm": "Dispatch this staged delivery graph? This launches the graph engine-natively \u2014 any side-effecting node (it merges PRs / publishes packages) will run. Clicking Dispatch IS the approval, content-addressed to exactly the graph shown here.",
-            "action": {
-              "path": "/app/api/actions/delivery-graph/dispatch",
-              "body": { "digest": "{{row.digest}}" }
-            }
-          }
-        ],
-        "detail": {
-          "fields": [
-            { "field": "digest", "label": "Digest" },
-            { "field": "logical_key", "label": "Logical key" },
-            { "field": "side_effecting", "label": "Side-effecting" },
-            { "field": "preview", "label": "Preview (diagram, human stop-points, side effects)" },
-            { "field": "graph", "label": "Graph JSON (normalized serialization to be dispatched)" }
-          ]
-        }
+        "embed": "./delivery-graphs/staged-embed.html",
+        "standalone": "./delivery-graphs/staged-standalone.html",
+        "fill": true
       }
     },
     {

package/test/delivery-graphs-embed.test.ts

@@ -84,15 +84,22 @@ test("#460: the compose view exposes NO dispatch or approval affordance — it o
   assert(!/approvalToken/.test(MOUNT_JS), "mount.js must NOT carry the removed replayable approvalToken");
 });
 
-test("#460: dispatch is the operator's Staged-proposals row-action on the page", () => {
-  // The page (not mount.js) offers dispatch: a Staged proposals grid over delivery_graph_proposals
-  // with a Dispatch row-action that posts the proposal's digest to the operator dispatch door.
+test("#460/#511: dispatch is the operator's action on the Staged-proposals App-View", () => {
+  // Dispatch is NOT in the compose view (asserted above). It lives on the Staged-proposals surface,
+  // which is now an App-View (issue #511) rather than a declarative grid: a grid row-action can POST but
+  // cannot hand the recompiled BPMN up to the host explorer, so a staged proposal had a Dispatch button
+  // but no way to SEE the graph. The App-View carries BOTH Preview-DI and Dispatch. The wiring itself
+  // (which doors staged.mount.js posts to) is pinned by delivery-graphs-staged-embed.test.ts.
   const page = JSON.parse(PAGE_JSON) as { nodes: Array<Record<string, any>> };
   const staged = page.nodes.find((n) => n.id === "delivery-graphs-staged");
-  assert(staged, "the page must carry a Staged proposals grid");
-  assert(staged?.props?.data?.table === "delivery_graph_proposals", "the staged grid binds to delivery_graph_proposals");
-  const dispatch = (staged?.props?.rowActions ?? []).find((a: any) => a.label === "Dispatch");
-  assert(dispatch, "the staged grid must expose a Dispatch row-action");
-  assert(dispatch.action.path.endsWith("actions/delivery-graph/dispatch"), "Dispatch posts to the operator dispatch door");
-  assert(dispatch.action.body.digest === "{{row.digest}}", "Dispatch posts the proposal's digest");
+  assert(staged, "the page must carry a Staged proposals surface");
+  assert(staged?.type === "appView", "the Staged proposals surface is an App-View (#511), not a declarative grid");
+  assert(
+    staged?.props?.embed === "./delivery-graphs/staged-embed.html",
+    "the Staged proposals App-View embeds ./delivery-graphs/staged-embed.html",
+  );
+  assert(
+    staged?.props?.standalone === "./delivery-graphs/staged-standalone.html",
+    "the Staged proposals App-View has a standalone shell",
+  );
 });

package/test/delivery-graphs-staged-embed.test.ts

@@ -0,0 +1,77 @@
+// Contract guard for the Staged proposals App-View (issues #460 + #511).
+//
+// A staged delivery-graph proposal (agent-authored, or staged from the compose view) must be
+// PREVIEWABLE and DISPATCHABLE from the cockpit. The old declarative `dataGrid` could POST a Dispatch
+// row-action but could not hand the recompiled BPMN up to the host explorer, so a staged proposal had a
+// Dispatch button and NO way to see the graph. The staged App-View (pages/delivery-graphs/staged.*)
+// closes that: per row it offers Preview-DI (over the nano-navigate bridge) AND Dispatch. This test
+// pins the wiring so it cannot silently regress: the sidecars exist and mount the same module, the door
+// defaults are base-relative (the #279 App-View resolution class — a leading-slash path 404s through the
+// console iframe), it drives the DI-preview bridge, and it posts the dispatch by digest.
+import { test } from "node:test";
+import { assert } from "#test-assert";
+import { readFileSync } from "node:fs";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+const DIR = `${ROOT}pages/delivery-graphs`;
+const MOUNT_JS = readFileSync(`${DIR}/staged.mount.js`, "utf8");
+const EMBED_HTML = readFileSync(`${DIR}/staged-embed.html`, "utf8");
+const STANDALONE_HTML = readFileSync(`${DIR}/staged-standalone.html`, "utf8");
+const PAGE_JSON = readFileSync(`${ROOT}pages/delivery-graphs.page.json`, "utf8");
+
+// Pull the string default out of `const <name> = config.<field> ?? <CONST>;` (or a module const).
+function defaultUrl(name: string): string {
+  const m = MOUNT_JS.match(new RegExp(`${name}\\s*=\\s*config\\.\\w+\\s*\\?\\?\\s*(\\w+);`));
+  assert(m, `staged.mount.js must default ${name} from config with a fallback constant`);
+  const constM = MOUNT_JS.match(new RegExp(`const ${m![1]}\\s*=\\s*"([^"]*)"`));
+  assert(constM, `staged.mount.js must declare the ${m![1]} fallback as a string literal`);
+  return constM![1];
+}
+
+test("#511: the staged App-View mounts the same module standalone and embedded", () => {
+  assert(/mountStagedProposals/.test(MOUNT_JS), "staged.mount.js must export mountStagedProposals");
+  for (const [file, html] of [["staged-embed.html", EMBED_HTML], ["staged-standalone.html", STANDALONE_HTML]] as const) {
+    assert(
+      /import \{ mountStagedProposals \} from "\.\/staged\.mount\.js"/.test(html),
+      `${file} must import mountStagedProposals from ./staged.mount.js`,
+    );
+    assert(/mountStagedProposals\(/.test(html), `${file} must call mountStagedProposals`);
+  }
+});
+
+test("#511: the page binds the Staged proposals node to the staged App-View sidecars", () => {
+  const page = JSON.parse(PAGE_JSON) as { nodes: Array<Record<string, any>> };
+  const staged = page.nodes.find((n) => n.id === "delivery-graphs-staged");
+  assert(staged, "the page must carry the delivery-graphs-staged node");
+  assert(staged?.type === "appView", "delivery-graphs-staged must be an appView (#511)");
+  assert(staged?.props?.embed === "./delivery-graphs/staged-embed.html", "it embeds the staged embed sidecar");
+  assert(staged?.props?.standalone === "./delivery-graphs/staged-standalone.html", "it has the staged standalone sidecar");
+});
+
+test("#511/#279: the staged list door default is base-relative", () => {
+  const url = defaultUrl("stagedUrl");
+  assert(url.endsWith("delivery-graph/staged"), `stagedUrl default "${url}" must hit the listStagedProposals door`);
+  assert(!url.startsWith("/"), `default stagedUrl "${url}" must be base-relative (App-View #279 resolution class)`);
+});
+
+test("#511: DI preview — the staged view wires the proposal-bpmn door and bridges the XML to the explorer", () => {
+  const url = defaultUrl("proposalBpmnUrl");
+  assert(url.endsWith("actions/delivery-graph/proposal-bpmn"), `proposalBpmnUrl default "${url}" must hit the previewProposalBpmn door`);
+  assert(!url.startsWith("/"), `default proposalBpmnUrl "${url}" must be base-relative`);
+  assert(/data-preview-di=/.test(MOUNT_JS), "staged.mount.js must render a per-row Preview-DI affordance carrying the digest");
+  assert(/target:\s*"definitionPreview"/.test(MOUNT_JS), "staged.mount.js must post nano-navigate to the definitionPreview target");
+  assert(/params:\s*\{\s*xml:/.test(MOUNT_JS), "staged.mount.js must carry the compiled BPMN xml in the bridge message");
+});
+
+test("#460/#511: Dispatch is the operator's launch — posts the digest to the dispatch door, and never compiles/stages", () => {
+  const url = defaultUrl("dispatchUrl");
+  assert(url.endsWith("actions/delivery-graph/dispatch"), `dispatchUrl default "${url}" must hit the dispatchDeliveryGraph door`);
+  assert(!url.startsWith("/"), `default dispatchUrl "${url}" must be base-relative`);
+  assert(/data-dispatch=/.test(MOUNT_JS), "staged.mount.js must render a per-row Dispatch affordance carrying the digest");
+  assert(/window\.confirm\(/.test(MOUNT_JS), "Dispatch must confirm before launching (dispatch authorises side effects)");
+  // Operator-only: this surface dispatches a digest that is ALREADY staged — it must not compile or
+  // stage (that is the compose view), so the #460 boundary holds and the self-approval hole stays shut.
+  assert(!/delivery-graph\/preview\b/.test(MOUNT_JS), "staged.mount.js must NOT wire the compile/stage door");
+  assert(!/graphJson/.test(MOUNT_JS), "staged.mount.js must NOT submit pasted graph JSON (it only lists+dispatches staged proposals)");
+  assert(!/approvalToken/.test(MOUNT_JS), "staged.mount.js must NOT carry the removed replayable approvalToken");
+});