@nanobpm/nano-workforce 0.123.2 → 0.124.0

package/operations/dispatchDeliveryGraph.ts

@@ -1,113 +1,93 @@
-// POST /app/api/actions/delivery-graph/dispatch → operationId `dispatchDeliveryGraph` (issue #386,
-// ADR 0005 slice S5). The human-facing UI JSON-paste DISPATCH ingress: the Delivery Graphs page's
-// "Dispatch" action posts the operator's pasted delivery-graph as a raw JSON STRING plus an explicit
-// `approve` flag; this door parses it (`parseDeliveryGraphText`) and DELEGATES to the SAME gated,
-// idempotent `startDeliveryGraph` handler the agent-facing / REST paths use. There is deliberately NO
-// parallel dispatch path — this is a thin UI text adapter onto the ONE contract (S5's stated "UI
-// JSON-paste" ingress that S5 named but did not build).
+// POST /app/api/actions/delivery-graph/dispatch → operationId `dispatchDeliveryGraph` (ADR 0005
+// Decision 7, issue #460). The OPERATOR-ONLY dispatch door: the cockpit's staged-proposals grid posts
+// the `digest` of the proposal the operator picked; this door loads that `staged` proposal, runs the
+// retained S4 runner for its previewed graph (`dispatchDeliveryGraphRun`), and marks the proposal
+// `dispatched`.
 //
-//   • APPROVAL. When the operator ticks `approve` (having reviewed the preview), the door derives the
-//     graph's content digest via the SAME pure compiler `startDeliveryGraph` uses and presents it as
-//     the `approvalToken`, so a side-effecting graph dispatches. Without `approve`, a side-effecting
-//     graph is PARKED at approval by the start door (a 400 whose `awaiting-approval` run shows in the
-//     in-flight grid) and a non-side-effecting graph dispatches straight away.
-//   • The start door owns idempotency, the durable run row, and the at-most-once launch fence — this
-//     adapter adds nothing to that; it only parses the paste and surfaces a human `error` banner.
+// The operator clicking Dispatch IS the approval — there is no replayable token. This door is NOT part
+// of the agent surface: the agent compile door returns only a navigational preview (no digest-as-
+// dispatch-handle), so an agent cannot reach a run through the documented surface. Idempotent: a
+// re-dispatch of an already-running run short-circuits with `alreadyRunning`. An unknown / expired /
+// superseded / already-dispatched digest is a clean 400.
 
-import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
-import { parseDeliveryGraphText } from "../app/deliveryGraphText.ts";
-import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
-import type { DeliveryCompileError, DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
+import { dispatchDeliveryGraphRun } from "../app/deliveryGraphDispatch.ts";
+import { getStagedProposal, markProposalDispatched, markProposalExpired } from "../app/deliveryGraphProposals.ts";
+import type { DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
-import startDeliveryGraph from "./startDeliveryGraph.ts";
 
-export default defineOperation("dispatchDeliveryGraph", async (input, app) => {
-  const body = input.body;
-  const parsed = parseDeliveryGraphText(body);
-  if (!parsed.ok) {
-    app.log.warn("dispatch-delivery-graph rejected: parse", { message: parsed.error });
-    return { status: 400, body: { ok: false, error: parsed.error } };
+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 === "") {
+    app.log.warn("dispatch-delivery-graph rejected: missing digest");
+    return { status: 400, body: { ok: false, error: "request body must carry a `digest` naming the staged proposal to dispatch" } };
   }
-  const approve = body?.approve === true;
-  const idemRaw = typeof body?.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
+  const idemRaw = body && typeof body === "object" && "idempotencyKey" in body && typeof body.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
   const idempotencyKey = idemRaw !== "" ? idemRaw : undefined;
 
-  // When the operator approves, derive the graph's content digest (the approval token) via the SAME
-  // pure compiler the start door uses, so a side-effecting graph they reviewed in the preview
-  // dispatches. A compile failure here surfaces as a clean 400 rather than reaching the start door.
-  let approvalToken: string | undefined;
-  if (approve) {
-    const compiled = await compileDeliveryGraph(parsed.graph);
-    if (!compiled.ok) {
-      app.log.warn("dispatch-delivery-graph rejected: compile", { errors: compiled.errors.length });
-      return {
-        status: 400,
-        body: {
-          ok: false,
-          error: `graph failed validation: ${compiled.errors.length} error(s)`,
-          errors: compiled.errors,
-        },
-      };
-    }
-    approvalToken = deliveryGraphDigest(compiled.bpmn);
+  // 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);
+  if (!proposal) {
+    app.log.warn("dispatch-delivery-graph rejected: no live staged proposal", { digest });
+    return {
+      status: 400,
+      body: { ok: false, error: `no staged proposal for digest ${digest} — it may have been dispatched, superseded, or aged out; recompile to re-stage it` },
+    };
   }
 
-  const startBody: Record<string, unknown> = { graph: parsed.graph };
-  if (approvalToken !== undefined) startBody.approvalToken = approvalToken;
-  if (idempotencyKey !== undefined) startBody.idempotencyKey = idempotencyKey;
-
-  // Delegate to the ONE dispatch contract — the exact `startDeliveryGraph` handler, no re-implementation.
-  // The parsed graph is `unknown` (the paste is runtime-validated inside the door), so the handler's
-  // typed input signature is bridged here; nothing re-implements dispatch.
-  // biome-ignore lint/plugin: bridging the runtime-validated paste onto the start door's typed input; the door owns validation.
-  const delegate = startDeliveryGraph as (
-    i: { req: unknown; params: unknown; query: unknown; body: unknown },
-    a: typeof app,
-  ) => Promise<{ status?: number; body?: Record<string, unknown> } | undefined>;
-  const res = await delegate(
-    { req: input.req, params: input.params, query: input.query, body: startBody },
-    app,
-  );
-  const resBody: Record<string, unknown> = res?.body ?? {};
-  const status = res?.status ?? 202;
-
-  // Re-shape the start door's result onto this ingress contract by narrowing each field — no assertions.
-  const outBody: DeliveryGraphTextResult = { ok: resBody.ok === true };
-  if (typeof resBody.status === "string") outBody.status = resBody.status;
-  if (typeof resBody.runKey === "string") outBody.runKey = resBody.runKey;
-  if (typeof resBody.digest === "string") outBody.digest = resBody.digest;
-  if (typeof resBody.sideEffecting === "boolean") outBody.sideEffecting = resBody.sideEffecting;
-  if (typeof resBody.alreadyRunning === "boolean") outBody.alreadyRunning = resBody.alreadyRunning;
-  if (typeof resBody.processInstanceKey === "string") outBody.processInstanceKey = resBody.processInstanceKey;
-  if (typeof resBody.processDefinitionId === "string") outBody.processDefinitionId = resBody.processDefinitionId;
-  if (typeof resBody.approvalToken === "string") outBody.approvalToken = resBody.approvalToken;
-  if (typeof resBody.message === "string") outBody.message = resBody.message;
+  // The stored graph was validated at stage time; dispatch re-compiles it to derive the run-row shape.
+  let graph: unknown;
+  try {
+    graph = JSON.parse(proposal.graph);
+  } catch (err) {
+    app.log.error("dispatch-delivery-graph: stored graph is corrupt", { digest });
+    // Fail closed: a corrupt graph can never launch, so retire the proposal (→ `expired`) instead of
+    // leaving an undismissable `staged` row that fails every dispatch attempt the same way.
+    await markProposalExpired(app.data, digest);
+    return { status: 400, body: { ok: false, error: `staged proposal ${digest} is corrupt: ${err instanceof Error ? err.message : String(err)}` } };
+  }
 
-  // Carry through the start door's path-qualified validation/compile `errors` so callers/UI keep the
-  // structured detail (not just the summary banner). Narrow each entry to the wire pair — no assertions.
-  if (Array.isArray(resBody.errors)) {
-    const errors: DeliveryCompileError[] = [];
-    for (const e of resBody.errors) {
-      if (
-        typeof e === "object" &&
-        e !== null &&
-        "path" in e &&
-        "message" in e &&
-        typeof e.path === "string" &&
-        typeof e.message === "string"
-      ) {
-        errors.push({ path: e.path, message: e.message });
-      }
-    }
-    if (errors.length > 0) outBody.errors = errors;
+  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title });
+  if (!dispatched.ok) {
+    app.log.warn("dispatch-delivery-graph refused: compile", { digest, errors: dispatched.errors.length });
+    const outBody: DeliveryGraphTextResult = {
+      ok: false,
+      error: `graph failed validation: ${dispatched.errors.length} error(s)`,
+      errors: dispatched.errors,
+    };
+    return { status: 400, body: outBody };
   }
 
-  // Surface a human error banner for the page on a refusal (parked-at-approval / validation).
-  if (status >= 400 && typeof outBody.error !== "string") {
-    if (typeof resBody.error === "string") outBody.error = resBody.error;
-    else if (typeof resBody.message === "string") outBody.error = resBody.message;
-    else if (outBody.errors !== undefined) outBody.error = `graph failed validation: ${outBody.errors.length} error(s)`;
-    else outBody.error = "dispatch was refused";
+  // Retire the proposal from the staged list — the run now shows in the in-flight grid. Guard against
+  // an `idempotencyKey` that short-circuits onto an ALREADY-running run of a DIFFERENT graph: in that
+  // case `dispatchDeliveryGraphRun` returns that other run's `digest`, so THIS proposal's graph was
+  // never launched. Consuming it then would mark a proposal `dispatched` that never ran. Only retire the
+  // proposal when the live run is genuinely this proposal's graph (`dispatched.digest === digest`).
+  if (dispatched.digest !== digest) {
+    app.log.warn("dispatch-delivery-graph refused: idempotencyKey bound to a different running graph", {
+      digest,
+      runDigest: dispatched.digest,
+      runKey: dispatched.runKey,
+    });
+    return {
+      status: 409,
+      body: {
+        ok: false,
+        error: `idempotencyKey is already bound to a different running delivery graph (digest ${dispatched.digest}); the staged proposal ${digest} was NOT dispatched — retry with a fresh idempotencyKey (or none)`,
+      },
+    };
   }
-  return { status, body: outBody };
+  await markProposalDispatched(app.data, digest);
+
+  const outBody: DeliveryGraphTextResult = {
+    ok: true,
+    status: dispatched.status,
+    runKey: dispatched.runKey,
+    digest: dispatched.digest,
+    sideEffecting: dispatched.sideEffecting,
+    alreadyRunning: dispatched.alreadyRunning,
+  };
+  if (dispatched.processInstanceKey !== undefined) outBody.processInstanceKey = dispatched.processInstanceKey;
+  if (dispatched.processDefinitionId !== undefined) outBody.processDefinitionId = dispatched.processDefinitionId;
+  return { status: 202, body: outBody };
 });

package/operations/getAgentInstructions.test.ts

@@ -52,9 +52,11 @@ test("the guide covers every capability the endpoint promises", async () => {
 
 test("the guide documents the delivery-graph surface (ADR 0005)", async () => {
   const md = ((await handler(input(), app)) as any).body.instructions as string;
-  // The two doors, with their exact action paths.
-  assert(md.includes("compile-delivery-graph"), "documents the pure compile door");
-  assert(md.includes("start/delivery-graph"), "documents the gated dispatch door");
+  // The agent surface: a single compile door that validates + previews + STAGES. There is NO agent
+  // start/dispatch door (issue #460) — dispatch is an operator action in the cockpit.
+  assert(md.includes("compile-delivery-graph"), "documents the compile+stage door");
+  assert(!md.includes("start/delivery-graph"), "does NOT expose an agent start/dispatch door (issue #460)");
+  assert(md.includes("propose → compile → stage"), "frames the agent surface as ending at stage");
   // The closed node vocabulary: assert the exact config snippet for each of the four kinds,
   // so the test fails if §9's node-kind table is removed or reworded — not merely if the bare
   // words "agent"/"wait"/"human"/"connector" appear anywhere else in the guide.
@@ -65,9 +67,11 @@ test("the guide documents the delivery-graph surface (ADR 0005)", async () => {
   // The fact-edge syntax: an edge is `{ from, to }` and `from` may be a qualified `<nodeId>.<fact>`.
   assert(md.includes("each edge is `{ from, to }`"), "documents the edge shape");
   assert(md.includes("qualified `<nodeId>.<fact>`"), "documents the qualified fact-edge syntax");
-  // The approval gate + idempotency of the start door.
-  assert(md.includes("approvalToken"), "documents the approval gate");
-  assert(md.includes("idempotencyKey"), "documents idempotency");
+  // Operator-only dispatch: the compile response carries a digest + navigational reviewUrl and the
+  // guide directs the agent to ask an operator to dispatch in the cockpit (no self-service replay).
+  assert(md.includes("reviewUrl"), "documents the navigational reviewUrl");
+  assert(md.includes("Dispatch is an operator action") || md.includes("Dispatch** in the cockpit"), "documents operator-only dispatch");
+  assert(!md.includes("approvalToken"), "the replayable approvalToken flow is gone (issue #460)");
   // The worked example: a human emit node handing a version to a downstream edge.
   assert(md.includes("manual-publish.publishedVersion"), "includes the worked example's human-emit fact edge");
 });

package/operations/previewDeliveryGraph.test.ts

@@ -1,17 +1,35 @@
-// Tests for the POST /app/api/actions/delivery-graph/preview operation `previewDeliveryGraph`
-// (issue #386, ADR 0005 slice S1) — the human-facing UI JSON-paste PREVIEW ingress. It parses the
-// operator's pasted JSON STRING and runs the SAME pure `compileDeliveryGraph` compiler the agent door
-// uses, mapping the result onto a compact summary (200) or a human `error` + path-qualified `errors`
-// (400). It is PURE — no data layer, no dispatch — so it mirrors the compile door's test harness.
+// Tests for the POST /app/api/actions/delivery-graph/preview operation `previewDeliveryGraph` (ADR
+// 0005 Decision 7, issue #460) — the human-facing UI JSON-paste PREVIEW+STAGE ingress. It parses the
+// operator's pasted JSON STRING, runs the SAME `compileDeliveryGraph` compiler the agent door uses,
+// and — like the agent compile door — persists the compiled graph as a `staged` proposal, returning a
+// compact summary (200, `staged:true` + `reviewUrl`) or a human `error` + path-qualified `errors`
+// (400). It never dispatches — that is a separate operator action on the staged proposal.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
-import type { AppApi } from "@nanobpm/urban";
+import type { AppApi, DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import { deliveryGraphProposals } from "../app/deliveryGraphProposals.ts";
 import { noopLog } from "../test/log.ts";
 import handler from "./previewDeliveryGraph.ts";
 
-const app = { log: noopLog() } as unknown as AppApi;
+const APP_ROOT = resolve(import.meta.dirname, "..");
 
-async function call(body: unknown) {
+async function withApp(fn: (app: AppApi, data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dgpreview-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    const edge = { data: app.db, log: noopLog() } as unknown as AppApi;
+    await fn(edge, app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function call(app: AppApi, body: unknown) {
   return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
 }
 
@@ -24,60 +42,81 @@ const GOOD = JSON.stringify({
   edges: [{ from: "a", to: "b" }],
 });
 
-test("preview-delivery-graph: a pasted well-formed graph → 200 summary with digest + counts", async () => {
-  const res = await call({ graphJson: GOOD });
-  assertEquals(res.status, 200);
-  assertEquals(res.body.ok, true);
-  assert(typeof res.body.digest === "string" && res.body.digest.length > 0);
-  assertEquals(res.body.nodeCount, 2);
-  assertEquals(res.body.humanNodeCount, 1);
-  assertEquals(res.body.sideEffectCount, 1);
-  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: a pasted well-formed graph → 200 summary, staged, with digest + counts", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { graphJson: GOOD });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.ok, true);
+    assertEquals(res.body.staged, true);
+    assert(typeof res.body.digest === "string" && res.body.digest.length > 0);
+    assert(typeof res.body.reviewUrl === "string" && res.body.reviewUrl.length > 0);
+    assertEquals(res.body.nodeCount, 2);
+    assertEquals(res.body.humanNodeCount, 1);
+    assertEquals(res.body.sideEffectCount, 1);
+    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);
+    // A staged proposal now exists for the operator to dispatch — and NO dispatch handle came back.
+    assertEquals((await deliveryGraphProposals(data).get(res.body.digest))?.status, "staged");
+    assertEquals(res.body.runKey, undefined);
+    assertEquals(res.body.processInstanceKey, undefined);
+  });
 });
 
-test("preview-delivery-graph: is PURE — repeated previews return the identical digest", async () => {
-  const a = await call({ graphJson: GOOD });
-  const b = await call({ graphJson: GOOD });
-  assertEquals(a.body.digest, b.body.digest);
+test("preview-delivery-graph: repeated previews stage the identical digest idempotently (one live row)", async () => {
+  await withApp(async (app, data) => {
+    const a = await call(app, { graphJson: GOOD });
+    const b = await call(app, { graphJson: GOOD });
+    assertEquals(a.body.digest, b.body.digest);
+    assertEquals((await deliveryGraphProposals(data).find({ digest: a.body.digest })).length, 1);
+  });
 });
 
-test("preview-delivery-graph: text that is not valid JSON → 400 with a human error", async () => {
-  const res = await call({ graphJson: "{ not json" });
-  assertEquals(res.status, 400);
-  assertEquals(res.body.ok, false);
-  assert(typeof res.body.error === "string" && res.body.error.includes("not valid JSON"));
+test("preview-delivery-graph: text that is not valid JSON → 400 with a human error, nothing staged", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { graphJson: "{ not json" });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(typeof res.body.error === "string" && res.body.error.includes("not valid JSON"));
+    assertEquals((await deliveryGraphProposals(data).all()).length, 0);
+  });
 });
 
 test("preview-delivery-graph: a blank paste → 400, never a 500", async () => {
-  const res = await call({ graphJson: "   " });
-  assertEquals(res.status, 400);
-  assertEquals(res.body.ok, false);
-  assert(typeof res.body.error === "string" && res.body.error.length > 0);
+  await withApp(async (app) => {
+    const res = await call(app, { graphJson: "   " });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(typeof res.body.error === "string" && res.body.error.length > 0);
+  });
 });
 
-test("preview-delivery-graph: a valid-JSON but malformed graph → 400 with path-qualified errors", async () => {
-  const res = await call({
-    graphJson: JSON.stringify({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] }),
+test("preview-delivery-graph: a valid-JSON but malformed graph → 400 with path-qualified errors, nothing staged", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, {
+      graphJson: JSON.stringify({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] }),
+    });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(Array.isArray(res.body.errors) && res.body.errors.length > 0);
+    assert(res.body.errors.every((e: { path: string; message: string }) => typeof e.path === "string"));
+    assertEquals((await deliveryGraphProposals(data).all()).length, 0);
   });
-  assertEquals(res.status, 400);
-  assertEquals(res.body.ok, false);
-  assert(Array.isArray(res.body.errors) && res.body.errors.length > 0);
-  assert(res.body.errors.every((e: { path: string; message: string }) => typeof e.path === "string"));
 });
 
 test("preview-delivery-graph: a pasted JSON array (not an object) → 400", async () => {
-  const res = await call({ graphJson: "[]" });
-  assertEquals(res.status, 400);
-  assertEquals(res.body.ok, false);
+  await withApp(async (app) => {
+    const res = await call(app, { graphJson: "[]" });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+  });
 });

package/operations/previewDeliveryGraph.ts

@@ -1,17 +1,24 @@
-// POST /app/api/actions/delivery-graph/preview → operationId `previewDeliveryGraph` (issue #386,
-// ADR 0005 slice S1). The human-facing UI JSON-paste PREVIEW ingress: the Delivery Graphs page's
-// "Preview" action posts the operator's pasted delivery-graph as a raw JSON STRING; this door parses
-// it (`parseDeliveryGraphText`) and runs the SAME pure `compileDeliveryGraph` compiler the agent-facing
-// door uses, returning a compact summary — the content `digest` (the approval token to dispatch with),
-// the node / human-stop / side-effect counts, and the mermaid `diagram`.
+// POST /app/api/actions/delivery-graph/preview → operationId `previewDeliveryGraph` (ADR 0005
+// Decision 7, issue #460). The human-facing UI JSON-paste PREVIEW+STAGE ingress: the Delivery Graphs
+// page's "Preview & stage" action posts the operator's pasted delivery-graph as a raw JSON STRING;
+// this door parses it (`parseDeliveryGraphText`) and runs the SAME `compileDeliveryGraph` compiler the
+// agent-facing door uses, and — like the agent compile door — persists the compiled graph as a
+// `staged` proposal (content-addressed by its `digest`).
 //
-// It is PURE and side-effect-free (compile and start are separate doors — Decision 5/7): nothing is
-// deployed or dispatched, so an operator can Preview repeatedly while fixing the JSON. A blank/invalid
-// paste, or a graph that fails validation, is a 400 carrying a human `error` (and, for a compile
-// failure, the path-qualified `errors`). This is a thin UI adapter over the ONE compile contract, not
-// a parallel compile path.
+// It returns a compact preview summary (the `digest`, node/human/side-effect counts, the mermaid
+// `diagram`, and the full human-stop / side-effect detail) plus a navigational `reviewUrl`. It never
+// deploys or dispatches — dispatch is a separate OPERATOR action on the staged proposal (the Dispatch
+// button on the staged-proposals grid). A blank/invalid paste, or a graph that fails validation, is a
+// 400 carrying a human `error` (and path-qualified `errors` for a compile failure); nothing is staged.
 
 import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
+import {
+  buildProposalPreview,
+  buildProposalRow,
+  proposalLogicalKey,
+  proposalReviewUrl,
+  stageProposal,
+} from "../app/deliveryGraphProposals.ts";
 import { parseDeliveryGraphText } from "../app/deliveryGraphText.ts";
 import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
@@ -34,8 +41,29 @@ export default defineOperation("previewDeliveryGraph", async ({ body }, app) =>
       },
     };
   }
+
   const digest = deliveryGraphDigest(compiled.bpmn);
-  app.log.info("preview-delivery-graph compiled", {
+  const name =
+    typeof compiled.resolved.name === "string" && compiled.resolved.name.trim() !== ""
+      ? compiled.resolved.name.trim()
+      : null;
+  const preview = buildProposalPreview(compiled);
+  await stageProposal(
+    app.data,
+    buildProposalRow({
+      digest,
+      logicalKey: proposalLogicalKey(name, digest),
+      title: name,
+      graphJson: JSON.stringify(parsed.graph),
+      preview,
+      nodeCount: compiled.resolved.nodes.length,
+      humanNodeCount: compiled.humanNodes.length,
+      sideEffectCount: compiled.sideEffects.length,
+      sideEffecting: compiled.sideEffects.length > 0,
+    }),
+  );
+
+  app.log.info("preview-delivery-graph staged", {
     nodes: compiled.resolved.nodes.length,
     humanNodes: compiled.humanNodes.length,
     sideEffects: compiled.sideEffects.length,
@@ -45,19 +73,18 @@ export default defineOperation("previewDeliveryGraph", async ({ body }, app) =>
     status: 200,
     body: {
       ok: true,
+      staged: true,
       digest,
-      ...(typeof compiled.resolved.name === "string" && compiled.resolved.name !== ""
-        ? { title: compiled.resolved.name }
-        : {}),
+      reviewUrl: proposalReviewUrl(digest),
+      ...(name !== null ? { title: name } : {}),
       sideEffecting: compiled.sideEffects.length > 0,
       nodeCount: compiled.resolved.nodes.length,
       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).
+      // side-effecting actions. The Delivery Graphs page renders these so the operator sees WHERE it
+      // parks on a person and WHAT it will do — the "preview before dispatch" principle made visible.
       humanNodes: compiled.humanNodes,
       sideEffects: compiled.sideEffects,
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.123.2",
+  "version": "0.124.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/cockpit/mount.js

@@ -319,7 +319,8 @@ function relaySocketFactory(url) {
  * @param {Element} host — where the cockpit renders (standalone: document.body; embedded: the App-View host).
  * @param {object} [opts]
  * @param {string} [opts.reportUrl] — the supply JSON endpoint the app serves (default
- *   `"app/api/agentic/supply"`, base-relative).
+ *   `new URL("../app/api/agentic/supply", import.meta.url).href`, module-anchored so it
+ *   resolves to the app root `<appMount>/app/api/agentic/supply`, not the `/cockpit/` shell base).
  * @param {string} [opts.relayUrl]  — the agentic channel WebSocket URL (with auth token + capability query).
  * @param {string} [opts.hookSecret] — shared secret sent as `x-hook-secret` on the report fetch when the
  *   app's supply endpoint is guarded by NANO_PR_WEBHOOK_SECRET (omit for open deployments).
@@ -331,7 +332,9 @@ function relaySocketFactory(url) {
  * @param {number} [opts.pastFetchTimeoutMs] — upper bound (ms) on a single past-sessions transcripts
  *   fetch; the fetch is aborted past this so a hung endpoint can't wedge the past panel (default 15000).
  * @param {string} [opts.transcriptsUrl] — the captured-session list endpoint backing the always-on
- *   "past sessions" history + replay (default `"app/api/agentic/transcripts"`, base-relative).
+ *   "past sessions" history + replay (default
+ *   `new URL("../app/api/agentic/transcripts", import.meta.url).href`, module-anchored so it
+ *   resolves to the app root `<appMount>/app/api/agentic/transcripts`, not the `/cockpit/` shell base).
  * @returns a handle with `.dispose()`.
  */
 export function mountCockpit(host, opts = {}) {
@@ -341,16 +344,20 @@ export function mountCockpit(host, opts = {}) {
     );
   }
   const doc = document;
-  // Base-relative defaults (no leading slash) so the browser resolves them against the document's
-  // baseURI. Standalone (served at the app root) this is the origin root; through the Studio console
-  // App-View the document base is the app-view path (`/console/app-view/<AppName>/`) while the iframe
-  // ORIGIN is the console (:8080) — an absolute (leading-slash) path would resolve against the console
-  // origin root (`:8080/app/api/agentic/supply` → 404) instead of the app-view base that proxies the
-  // API, leaving the cockpit empty (#279). A base-relative default lands on the right endpoint both
-  // ways, so the cockpit populates identically standalone and embedded even though the console never
-  // injects window.__NANO_APP_VIEW__.
-  const reportUrl = opts.reportUrl ?? "app/api/agentic/supply";
-  const transcriptsUrl = opts.transcriptsUrl ?? "app/api/agentic/transcripts";
+  // Default endpoints are anchored to THIS MODULE's URL (import.meta.url), NOT the document base.
+  // The API is served at the app root (`<appMount>/app/api/agentic/…`), but the cockpit shell
+  // (embed.html / standalone.html) — and therefore this mount.js — is served one directory deep at
+  // `<appMount>/cockpit/`. A document-base-relative default (`"app/api/agentic/supply"`) resolves
+  // against that `…/cockpit/` base to `…/cockpit/app/api/agentic/supply` → 404 on EVERY surface
+  // (standalone, local urban-SPA App-View embed, and the Studio console App-View, which serves the
+  // shell at `<app-view-base>/cockpit/…`), leaving the cockpit empty (#467). An absolute leading-slash
+  // path is worse still — through Studio it resolves against the console ORIGIN (:8080), not the
+  // app-view base that proxies the API (#279). mount.js is ALWAYS at `<appMount>/cockpit/mount.js`
+  // while the API is ALWAYS at `<appMount>/app/api/…`, so `../app/api/…` off import.meta.url lands on
+  // the right endpoint on all three surfaces regardless of the document base — the console never
+  // injects window.__NANO_APP_VIEW__, so this default is what actually runs there too.
+  const reportUrl = opts.reportUrl ?? new URL("../app/api/agentic/supply", import.meta.url).href;
+  const transcriptsUrl = opts.transcriptsUrl ?? new URL("../app/api/agentic/transcripts", import.meta.url).href;
   const hookSecret = opts.hookSecret;
   const relayUrl = opts.relayUrl ?? defaultRelayUrl(opts.relayToken, opts.relayCapability);
   const refreshMs = opts.refreshMs ?? DEFAULT_REFRESH_MS;