@nanobpm/nano-workforce 0.133.1 → 0.135.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **delivery-graph:** node timeout PT1H default, submission + per-node override ([#505](https://github.com/nanobpm/nano-workforce/issues/505)) ([#507](https://github.com/nanobpm/nano-workforce/issues/507)) ([96fe961](https://github.com/nanobpm/nano-workforce/commit/96fe96165bb898919f7000002e68cb4ba5a925e9))
+
 ## [0.133.1](https://github.com/nanobpm/nano-workforce/compare/v0.133.0...v0.133.1) (2026-08-24)
 
 ### Bug Fixes

package/app/deliveryGraphDispatch.ts

@@ -23,6 +23,7 @@ import {
   DELIVERY_PHASE,
   deliveryGraphRuns,
 } from "./deliveryGraphRun.ts";
+import type { DeliveryRunTimeouts } from "./deliveryRunner.ts";
 import { deliveryGraphDigest, runDeliveryGraph } from "./deliveryRunner.ts";
 
 /** The outcome of a dispatch attempt — mirrors the retained run lifecycle. `ok:false` carries the
@@ -48,7 +49,7 @@ export type DispatchDeliveryGraphResult =
 export async function dispatchDeliveryGraphRun(
   app: Pick<AppApi, "data" | "engine" | "log">,
   graph: unknown,
-  options: { runKey?: string | null; title?: string | null } = {},
+  options: { runKey?: string | null; title?: string | null } & DeliveryRunTimeouts = {},
 ): Promise<DispatchDeliveryGraphResult> {
   const validationErrors = validateDeliveryGraph(graph);
   if (validationErrors.length > 0) {
@@ -130,7 +131,16 @@ export async function dispatchDeliveryGraphRun(
   };
   let launched: Awaited<ReturnType<typeof runDeliveryGraph>>;
   try {
-    launched = await runDeliveryGraph(app.engine, typedGraph, { runKey });
+    // Thread the operator-supplied run-level timeouts (#505) so a submission override reaches every
+    // node's seeded `nodeInputs` (absent → the runner's PT1H/PT30M/P1D defaults).
+    launched = await runDeliveryGraph(app.engine, typedGraph, {
+      runKey,
+      nodeTimeout: options.nodeTimeout,
+      probeTimeout: options.probeTimeout,
+      escalationSlaTimeout: options.escalationSlaTimeout,
+      probePollEvery: options.probePollEvery,
+      escalationAssignee: options.escalationAssignee,
+    });
   } catch (err) {
     await markClaimFailed();
     app.log.error("dispatch-delivery-graph launch threw", { runKey });

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

@@ -138,6 +138,93 @@ test("wait gateKeys default to a fresh per-run token so concurrent runs of one g
   assertEquals(gateKeyOf(seeded), "run-7:n3");
 });
 
+test("the node timeout defaults to PT1H (raised from PT30M) when no option is supplied (#505)", async () => {
+  // #505: the hard PT30M default tripped the boundary timer on legitimately-long implementation nodes.
+  // With no timeout option, every agent/connector node inherits the NEW PT1H run default.
+  const p = await prepareOk(GRAPH);
+  const timeouts = Object.values(p.nodeInputs)
+    .filter((v) => "timeout" in v)
+    .map((v) => (v as { timeout: string }).timeout);
+  assert(timeouts.length === 2, `expected the agent + connector nodes to seed a timeout, got ${timeouts.length}`);
+  for (const t of timeouts) assertEquals(t, "PT1H");
+});
+
+test("a submission nodeTimeout override seeds every agent/connector node with that duration (#505)", async () => {
+  // AC: an operator dispatch that sets nodeTimeout: "PT2H" seeds PT2H for ALL agent/connector nodes.
+  const p = await prepareOk(GRAPH, { nodeTimeout: "PT2H" });
+  const timeouts = Object.values(p.nodeInputs)
+    .filter((v) => "timeout" in v)
+    .map((v) => (v as { timeout: string }).timeout);
+  assert(timeouts.length === 2, `expected two seeded node timeouts, got ${timeouts.length}`);
+  for (const t of timeouts) assertEquals(t, "PT2H");
+});
+
+test("a per-node timeout override wins for its node while siblings keep the run/default value (#505)", async () => {
+  // AC: a node declaring timeout: "PT4H" seeds nodeInputs.<el>.timeout == "PT4H" while its siblings keep
+  // the run-level (here PT2H) value. Asserted positionally on the compiled nodeInputs map.
+  const graph: DeliveryGraph = {
+    name: "per-node override",
+    nodes: [
+      { id: "heavy", kind: "agent", agent: { jobType: "senior:feature", prompt: "long build", timeout: "PT4H" } },
+      { id: "quick", kind: "agent", agent: { jobType: "senior:demo" } },
+      { id: "notify", kind: "connector", connector: { target: "slack:post", dedupeKey: "n-1", timeout: "PT10M" } },
+    ],
+    edges: [
+      { from: "heavy", to: "quick" },
+      { from: "quick", to: "notify" },
+    ],
+  };
+  const p = await prepareOk(graph, { nodeTimeout: "PT2H" });
+  const byJobType = (jt: string) =>
+    Object.values(p.nodeInputs).find((v) => (v as { jobType?: string }).jobType === jt) as { timeout: string } | undefined;
+  const connector = Object.values(p.nodeInputs).find((v) => (v as { target?: string }).target === "slack:post") as
+    | { timeout: string }
+    | undefined;
+
+  assertEquals(byJobType("senior:feature")?.timeout, "PT4H"); // per-node override wins
+  assertEquals(byJobType("senior:demo")?.timeout, "PT2H"); // sibling keeps the run-level value
+  assertEquals(connector?.timeout, "PT10M"); // connector per-node override wins too
+});
+
+test("a per-node timeout is normalized (lower-case → canonical) and a malformed one falls back to the run value (#505)", async () => {
+  // A graph built programmatically (bypassing the OpenAPI pattern) can carry a lower-case or malformed
+  // per-node duration. The runner normalizes it through `isoDuration` so a bad value never bakes an
+  // uninterpretable boundary timer: `pt4h` → `PT4H`, and `nonsense` falls back to the run-level default.
+  const graph: DeliveryGraph = {
+    name: "per-node normalization",
+    nodes: [
+      { id: "lower", kind: "agent", agent: { jobType: "senior:feature", timeout: "pt4h" } },
+      { id: "bad", kind: "connector", connector: { target: "slack:post", dedupeKey: "n-1", timeout: "nonsense" } },
+    ],
+    edges: [{ from: "lower", to: "bad" }],
+  } as unknown as DeliveryGraph;
+  const p = await prepareOk(graph, { nodeTimeout: "PT2H" });
+  const agent = Object.values(p.nodeInputs).find((v) => (v as { jobType?: string }).jobType === "senior:feature") as
+    | { timeout: string }
+    | undefined;
+  const connector = Object.values(p.nodeInputs).find((v) => (v as { target?: string }).target === "slack:post") as
+    | { timeout: string }
+    | undefined;
+
+  assertEquals(agent?.timeout, "PT4H"); // lower-case normalized to canonical form
+  assertEquals(connector?.timeout, "PT2H"); // malformed value rejected → run-level default
+});
+
+test("a RUN-LEVEL timeout is normalized (lower-case → canonical) and a malformed one falls back to the default (#505)", async () => {
+  // A programmatic caller of prepareDeliveryGraph/runDeliveryGraph bypasses the OpenAPI/door validators,
+  // so a lower-case or malformed run-level `nodeTimeout` must not become the fallback baked into a node's
+  // boundary timer FEEL. isoDuration canonicalizes it (`pt3h` → `PT3H`) at the run level too, and a
+  // malformed value falls back to the DEFAULTS run value rather than an uninterpretable duration.
+  const lower = await prepareOk(GRAPH, { nodeTimeout: "pt3h" });
+  for (const v of Object.values(lower.nodeInputs).filter((v) => "timeout" in v)) {
+    assertEquals((v as { timeout: string }).timeout, "PT3H"); // lower-case run value normalized
+  }
+  const bad = await prepareOk(GRAPH, { nodeTimeout: "nonsense" });
+  for (const v of Object.values(bad.nodeInputs).filter((v) => "timeout" in v)) {
+    assertEquals((v as { timeout: string }).timeout, "PT1H"); // malformed run value → PT1H default, never baked raw
+  }
+});
+
 test("a malformed graph returns the S1 compile errors and prepares nothing", async () => {
   const r = await prepareDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] } as unknown as DeliveryGraph);
   assert(!r.ok, "a dangling edge fails to prepare");

package/app/deliveryRunner.ts

@@ -18,6 +18,7 @@ import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery } from "./readiness.ts";
+import { isoDuration } from "./reviewWait.ts";
 
 /** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
  * content-addressed deploy id (`delivery-graph-<digest>`) AND the dispatch fence's default idempotency
@@ -53,7 +54,7 @@ export interface DeliveryRunOptions extends DeliveryRunTimeouts {
 }
 
 const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
-  nodeTimeout: "PT30M",
+  nodeTimeout: "PT1H",
   probeTimeout: "PT30M",
   probePollEvery: msToIsoDuration(DEFAULT_EVERY_MS),
   escalationSlaTimeout: "P1D",
@@ -110,11 +111,14 @@ export async function prepareDeliveryGraph(
   const bpmn = rewriteProcessId(compiled.bpmn, processDefinitionId);
 
   const runKey = options.runKey?.trim() || randomUUID();
+  // Normalize the run-level timeouts through isoDuration so a programmatic caller that bypasses the
+  // OpenAPI/door validators cannot bake a malformed or lower-case duration into a BPMN timer FEEL —
+  // isoDuration canonicalizes case and falls back to the default on a malformed/blank value.
   const timeouts = {
-    nodeTimeout: options.nodeTimeout ?? DEFAULTS.nodeTimeout,
-    probeTimeout: options.probeTimeout ?? DEFAULTS.probeTimeout,
-    probePollEvery: options.probePollEvery ?? DEFAULTS.probePollEvery,
-    escalationSlaTimeout: options.escalationSlaTimeout ?? DEFAULTS.escalationSlaTimeout,
+    nodeTimeout: isoDuration(options.nodeTimeout, DEFAULTS.nodeTimeout),
+    probeTimeout: isoDuration(options.probeTimeout, DEFAULTS.probeTimeout),
+    probePollEvery: isoDuration(options.probePollEvery, DEFAULTS.probePollEvery),
+    escalationSlaTimeout: isoDuration(options.escalationSlaTimeout, DEFAULTS.escalationSlaTimeout),
     escalationAssignee: options.escalationAssignee ?? null,
   };
   const elementByNodeId = new Map(compiled.resolved.nodes.map((n) => [n.id, n.element]));
@@ -174,7 +178,7 @@ function buildNodeInput(
 ): NodeInput {
   switch (node.kind) {
     case "agent":
-      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: ctx.nodeTimeout };
+      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
     case "wait": {
       const probe = parseProbe(node.wait);
       return {
@@ -201,7 +205,7 @@ function buildNodeInput(
         target: node.connector.target,
         dedupeKey: node.connector.dedupeKey ?? null,
         payload: node.connector.payload ?? null,
-        timeout: ctx.nodeTimeout,
+        timeout: isoDuration(node.connector.timeout, ctx.nodeTimeout),
       };
     default:
       return assertNever(node, "buildNodeInput");

package/app/reviewWait.ts

@@ -20,6 +20,14 @@ export const DEFAULT_REVIEW_WAIT_TIMEOUT = "PT20M";
 // would fail to interpret; not a full grammar (we don't need fractional seconds here).
 const ISO_DURATION = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
 
+/** True when `raw` is a well-formed ISO-8601 duration under {@link isoDuration}'s grammar — the strict
+ * predicate an operator submission door uses to REJECT a malformed duration (400) rather than silently
+ * fall back to a default. Derives from the same {@link ISO_DURATION} grammar so the accept/reject
+ * decision can never drift from the normalise-or-default one. Case-insensitive (`pt2h` is valid). */
+export function isValidIsoDuration(raw: string): boolean {
+  return ISO_DURATION.test(raw.trim().toUpperCase());
+}
+
 /** Validate an ISO-8601 duration string for a BPMN timer's `<bpmn:timeDuration>`, falling back to
  * `def` when the value is absent, blank, or malformed — a bad env value must never deploy an
  * uninterpretable timer expression into a process. Normalises to upper case (`pt20m` → `PT20M`).

package/openapi.yaml

@@ -1407,6 +1407,15 @@ components:
                   type: string
                   maxLength: 20000
                   description: OPTIONAL steering prompt appended to the node's job brief.
+                timeout:
+                  type: string
+                  pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+                  maxLength: 64
+                  description: >-
+                    OPTIONAL per-node ISO-8601 SLA timeout (#505). Overrides the run-level `nodeTimeout`
+                    (and the `PT1H` default) for THIS node's bounded-timeout → escalate boundary timer, so
+                    a legitimately-long node (e.g. a full `senior:feature` implementation) can outlast a
+                    quick gate without a spurious escalation. Absent → the run/default value.
     DeliveryNodeWait:
       description: >-
         A `wait` node — a durable `ReadinessProbe` (ADR 0001 §2) watching an external fact. Reuses the
@@ -1496,6 +1505,14 @@ components:
                   type: object
                   additionalProperties: true
                   description: Minimal forward-declared payload stub — the concrete connector payload schema is deferred (ADR non-goal).
+                timeout:
+                  type: string
+                  pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+                  maxLength: 64
+                  description: >-
+                    OPTIONAL per-node ISO-8601 SLA timeout (#505). Overrides the run-level `nodeTimeout`
+                    (and the `PT1H` default) for THIS connector node's bounded-timeout → escalate boundary
+                    timer. Absent → the run/default value.
     DeliveryEdge:
       description: >-
         A dependency edge — "`to` proceeds once fact `from` is observable" (ADR 0005 Decision 3).
@@ -1596,6 +1613,28 @@ components:
           type: string
           maxLength: 255
           description: OPTIONAL idempotency key. A re-dispatch with the same key (or, when omitted, the same digest) does not double-launch. Blank/whitespace is treated as absent.
+        nodeTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 SLA timeout for `agent`/`connector` nodes (#505) — the
+            bounded-timeout → escalate boundary bound every such node inherits unless it declares its own
+            per-node `timeout`. Absent → the `PT1H` default. An invalid duration is rejected at submit.
+        probeTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 poll budget for `wait` gates (#505) before they escalate. Absent →
+            the `PT30M` default. An invalid duration is rejected at submit.
+        escalationSlaTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 SLA for `human` nodes (#505) before they record an `escalated`
+            outcome. Absent → the `P1D` default. An invalid duration is rejected at submit.
     DeliveryGraphProposalBpmnRequest:
       description: >-
         Request the compiled BPMN of a staged delivery-graph proposal for read-only DI PREVIEW. Carries
@@ -1634,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
@@ -2888,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/dispatchDeliveryGraph.test.ts

@@ -182,4 +182,69 @@ describe("dispatchDeliveryGraph — operator dispatch by staged-proposal digest"
     assert.equal((await deliveryGraphProposals(app.db).get(digest))?.status, "expired");
     assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
   });
+
+  test("an invalid run-level nodeTimeout duration is rejected at submit → 400, nothing launched (#505)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    const res = await api.call<{ ok?: boolean; error?: string; issues?: Array<{ path: string }> }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, nodeTimeout: "2 hours" },
+    });
+    // Rejected at submit — either by the edge shape-validator (openapi `pattern`) or the door's own
+    // ISO-8601 guard; both surface a 400. Nothing launches and the proposal stays staged (dispatchable).
+    assert.equal(res.status, 400);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "staged");
+  });
+
+  test("an oversized invalid duration never bloats the 400 response — rejected with a bounded error, nothing launched (#505)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    const huge = `PT${"9".repeat(5000)}X`;
+    const res = await api.call<{ ok?: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, nodeTimeout: huge },
+    });
+    assert.equal(res.status, 400);
+    // The 5000-char blob is never echoed back verbatim — the edge pattern rejects it, and the door's
+    // own guard (`truncateForEcho`) caps the echo when the edge is bypassed. Either way the response
+    // stays bounded, so a malformed input can't bloat logs/response bodies.
+    assert.ok((res.body.error ?? "").length < 300, `error body should be bounded, got ${(res.body.error ?? "").length} chars`);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+  });
+
+  test("a syntactically-valid but oversized duration is rejected at the door → 400, nothing launched (#505)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    // Matches the ISO-8601 grammar but exceeds the door's MAX_DURATION_LEN (64) — the door re-enforces the
+    // openapi `maxLength: 64` so an oversized value is refused even if the edge validator is bypassed.
+    const longValid = `PT${"9".repeat(70)}H`;
+    const res = await api.call<{ ok?: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, nodeTimeout: longValid },
+    });
+    assert.equal(res.status, 400);
+    assert.ok((res.body.error ?? "").length < 300, `error body should be bounded, got ${(res.body.error ?? "").length} chars`);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "staged");
+  });
+
+  test("a valid run-level nodeTimeout override dispatches the run → 202 running (#505)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    const res = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, nodeTimeout: "PT2H" },
+    });
+    assert.equal(res.status, 202);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.status, "running");
+    await app.settle();
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "dispatched");
+  });
 });

package/operations/dispatchDeliveryGraph.ts

@@ -12,9 +12,39 @@
 
 import { dispatchDeliveryGraphRun } from "../app/deliveryGraphDispatch.ts";
 import { getStagedProposal, markProposalDispatched, markProposalExpired } from "../app/deliveryGraphProposals.ts";
+import { isValidIsoDuration } from "../app/reviewWait.ts";
 import type { DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
+/** Cap an untrusted, rejected duration string before it is echoed into logs/response bodies. `openapi.yaml`
+ * caps these dispatch duration fields at `maxLength: 64` at the edge, and the door re-enforces that bound
+ * (see `MAX_DURATION_LEN`); this truncation is defense-in-depth for when the edge validator is bypassed,
+ * so a very large malformed value can never bloat either the logs or the response. */
+const MAX_ECHO_LEN = 80;
+function truncateForEcho(value: string): string {
+  return value.length > MAX_ECHO_LEN ? `${value.slice(0, MAX_ECHO_LEN)}… (${value.length} chars)` : value;
+}
+
+/** Door-level cap on a duration override, mirroring the `maxLength: 64` on these fields in `openapi.yaml`.
+ * Re-enforced here so a syntactically-valid-but-oversized duration is still rejected when the edge
+ * validator is bypassed (internal calls/tests), keeping seeded process variables and error/log output bounded. */
+const MAX_DURATION_LEN = 64;
+
+/** Validate an OPTIONAL run-level ISO-8601 duration override off the dispatch body (#505). Blank/
+ * whitespace is treated as absent (→ the runner default). A present-but-malformed value returns
+ * `{ ok: false, invalid }` so the door can reject it at submit rather than silently deploy an
+ * uninterpretable timer. Reuses the canonical `reviewWait` grammar so accept/reject never drifts from
+ * the runner's normalise-or-default one, and enforces `MAX_DURATION_LEN` so an oversized value is
+ * rejected even if the OpenAPI `maxLength` edge check is bypassed. */
+function validateDurationOverride(raw: unknown): { ok: true; value: string | undefined } | { ok: false; invalid: string } {
+  if (raw === undefined || raw === null) return { ok: true, value: undefined };
+  if (typeof raw !== "string") return { ok: false, invalid: String(raw) };
+  const trimmed = raw.trim();
+  if (trimmed === "") return { ok: true, value: undefined };
+  if (trimmed.length > MAX_DURATION_LEN || !isValidIsoDuration(trimmed)) return { ok: false, invalid: trimmed };
+  return { ok: true, value: trimmed.toUpperCase() };
+}
+
 export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) => {
   const digest = body && typeof body === "object" && "digest" in body && typeof body.digest === "string" ? body.digest.trim() : "";
   if (digest === "") {
@@ -24,6 +54,27 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
   const idemRaw = body && typeof body === "object" && "idempotencyKey" in body && typeof body.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
   const idempotencyKey = idemRaw !== "" ? idemRaw : undefined;
 
+  // Run-level timeout overrides (#505) — exposed at submission, validated as ISO-8601 durations here so
+  // an invalid value is a clean 400 (never a deployed, uninterpretable timer). Absent → runner defaults.
+  const rawTimeouts: Record<"nodeTimeout" | "probeTimeout" | "escalationSlaTimeout", unknown> =
+    body && typeof body === "object"
+      ? {
+          nodeTimeout: "nodeTimeout" in body ? body.nodeTimeout : undefined,
+          probeTimeout: "probeTimeout" in body ? body.probeTimeout : undefined,
+          escalationSlaTimeout: "escalationSlaTimeout" in body ? body.escalationSlaTimeout : undefined,
+        }
+      : { nodeTimeout: undefined, probeTimeout: undefined, escalationSlaTimeout: undefined };
+  const timeouts: { nodeTimeout?: string; probeTimeout?: string; escalationSlaTimeout?: string } = {};
+  for (const field of ["nodeTimeout", "probeTimeout", "escalationSlaTimeout"] as const) {
+    const parsed = validateDurationOverride(rawTimeouts[field]);
+    if (!parsed.ok) {
+      const shown = truncateForEcho(parsed.invalid);
+      app.log.warn("dispatch-delivery-graph rejected: invalid duration", { field, value: shown, invalidLength: parsed.invalid.length });
+      return { status: 400, body: { ok: false, error: `\`${field}\` must be an ISO-8601 duration (e.g. \`PT2H\`); got \`${shown}\`` } };
+    }
+    if (parsed.value !== undefined) timeouts[field] = parsed.value;
+  }
+
   // Load the live staged proposal for this digest — refuses an unknown/expired/superseded/already-
   // dispatched digest cleanly (no run is launched).
   const proposal = await getStagedProposal(app.data, digest);
@@ -47,7 +98,7 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
     return { status: 400, body: { ok: false, error: `staged proposal ${digest} is corrupt: ${err instanceof Error ? err.message : String(err)}` } };
   }
 
-  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title });
+  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title, ...timeouts });
   if (!dispatched.ok) {
     app.log.warn("dispatch-delivery-graph refused: compile", { digest, errors: dispatched.errors.length });
     const outBody: DeliveryGraphTextResult = {

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