@nanobpm/nano-workforce 0.134.0 → 0.135.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/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/openapi.yaml

@@ -1673,6 +1673,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 +2983,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.135.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",

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");
+});