@nanobpm/nano-workforce 0.120.2 → 0.121.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.121.0](https://github.com/nanobpm/nano-workforce/compare/v0.120.2...v0.121.0) (2026-08-22)
+
+
+### Features
+
+* **delivery-graphs:** surface the compile preview in the console (compose → preview → dispatch) ([#445](https://github.com/nanobpm/nano-workforce/issues/445)) ([eb8bc7a](https://github.com/nanobpm/nano-workforce/commit/eb8bc7a609f894ddf83248bf356ab18864f63b62)), closes [#279](https://github.com/nanobpm/nano-workforce/issues/279) [#441](https://github.com/nanobpm/nano-workforce/issues/441)
+
 ## [0.120.2](https://github.com/nanobpm/nano-workforce/compare/v0.120.1...v0.120.2) (2026-08-22)
 
 

package/openapi.yaml

@@ -1616,6 +1616,20 @@ components:
         diagram:
           type: string
           description: The mermaid flowchart of the compiled graph (preview).
+        humanNodes:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryHumanStop"
+          description: >-
+            The human stop-points the compiled graph parks on (preview) — where it waits for a person
+            (or an agent answering on their behalf), rendered by the Delivery Graphs page (#441).
+        sideEffects:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliverySideEffect"
+          description: >-
+            The side-effecting (`agent`/`connector`) actions the compiled graph WILL perform (preview)
+            — what an approval authorises (Decision 7), rendered by the Delivery Graphs page (#441).
     ResolvedDeliveryNode:
       description: >-
         A normalised node in the compiled graph (ADR 0005 slice S1) — its `id`, `kind`, the

package/operations/previewDeliveryGraph.test.ts

@@ -35,6 +35,15 @@ test("preview-delivery-graph: a pasted well-formed graph → 200 summary with di
   assertEquals(res.body.sideEffecting, true);
   assert(typeof res.body.diagram === "string" && res.body.diagram.length > 0);
   assertEquals(res.body.title, "runbook");
+  // The FULL preview detail (#441) — the human stop-points and side-effecting actions the page
+  // renders, not just the counts. `a` is the side-effecting agent node; `b` is the human stop.
+  assert(Array.isArray(res.body.humanNodes) && res.body.humanNodes.length === 1);
+  assertEquals(res.body.humanNodes[0].nodeId, "b");
+  assertEquals(res.body.humanNodes[0].prompt, "do X");
+  assert(Array.isArray(res.body.sideEffects) && res.body.sideEffects.length === 1);
+  assertEquals(res.body.sideEffects[0].nodeId, "a");
+  assertEquals(res.body.sideEffects[0].kind, "agent");
+  assert(typeof res.body.sideEffects[0].description === "string" && res.body.sideEffects[0].description.length > 0);
 });
 
 test("preview-delivery-graph: is PURE — repeated previews return the identical digest", async () => {

package/operations/previewDeliveryGraph.ts

@@ -54,6 +54,12 @@ export default defineOperation("previewDeliveryGraph", async ({ body }, app) =>
       humanNodeCount: compiled.humanNodes.length,
       sideEffectCount: compiled.sideEffects.length,
       diagram: compiled.diagram,
+      // The FULL extracted preview detail (not just the counts): the human stop-points and the
+      // side-effecting actions the operator is being asked to approve (Decision 7). The Delivery
+      // Graphs page renders these lists so the operator sees WHERE it parks on a person and WHAT it
+      // will do before dispatching — the "preview before dispatch" principle made visible (#441).
+      humanNodes: compiled.humanNodes,
+      sideEffects: compiled.sideEffects,
     },
   };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.120.2",
+  "version": "0.121.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/delivery-graphs.css

@@ -0,0 +1,273 @@
+:root {
+  color-scheme: dark;
+}
+
+.dg {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  color: #d7e0ea;
+  background: #0b0f14;
+  min-height: 100%;
+  box-sizing: border-box;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.dg .card {
+  background: #121821;
+  border: 1px solid #223042;
+  border-radius: 10px;
+  padding: 14px 16px;
+}
+
+.dg .card-warn {
+  border-color: rgba(210, 153, 34, 0.5);
+}
+
+.dg .card-err {
+  border-color: rgba(248, 81, 73, 0.5);
+}
+
+.dg .card-ok {
+  border-color: rgba(63, 185, 80, 0.5);
+}
+
+.dg h2 {
+  margin: 0 0 8px;
+  font-size: 15px;
+  font-weight: 600;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.dg p {
+  margin: 6px 0;
+  font-size: 13px;
+}
+
+.dg .json {
+  width: 100%;
+  box-sizing: border-box;
+  min-height: 200px;
+  resize: vertical;
+  background: #0d141d;
+  color: #d7e0ea;
+  border: 1px solid #223042;
+  border-radius: 8px;
+  padding: 10px 12px;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 12.5px;
+  line-height: 1.5;
+}
+
+.dg .idem {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin-top: 10px;
+  font-size: 12px;
+}
+
+.dg .input {
+  background: #0d141d;
+  color: #d7e0ea;
+  border: 1px solid #223042;
+  border-radius: 6px;
+  padding: 6px 10px;
+  font-size: 13px;
+}
+
+.dg .actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-top: 12px;
+  flex-wrap: wrap;
+}
+
+.dg .btn {
+  background: #1c2735;
+  color: #d7e0ea;
+  border: 1px solid #2b3a4e;
+  border-radius: 7px;
+  padding: 7px 16px;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.dg .btn:hover {
+  background: #223042;
+}
+
+.dg .btn:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.dg .btn-primary {
+  background: #1f6feb;
+  border-color: #388bfd;
+  color: #fff;
+}
+
+.dg .btn-primary:hover {
+  background: #388bfd;
+}
+
+.dg .btn-ghost {
+  background: transparent;
+  border-color: #2b3a4e;
+  color: #8aa0b8;
+}
+
+.dg .status {
+  font-size: 12.5px;
+  color: #8aa0b8;
+}
+
+.dg .status-ok {
+  color: #56d364;
+}
+
+.dg .status-err {
+  color: #ff7b72;
+}
+
+.dg .status-warn {
+  color: #e3b341;
+}
+
+.dg .chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 8px;
+}
+
+.dg .chip {
+  background: #0d141d;
+  border: 1px solid #223042;
+  border-radius: 999px;
+  padding: 3px 12px;
+  font-size: 12px;
+}
+
+.dg .count {
+  background: #0d141d;
+  border: 1px solid #223042;
+  border-radius: 999px;
+  padding: 0 9px;
+  font-size: 12px;
+  font-weight: 500;
+  color: #8aa0b8;
+}
+
+.dg table.grid {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 13px;
+  margin-top: 4px;
+}
+
+.dg table.grid th,
+.dg table.grid td {
+  text-align: left;
+  padding: 6px 8px;
+  border-bottom: 1px solid #1c2735;
+  vertical-align: top;
+}
+
+.dg table.grid th {
+  color: #8aa0b8;
+  font-weight: 500;
+}
+
+.dg .diagram {
+  background: #0d141d;
+  border: 1px solid #223042;
+  border-radius: 8px;
+  padding: 12px;
+  overflow-x: auto;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 12.5px;
+  line-height: 1.5;
+  color: #b9c6d6;
+  margin: 0;
+}
+
+.dg .errors {
+  margin: 8px 0 0;
+  padding-left: 18px;
+  font-size: 13px;
+}
+
+.dg .errors li {
+  margin: 3px 0;
+}
+
+.dg code {
+  background: #0d141d;
+  border: 1px solid #223042;
+  border-radius: 4px;
+  padding: 1px 5px;
+  font-size: 12px;
+}
+
+.dg .muted {
+  color: #6b7f95;
+}
+
+.dg .ok {
+  color: #56d364;
+}
+
+.dg .warn {
+  color: #e3b341;
+}
+
+.dg .red {
+  color: #ff7b72;
+}
+
+.dg .pill {
+  display: inline-block;
+  border-radius: 999px;
+  padding: 1px 9px;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+.dg .pill-agent {
+  background: rgba(31, 111, 235, 0.18);
+  color: #58a6ff;
+  border: 1px solid rgba(31, 111, 235, 0.4);
+}
+
+.dg .pill-connector {
+  background: rgba(210, 153, 34, 0.18);
+  color: #e3b341;
+  border: 1px solid rgba(210, 153, 34, 0.4);
+}
+
+.dg .pill-wait {
+  background: rgba(63, 185, 80, 0.18);
+  color: #56d364;
+  border: 1px solid rgba(63, 185, 80, 0.4);
+}
+
+.dg .pill-human {
+  background: rgba(163, 113, 247, 0.18);
+  color: #bc8cff;
+  border: 1px solid rgba(163, 113, 247, 0.4);
+}
+
+.dg .pill-unknown {
+  background: rgba(139, 148, 158, 0.18);
+  color: #8b949e;
+  border: 1px solid rgba(139, 148, 158, 0.4);
+}

package/pages/delivery-graphs/embed.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Delivery graphs — compose · 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). The console loads this document into its App-View surface and
+      hands it a host element; we mount the SAME compose → preview → dispatch view via the SAME
+      ./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-root"></main>
+    <script type="module">
+      import { mountDeliveryGraphs } from "./mount.js";
+
+      const cfg = window.__NANO_APP_VIEW__ ?? {};
+      mountDeliveryGraphs(cfg.host ?? document.getElementById("delivery-graphs-root"), {
+        previewUrl: cfg.previewUrl,
+        dispatchUrl: cfg.dispatchUrl,
+        hookSecret: cfg.hookSecret,
+      });
+    </script>
+  </body>
+</html>

package/pages/delivery-graphs/mount.js

@@ -0,0 +1,365 @@
+// pages/delivery-graphs/mount.js — the Delivery Graphs compose → preview → dispatch view (ADR 0005,
+// issue #441). The human front door for a delivery graph: author/paste a `DeliveryGraph` JSON,
+// PREVIEW it (a pure compile — nothing is dispatched) to SEE the rendered plan before approving it,
+// then DISPATCH it through the gated two-step.
+//
+// A self-contained, dependency-free renderer in the SAME shape as the demand×supply board
+// (pages/board/mount.js) and the agent cockpit: the SAME module mounts embedded in the console (App
+// View) and standalone on a phone — only the host element and injected endpoint config differ. The app
+// has no browser build step, so this consumes the preview/dispatch doors straight off the wire.
+//
+// It is a THIN UI over the EXISTING doors — there is no parallel compile/dispatch path:
+//   • PREVIEW  → POST previewUrl  (previewDeliveryGraph)  — pure; renders the mermaid `diagram`, the
+//                `humanNodes[]` stop-points, the `sideEffects[]` the operator is asked to approve, and
+//                path-qualified validation `errors[]` inline for a 400 (the fix-and-recompile loop).
+//   • DISPATCH → POST dispatchUrl (dispatchDeliveryGraph → startDeliveryGraph) — the gated two-step:
+//                a side-effecting graph parks `awaiting-approval` (400 + `approvalToken`); the view
+//                shows the side-effect summary and, on confirm, re-submits with `approve` → 202
+//                running. A graph with only `wait`/`human` nodes dispatches without approval.
+
+const DEFAULT_PREVIEW_URL = "app/api/actions/delivery-graph/preview";
+const DEFAULT_DISPATCH_URL = "app/api/actions/delivery-graph/dispatch";
+
+// A bounded timeout for every door request. Without it a hung preview/dispatch endpoint leaves the
+// fetch promise pending forever, so the busy() lock never clears and the UI is stranded (buttons
+// disabled, status stuck) with no way to retry. On timeout the AbortController rejects the fetch,
+// which surfaces as an error banner and re-enables the controls via the callers' finally blocks.
+const REQUEST_TIMEOUT_MS = 30000;
+
+const EXAMPLE_GRAPH = JSON.stringify(
+  {
+    name: "example-runbook",
+    nodes: [
+      { id: "build", kind: "agent", agent: { jobType: "senior:feature" }, emits: [{ name: "pr", type: "url" }] },
+      { id: "soak", kind: "wait", wait: { target: "checks-green" } },
+      { id: "signoff", kind: "human", human: { prompt: "Review the PR and approve the release." } },
+      { id: "publish", kind: "connector", connector: { target: "publish-package", dedupeKey: "example-runbook-publish" } },
+    ],
+    edges: [
+      { from: "build.pr", to: "soak" },
+      { from: "soak", to: "signoff" },
+      { from: "signoff", to: "publish" },
+    ],
+  },
+  null,
+  2,
+);
+
+/** Escape untrusted strings before they touch innerHTML. */
+function esc(value) {
+  return String(value ?? "").replace(
+    /[&<>"']/g,
+    (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[ch],
+  );
+}
+
+/** A small kind pill (agent / connector / wait / human). */
+function pill(kind) {
+  const k = String(kind ?? "").toLowerCase();
+  const cls = k === "agent" || k === "connector" || k === "wait" || k === "human" ? k : "unknown";
+  return `<span class="pill pill-${cls}">${esc(k || "\u2014")}</span>`;
+}
+
+/** Render a node's emitted facts (`name:type`) as a compact inline list. */
+function renderEmits(emits) {
+  if (!Array.isArray(emits) || emits.length === 0) return '<span class="muted">\u2014</span>';
+  return emits.map((f) => `<code>${esc(f.name)}<span class="muted">:${esc(f.type)}</span></code>`).join(" ");
+}
+
+/** Render the human stop-points table — WHERE the graph parks on a person. */
+function renderHumanNodes(humanNodes) {
+  const rows = Array.isArray(humanNodes) ? humanNodes : [];
+  if (rows.length === 0) {
+    return '<section class="card"><h2>Human stop-points <span class="count">0</span></h2><p class="muted">This graph never parks on a person — it runs to completion unattended.</p></section>';
+  }
+  const body = rows
+    .map(
+      (h) => `<tr>
+        <td><code>${esc(h.nodeId)}</code></td>
+        <td>${h.prompt ? esc(h.prompt) : '<span class="muted">(click-done stop)</span>'}</td>
+        <td>${h.formKey ? `<code>${esc(h.formKey)}</code>` : '<span class="muted">\u2014</span>'}</td>
+        <td>${renderEmits(h.emits)}</td>
+      </tr>`,
+    )
+    .join("");
+  return `<section class="card">
+    <h2>Human stop-points <span class="count">${rows.length}</span></h2>
+    <p class="muted">Where the graph STOPS for a person (or an agent answering on their behalf).</p>
+    <table class="grid"><thead><tr><th>Node</th><th>Prompt</th><th>Form</th><th>Emits</th></tr></thead><tbody>${body}</tbody></table>
+  </section>`;
+}
+
+/** Render the side-effects table — WHAT the graph will do (what approval authorises, Decision 7). */
+function renderSideEffects(sideEffects) {
+  const rows = Array.isArray(sideEffects) ? sideEffects : [];
+  if (rows.length === 0) {
+    return '<section class="card"><h2>Side effects <span class="count">0</span></h2><p class="ok">No side effects — this graph has only <code>wait</code>/<code>human</code> nodes, so it dispatches without approval.</p></section>';
+  }
+  const body = rows
+    .map(
+      (s) => `<tr>
+        <td><code>${esc(s.nodeId)}</code></td>
+        <td>${pill(s.kind)}</td>
+        <td>${esc(s.description)}</td>
+        <td>${s.dedupeKey ? `<code>${esc(s.dedupeKey)}</code>` : '<span class="muted">\u2014</span>'}</td>
+      </tr>`,
+    )
+    .join("");
+  return `<section class="card card-warn">
+    <h2>Side effects <span class="count">${rows.length}</span></h2>
+    <p class="warn">These actions the graph WILL perform once dispatched — approving the preview authorises them.</p>
+    <table class="grid"><thead><tr><th>Node</th><th>Kind</th><th>Effect</th><th>Dedupe key</th></tr></thead><tbody>${body}</tbody></table>
+  </section>`;
+}
+
+/** Render the path-qualified validation/compile errors inline for the fix-and-recompile loop. */
+function renderErrors(message, errors) {
+  const list = Array.isArray(errors) ? errors : [];
+  const items = list.map((e) => `<li><code>${esc(e.path)}</code> — ${esc(e.message)}</li>`).join("");
+  return `<section class="card card-err">
+    <h2>Validation failed</h2>
+    <p class="red">${esc(message || "The graph could not be compiled.")}</p>
+    ${items ? `<ul class="errors">${items}</ul>` : ""}
+  </section>`;
+}
+
+/** Render the successful preview: summary chips, the human/side-effect tables, and the mermaid source. */
+function renderPreview(result) {
+  const title = result.title ? `<code>${esc(result.title)}</code>` : '<span class="muted">(unnamed)</span>';
+  const gate = result.sideEffecting
+    ? '<span class="pill pill-connector">requires approval</span>'
+    : '<span class="pill pill-wait">no approval needed</span>';
+  const summary = `<section class="card">
+    <h2>Preview ${gate}</h2>
+    <p class="muted">Pure compile — nothing was dispatched. Review the plan below, then Dispatch it.</p>
+    <div class="chips">
+      <span class="chip">Graph ${title}</span>
+      <span class="chip">Nodes <b>${esc(result.nodeCount)}</b></span>
+      <span class="chip">Human <b>${esc(result.humanNodeCount)}</b></span>
+      <span class="chip">Side effects <b>${esc(result.sideEffectCount)}</b></span>
+      <span class="chip">Digest <code>${esc(result.digest)}</code></span>
+    </div>
+  </section>`;
+  const diagram = `<section class="card">
+    <h2>Diagram <span class="muted">(mermaid flowchart source)</span></h2>
+    <p class="muted">The resolved graph as a mermaid <code>flowchart</code>. Paste it into any mermaid renderer, or follow a dispatched run into the process explorer for the live laid-out model.</p>
+    <pre class="diagram">${esc(result.diagram)}</pre>
+  </section>`;
+  return summary + renderSideEffects(result.sideEffects) + renderHumanNodes(result.humanNodes) + diagram;
+}
+
+/** Render the dispatch outcome banner (running / already-running). */
+function renderDispatched(result) {
+  const already = result.alreadyRunning
+    ? ' <span class="muted">(re-dispatch short-circuited onto the already-running run)</span>'
+    : "";
+  return `<section class="card card-ok">
+    <h2>Dispatched — ${esc(result.status || "running")}${already}</h2>
+    <p class="ok">Watch it advance in the in-flight grid below.</p>
+    <div class="chips">
+      ${result.runKey ? `<span class="chip">Run <code>${esc(result.runKey)}</code></span>` : ""}
+      ${result.processInstanceKey ? `<span class="chip">Instance <code>${esc(result.processInstanceKey)}</code></span>` : ""}
+      ${result.processDefinitionId ? `<span class="chip">Definition <code>${esc(result.processDefinitionId)}</code></span>` : ""}
+    </div>
+  </section>`;
+}
+
+/**
+ * Mount the compose → preview → dispatch view into `host`.
+ * @param {Element|null} host — the element to render into (or null → look up #delivery-graphs-root).
+ * @param {{previewUrl?:string, dispatchUrl?:string, hookSecret?:string}} [config]
+ */
+export function mountDeliveryGraphs(host, config = {}) {
+  const isElement = host != null && host.nodeType === 1 && typeof host.innerHTML === "string";
+  const root = isElement ? host : document.getElementById("delivery-graphs-root");
+  if (!root) return () => {};
+
+  const previewUrl = config.previewUrl ?? DEFAULT_PREVIEW_URL;
+  const dispatchUrl = config.dispatchUrl ?? DEFAULT_DISPATCH_URL;
+  const headers = () => ({
+    "content-type": "application/json",
+    ...(config.hookSecret ? { "x-hook-secret": config.hookSecret } : {}),
+  });
+
+  // The static compose shell. The <textarea> is a real element (its value must survive re-renders of
+  // the output panes), so it is created once and never clobbered.
+  root.innerHTML = `<div class="dg">
+    <section class="card">
+      <h2>1 · Compose</h2>
+      <p class="muted">Paste or author a <code>DeliveryGraph</code> JSON (nodes/edges over the closed <code>agent</code>/<code>wait</code>/<code>human</code>/<code>connector</code> vocabulary).</p>
+      <textarea id="dg-json" class="json" spellcheck="false" placeholder='{ "name": "…", "nodes": [ … ], "edges": [ … ] }'></textarea>
+      <label class="idem"><span>Idempotency key <span class="muted">(optional — a re-dispatch with the same key won't double-launch)</span></span><input id="dg-idem" class="input" type="text" placeholder="(optional)" /></label>
+      <div class="actions">
+        <button id="dg-preview" class="btn btn-primary" type="button">Preview</button>
+        <button id="dg-dispatch" class="btn" type="button">Dispatch</button>
+        <button id="dg-example" class="btn btn-ghost" type="button">Load example</button>
+        <span id="dg-status" class="status"></span>
+      </div>
+    </section>
+    <div id="dg-approval"></div>
+    <div id="dg-output"></div>
+  </div>`;
+
+  const jsonEl = root.querySelector("#dg-json");
+  const idemEl = root.querySelector("#dg-idem");
+  const statusEl = root.querySelector("#dg-status");
+  const outputEl = root.querySelector("#dg-output");
+  const approvalEl = root.querySelector("#dg-approval");
+  const previewBtn = root.querySelector("#dg-preview");
+  const dispatchBtn = root.querySelector("#dg-dispatch");
+  const exampleBtn = root.querySelector("#dg-example");
+
+  function setStatus(text, tone) {
+    statusEl.textContent = text || "";
+    statusEl.className = "status" + (tone ? " status-" + tone : "");
+  }
+
+  function busy(on) {
+    previewBtn.disabled = on;
+    dispatchBtn.disabled = on;
+  }
+
+  // While a side-effecting graph is parked awaiting approval, LOCK the compose inputs so the operator
+  // cannot edit `graphJson`/idempotency key out from under the token they are about to approve — the
+  // approval must bind to the exact graph that was previewed and parked (the server derives the
+  // approval digest from whatever body it receives, so an edited textarea would silently approve a
+  // DIFFERENT graph). `doApprove` dispatches the FROZEN graph captured at park time, not the live field.
+  function lockCompose(on) {
+    jsonEl.readOnly = on;
+    idemEl.readOnly = on;
+    exampleBtn.disabled = on;
+  }
+
+  /** POST a JSON body to 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 post(url, payload) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+      let body = {};
+      try {
+        body = await res.json();
+      } catch (_e) {
+        body = {};
+      }
+      return { status: res.status, body };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  function graphJson() {
+    return jsonEl.value;
+  }
+
+  function idempotencyKey() {
+    const v = idemEl.value.trim();
+    return v === "" ? undefined : v;
+  }
+
+  async function doPreview() {
+    approvalEl.innerHTML = "";
+    lockCompose(false);
+    if (graphJson().trim() === "") {
+      setStatus("Paste a delivery-graph JSON to preview.", "err");
+      return;
+    }
+    busy(true);
+    setStatus("Compiling preview…");
+    try {
+      const { status, body } = await post(previewUrl, { graphJson: graphJson() });
+      if (status === 200 && body.ok) {
+        outputEl.innerHTML = renderPreview(body);
+        setStatus("\u2713 Compiled — nothing was dispatched.", "ok");
+      } else {
+        outputEl.innerHTML = renderErrors(body.error, body.errors);
+        setStatus("Preview failed — fix the errors and re-preview.", "err");
+      }
+    } catch (err) {
+      outputEl.innerHTML = renderErrors(err && err.message ? err.message : String(err), []);
+      setStatus("Preview request failed.", "err");
+    } finally {
+      busy(false);
+    }
+  }
+
+  /** Show the approval confirmation panel for a side-effecting graph parked awaiting-approval. The
+   * `frozen` graph/idempotency key are the EXACT values that produced this park — on confirm we
+   * dispatch those, never the (now-locked) live fields, so approval binds to the previewed graph. */
+  function showApproval(parked, frozen) {
+    approvalEl.innerHTML = `<section class="card card-warn">
+      <h2>Approval required</h2>
+      <p class="warn">${esc(parked.message || "This graph performs side effects and needs explicit approval to dispatch.")}</p>
+      <p class="muted">Approval token <code>${esc(parked.approvalToken || parked.digest || "")}</code>. Approving confirms the side effects rendered in the preview above.</p>
+      <div class="actions">
+        <button id="dg-approve" class="btn btn-primary" type="button">Approve &amp; dispatch</button>
+        <button id="dg-cancel" class="btn btn-ghost" type="button">Cancel</button>
+      </div>
+    </section>`;
+    approvalEl.querySelector("#dg-cancel").addEventListener("click", () => {
+      approvalEl.innerHTML = "";
+      lockCompose(false);
+      setStatus("Dispatch cancelled — the graph was not approved.", "");
+    });
+    approvalEl.querySelector("#dg-approve").addEventListener("click", () => doDispatch(true, frozen));
+  }
+
+  async function doDispatch(approve, frozen) {
+    // On approve, dispatch the graph FROZEN at park time; otherwise read the live compose fields.
+    const graph = frozen ? frozen.graphJson : graphJson();
+    if (graph.trim() === "") {
+      setStatus("Paste a delivery-graph JSON to dispatch.", "err");
+      return;
+    }
+    busy(true);
+    setStatus(approve ? "Approving & dispatching…" : "Dispatching…");
+    try {
+      const payload = { graphJson: graph, approve: approve === true };
+      const idem = frozen ? frozen.idempotencyKey : idempotencyKey();
+      if (idem !== undefined) payload.idempotencyKey = idem;
+      const { status, body } = await post(dispatchUrl, payload);
+      if (status === 202 && body.ok) {
+        approvalEl.innerHTML = "";
+        lockCompose(false);
+        outputEl.innerHTML = renderDispatched(body);
+        setStatus("\u2713 Dispatched.", "ok");
+      } else if (status === 400 && body.status === "awaiting-approval") {
+        // The gated two-step: a side-effecting graph parked at approval. Freeze the exact graph +
+        // idempotency key that parked and lock the compose inputs, then surface the confirm panel; the
+        // operator's confirm re-submits THAT frozen graph with approve=true → 202 running.
+        lockCompose(true);
+        showApproval(body, { graphJson: graph, idempotencyKey: idem });
+        setStatus("Approval required before this side-effecting graph can dispatch.", "warn");
+      } else {
+        approvalEl.innerHTML = "";
+        lockCompose(false);
+        outputEl.innerHTML = renderErrors(body.error, body.errors);
+        setStatus("Dispatch refused — fix the errors and try again.", "err");
+      }
+    } catch (err) {
+      outputEl.innerHTML = renderErrors(err && err.message ? err.message : String(err), []);
+      setStatus("Dispatch request failed.", "err");
+    } finally {
+      busy(false);
+    }
+  }
+
+  previewBtn.addEventListener("click", doPreview);
+  dispatchBtn.addEventListener("click", () => doDispatch(false));
+  exampleBtn.addEventListener("click", () => {
+    jsonEl.value = EXAMPLE_GRAPH;
+    approvalEl.innerHTML = "";
+    outputEl.innerHTML = "";
+    setStatus("Example loaded — Preview it.", "");
+  });
+
+  return () => {
+    root.innerHTML = "";
+  };
+}

package/pages/delivery-graphs/standalone.html

@@ -0,0 +1,38 @@
+<!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 — compose · 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 ./mount.js the console App-View embed uses,
+      so the standalone and embedded views render identically. Endpoints default to the current origin;
+      override the preview/dispatch endpoints via ?preview= / ?dispatch=. 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.
+    -->
+    <main id="delivery-graphs-root"></main>
+    <script type="module">
+      import { mountDeliveryGraphs } from "./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);
+      }
+      mountDeliveryGraphs(document.getElementById("delivery-graphs-root"), {
+        previewUrl: params.get("preview") ?? undefined,
+        dispatchUrl: params.get("dispatch") ?? undefined,
+        hookSecret,
+      });
+    </script>
+  </body>
+</html>

package/pages/delivery-graphs.page.json

@@ -70,42 +70,18 @@
       "type": "text",
       "id": "subtitle",
       "props": {
-        "text": "The human front door for delivery graphs (ADR 0005). Paste an agent-authored delivery-graph JSON, Preview it (a pure compile \u2014 nothing is dispatched) to see it validates and read its content digest, then Dispatch it. A graph with any side-effecting node (it merges PRs / publishes packages) dispatches only when you tick Approve; without approval it is parked in the in-flight grid below for review. Preview and Dispatch are thin UIs over the same compileDeliveryGraph / startDeliveryGraph doors \u2014 there is no parallel submit path.",
+        "text": "The human front door for delivery graphs (ADR 0005). Compose an agent-authored delivery-graph JSON, Preview it (a pure compile \u2014 nothing is dispatched) to SEE the rendered plan \u2014 its mermaid diagram, the human stop-points where it parks on a person, and the side effects it will perform \u2014 and fix any path-qualified validation errors inline. Then Dispatch it: a graph with any side-effecting node (it merges PRs / publishes packages) parks for an explicit Approve & dispatch confirm of the rendered preview; a graph with only wait/human nodes dispatches straight away. The compose \u2192 preview \u2192 dispatch view is a thin UI over the same compileDeliveryGraph / startDeliveryGraph doors \u2014 there is no parallel submit path.",
         "variant": "sub"
       }
     },
     {
-      "type": "actionForm",
-      "id": "delivery-graph-preview",
+      "type": "appView",
+      "id": "delivery-graphs-compose",
       "props": {
-        "title": "1 \u00b7 Preview (compile \u2014 pure, nothing is dispatched)",
-        "submitLabel": "Preview",
-        "action": {
-          "path": "/app/api/actions/delivery-graph/preview",
-          "body": "{{form}}",
-          "successLabel": "\u2713 Valid \u2014 the graph compiled. Nothing was dispatched. Review its shape in the in-flight grid, then Dispatch it below."
-        },
-        "fields": [
-          { "key": "graphJson", "label": "Delivery-graph JSON \u2014 paste the agent-authored DeliveryGraph (nodes/edges). Preview validates + compiles it without dispatching.", "type": "text", "required": true, "requiredMessage": "Paste a delivery-graph JSON to preview" }
-        ]
-      }
-    },
-    {
-      "type": "actionForm",
-      "id": "delivery-graph-dispatch",
-      "props": {
-        "title": "2 \u00b7 Dispatch (start \u2014 gated, idempotent)",
-        "submitLabel": "Dispatch",
-        "action": {
-          "path": "/app/api/actions/delivery-graph/dispatch",
-          "body": "{{form}}",
-          "successLabel": "\u2713 Dispatched \u2014 watch it advance in the in-flight grid below."
-        },
-        "fields": [
-          { "key": "graphJson", "label": "Delivery-graph JSON \u2014 paste the same DeliveryGraph you previewed.", "type": "text", "required": true, "requiredMessage": "Paste the delivery-graph JSON to dispatch" },
-          { "key": "approve", "label": "Approve \u2014 I reviewed the preview and approve dispatching this graph's side effects (required for any agent/connector node)", "type": "checkbox" },
-          { "key": "idempotencyKey", "label": "Idempotency key (optional) \u2014 a re-dispatch with the same key (or, blank, the same graph) will not double-launch an in-flight run", "type": "text" }
-        ]
+        "title": "Compose \u2192 preview \u2192 dispatch",
+        "embed": "./delivery-graphs/embed.html",
+        "standalone": "./delivery-graphs/standalone.html",
+        "fill": true
       }
     },
     {

package/scripts/pages-contract.test.ts

@@ -360,24 +360,16 @@ test("issue #386: the human-facing Delivery Graphs surface is wired (nav tab, pa
   );
   assert(tab, "pages/_nav.json must carry a `Delivery Graphs` nav tab → the delivery-graphs page");
 
-  // 2) The Submit page exists with a Preview (compile) action and a Dispatch (start) action, plus an
-  //    in-flight grid over the delivery_graph_runs aggregate that links to the per-graph detail page.
+  // 2) The page carries the compose → preview → dispatch App View (issue #441 — the rendered preview
+  //    that consumes the compile output), plus an in-flight grid over the delivery_graph_runs aggregate
+  //    that links to the per-graph detail page. The rich preview (mermaid diagram + humanNodes[] +
+  //    sideEffects[] + inline errors) can't render in a bare `actionForm` (its response is discarded),
+  //    so the surface is an `appView` embed over the SAME compile/dispatch doors.
   const page = JSON.parse(readFileSync(`${ROOT}pages/delivery-graphs.page.json`, "utf8"));
-  const forms = (page.nodes ?? []).filter((n: Json) => n.type === "actionForm");
-  const preview = forms.find((f: Json) => f.props?.action?.path === "/app/api/actions/delivery-graph/preview");
-  const dispatch = forms.find((f: Json) => f.props?.action?.path === "/app/api/actions/delivery-graph/dispatch");
-  assert(preview, "delivery-graphs page must have a Preview form posting to /app/api/actions/delivery-graph/preview");
-  assert(dispatch, "delivery-graphs page must have a Dispatch form posting to /app/api/actions/delivery-graph/dispatch");
-  // Both forms take the pasted graph JSON; Dispatch also carries the explicit approve gate.
-  assert(
-    (preview.props?.fields ?? []).some((fl: Json) => fl.key === "graphJson"),
-    "the Preview form must have a graphJson paste field",
-  );
-  assert(
-    (dispatch.props?.fields ?? []).some((fl: Json) => fl.key === "graphJson") &&
-      (dispatch.props?.fields ?? []).some((fl: Json) => fl.key === "approve"),
-    "the Dispatch form must have a graphJson paste field and an approve gate",
+  const compose = (page.nodes ?? []).find(
+    (n: Json) => n.type === "appView" && typeof n.props?.embed === "string" && n.props.embed.includes("delivery-graphs/embed.html"),
   );
+  assert(compose, "delivery-graphs page must have an appView embedding ./delivery-graphs/embed.html (the compose → preview → dispatch view, #441)");
   const grid = (page.nodes ?? []).find(
     (n: Json) => n.type === "dataGrid" && n.props?.data?.table === "delivery_graph_runs",
   );

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

@@ -0,0 +1,85 @@
+// Contract guard for the Delivery Graphs compose → preview → dispatch App View (issue #441).
+//
+// The rich compile preview (mermaid diagram + humanNodes[] stop-points + sideEffects[] + inline
+// path-qualified errors) and the gated approve → dispatch two-step are surfaced by an `appView` embed
+// (pages/delivery-graphs/) over the EXISTING previewDeliveryGraph / dispatchDeliveryGraph doors — a
+// bare `actionForm` discards its response and so can render none of that. This test pins the wiring so
+// it can't silently regress: the sidecars exist, mount.js hits BOTH doors with base-relative defaults
+// (the #279 App-View resolution class — a leading-slash path 404s through the console iframe), it
+// renders each preview facet, and it implements the awaiting-approval → approve re-submit.
+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}/mount.js`, "utf8");
+const EMBED_HTML = readFileSync(`${DIR}/embed.html`, "utf8");
+const STANDALONE_HTML = readFileSync(`${DIR}/standalone.html`, "utf8");
+
+// Pull the string default out of `const <name> = config.<name> ?? "<default>";` (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, `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, `mount.js must declare the ${m![1]} fallback as a string literal`);
+  return constM![1];
+}
+
+test("#441: the delivery-graphs App View mounts the same module standalone and embedded", () => {
+  assert(/mountDeliveryGraphs/.test(MOUNT_JS), "mount.js must export mountDeliveryGraphs");
+  for (const [file, html] of [["embed.html", EMBED_HTML], ["standalone.html", STANDALONE_HTML]] as const) {
+    assert(/import \{ mountDeliveryGraphs \} from "\.\/mount\.js"/.test(html), `${file} must import mountDeliveryGraphs from ./mount.js`);
+    assert(/mountDeliveryGraphs\(/.test(html), `${file} must call mountDeliveryGraphs`);
+  }
+});
+
+test("#441: mount.js wires BOTH the preview and dispatch doors", () => {
+  const previewUrl = defaultUrl("previewUrl");
+  const dispatchUrl = defaultUrl("dispatchUrl");
+  assert(previewUrl.endsWith("actions/delivery-graph/preview"), `previewUrl default "${previewUrl}" must hit the previewDeliveryGraph door`);
+  assert(dispatchUrl.endsWith("actions/delivery-graph/dispatch"), `dispatchUrl default "${dispatchUrl}" must hit the dispatchDeliveryGraph door`);
+});
+
+// The #279 App-View resolution class: a default endpoint must be BASE-RELATIVE (no leading slash) so
+// it resolves under the console app-view base, not the console origin root (which 404s the door).
+for (const name of ["previewUrl", "dispatchUrl"] as const) {
+  test(`#441/#279: default ${name} is base-relative (no leading slash)`, () => {
+    const def = defaultUrl(name);
+    assert(!def.startsWith("/"), `default ${name} "${def}" must not start with "/" — a leading-slash path resolves against the console iframe ORIGIN, not the app-view base, so the door 404s`);
+  });
+}
+
+test("#441: the preview render consumes every compile facet the door returns", () => {
+  // The whole point of the issue: the preview data (diagram / humanNodes / sideEffects / errors) is
+  // rich but was consumed by nothing. Assert the renderer touches each facet at a CONCRETE call site
+  // (not a bare word, which a comment/string could satisfy) so a renderer that stops reading a field
+  // fails this guard.
+  const facetUse: Record<string, RegExp> = {
+    diagram: /esc\(result\.diagram\)/,
+    humanNodes: /renderHumanNodes\(result\.humanNodes\)/,
+    sideEffects: /renderSideEffects\(result\.sideEffects\)/,
+    errors: /renderErrors\(body\.error,\s*body\.errors\)/,
+  };
+  for (const [facet, re] of Object.entries(facetUse)) {
+    assert(re.test(MOUNT_JS), `mount.js must render the preview's \`${facet}\` via ${re.source}`);
+  }
+});
+
+test("#441: dispatch implements the gated awaiting-approval → approve two-step", () => {
+  // Structural, not substring: pin the actual park-recognition branch and the approve re-submit call
+  // site, so a comment mentioning "approve" can't satisfy the guard.
+  assert(/body\.status === "awaiting-approval"/.test(MOUNT_JS), "mount.js must branch on the awaiting-approval park from the dispatch door");
+  assert(/doDispatch\(true/.test(MOUNT_JS), "mount.js must re-submit with approve (doDispatch(true, …)) on the operator's confirm");
+});
+
+test("#441: approval binds to the frozen previewed graph, not the live (editable) textarea", () => {
+  // The server derives the approval digest from whatever body it receives, so an operator who edits
+  // the textarea after parking would silently approve+dispatch a DIFFERENT graph than the one
+  // previewed. mount.js must (a) capture the exact graph at park time and dispatch THAT on confirm,
+  // and (b) lock the compose inputs while approval is pending so they can't drift.
+  // Structural assertions (concrete call sites), not bare-word substrings a comment could satisfy:
+  assert(/const graph = frozen \? frozen\.graphJson : graphJson\(\)/.test(MOUNT_JS), "doDispatch must dispatch the frozen (park-time) graph, not the live textarea");
+  assert(/lockCompose\(true\)/.test(MOUNT_JS), "mount.js must lock the compose inputs (lockCompose(true)) while a graph is parked awaiting approval");
+  assert(/jsonEl\.readOnly = on/.test(MOUNT_JS), "lockCompose must make the graph input read-only while approval is pending");
+});