@nanobpm/nano-workforce 0.189.3 → 0.191.0

package/operations/dispatchDeliveryGraph.test.ts

@@ -13,8 +13,10 @@ 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 { redactFreeText } from "../app/deliveryGraphCompiler.ts";
 import { deliveryGraphProposals } from "../app/deliveryGraphProposals.ts";
 import { deliveryGraphRuns } from "../app/deliveryGraphRun.ts";
+import { isEquivalentReStage, stableProposalRunKey } from "./dispatchDeliveryGraph.ts";
 
 const APP_ROOT = resolve(import.meta.dirname, "..");
 const GITHUB_ENV: Record<string, string> = { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "" };
@@ -32,6 +34,74 @@ const SIDE_EFFECTING = {
   edges: [{ from: "open-b", to: "publish" }],
 };
 
+test("stableProposalRunKey: digest identity + secret disambiguation (issue #778 review)", () => {
+  // The run key is derived from the proposal's semantic `digest` (which the compiler already normalises
+  // — collapsing omitted-vs-default fields and top-level node/edge REORDER) PLUS a fingerprint of the
+  // digest-invisible raw values. So a re-stage of the SAME logical graph in ANY encoding sharing the
+  // digest short-circuits, while a credential-differing graph (same digest, different secret) diverges.
+  const D1 = "sha-aaa";
+  const D2 = "sha-bbb";
+  const credA = {
+    name: "g",
+    nodes: [{ id: "n", kind: "connector", connector: { target: "//user:pass@host" } }],
+    edges: [],
+  };
+  // Same digest + identical graph → same key (a double-click / re-dispatch short-circuits).
+  assert.equal(stableProposalRunKey(D1, credA), stableProposalRunKey(D1, credA));
+  // Same digest but a DIFFERENT redacted-away credential — both redact to the same `//***@host` display
+  // so they SHARE the digest — must yield a DIFFERENT key, else the second dispatch collapses onto the
+  // first's still-running instance.
+  const credB = { name: "g", nodes: [{ id: "n", kind: "connector", connector: { target: "//other:secret@host" } }], edges: [] };
+  assert.notEqual(stableProposalRunKey(D1, credA), stableProposalRunKey(D1, credB));
+  // A genuinely different semantic graph carries a DIFFERENT digest → a different key even with no secrets.
+  const plain = { name: "g", nodes: [{ id: "n", kind: "human", human: { prompt: "x" } }], edges: [] };
+  assert.notEqual(stableProposalRunKey(D1, plain), stableProposalRunKey(D2, plain));
+  // A graph with NO digest-invisible content has an EMPTY fingerprint, so its key is a pure function of
+  // the digest: a re-stage in a DIFFERENT object-key encoding (same digest) short-circuits.
+  const plainReordered = { edges: [], name: "g", nodes: [{ human: { prompt: "x" }, kind: "human", id: "n" }] };
+  assert.equal(stableProposalRunKey(D1, plain), stableProposalRunKey(D1, plainReordered));
+  assert.ok(stableProposalRunKey(D1, credA).startsWith("staged-"), "the key is self-describing");
+});
+
+test("stableProposalRunKey: node-ORDER of digest-invisible content does not fork the key (issue #778 review)", () => {
+  // The compiler SORTS nodes before emitting `semanticBpmn`, so two graphs differing ONLY in top-level
+  // node order share one digest. Their digest-invisible raw values (`digestInvisibleRawValues`) must
+  // therefore fingerprint identically too — else a re-stage of the same logical graph in a different
+  // node encoding forks a DISTINCT run-key and double-launches instead of short-circuiting. The
+  // fingerprint is code-unit sorted at its source, making it reorder-invariant like the digest.
+  const D = "sha-order";
+  const ab = {
+    name: "g",
+    nodes: [
+      { id: "a", kind: "connector", connector: { target: "//user:pass@host" } },
+      { id: "b", kind: "connector", connector: { target: "//other:secret@host" } },
+    ],
+    edges: [],
+  };
+  const ba = {
+    name: "g",
+    nodes: [
+      { id: "b", kind: "connector", connector: { target: "//other:secret@host" } },
+      { id: "a", kind: "connector", connector: { target: "//user:pass@host" } },
+    ],
+    edges: [],
+  };
+  assert.equal(stableProposalRunKey(D, ab), stableProposalRunKey(D, ba), "a top-level node reorder must not fork the run-key");
+});
+
+test("isEquivalentReStage: only a live staged row whose RAW graph JSON is byte-identical to the launched graph is an equivalent re-stage — a credential-different re-stage (same digest) is NOT, and a retired/consumed row (null) is NOT (issue #778 review — thread dispatchDeliveryGraph.ts:320)", () => {
+  const launched = JSON.stringify({ name: "g", nodes: [{ id: "n", kind: "connector", connector: { target: "//user:pass@host" } }], edges: [] });
+  // A byte-identical re-stage IS equivalent — the door consumes the duplicate at its bumped revision.
+  assert.equal(isEquivalentReStage({ graph: launched }, launched), true);
+  // A credential-different re-stage shares the redacted digest but its RAW graph differs, so it is a
+  // newer, never-launched revision the door must leave `staged`.
+  const credDifferent = JSON.stringify({ name: "g", nodes: [{ id: "n", kind: "connector", connector: { target: "//other:secret@host" } }], edges: [] });
+  assert.equal(isEquivalentReStage({ graph: credDifferent }, launched), false);
+  // No live staged row (consumed/dismissed/superseded/expired) → not equivalent, nothing to consume.
+  assert.equal(isEquivalentReStage(null, launched), false);
+  assert.equal(isEquivalentReStage(undefined, launched), false);
+});
+
 describe("dispatchDeliveryGraph — operator dispatch by staged-proposal digest", () => {
   const dirs: string[] = [];
   const apps: TestApp[] = [];
@@ -165,6 +235,138 @@ describe("dispatchDeliveryGraph — operator dispatch by staged-proposal digest"
     assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
   });
 
+  test("a SAME-payload retry of a secret-bearing graph under the SAME idempotencyKey (a lost response / double-click) → 202 short-circuit, the proposal IS consumed and NO second run launches — the persisted identity fingerprint PROVES the running run is this exact graph, so the idempotency contract holds instead of a spurious 409 (issue #778 review — thread dispatchDeliveryGraph.ts:332)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    let agentFired = 0;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return {};
+    });
+
+    // Stage + dispatch a SECRET-BEARING graph (SIDE_EFFECTING carries redacted-away secret material —
+    // the same graph the cross-graph 409 case above refuses) under an explicit idempotencyKey. It
+    // launches and parks on its human node, so its run stays `running`.
+    const first = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SIDE_EFFECTING });
+    const dispatched = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: first.body.digest, idempotencyKey: "retry-key", repoless: true },
+    });
+    assert.equal(dispatched.status, 202);
+    await app.settle();
+    assert.equal(agentFired, 1, "the side effect fired exactly once on the first dispatch");
+    assert.equal((await deliveryGraphProposals(app.db).get(first.body.digest))?.status, "dispatched");
+
+    // Re-stage the IDENTICAL graph (byte-for-byte the same → same digest) and re-dispatch under the
+    // SAME key — the caller retrying a lost/duplicated request. The running run's persisted fingerprint
+    // matches this graph, so the door short-circuits onto it (202, alreadyRunning) and CONSUMES the
+    // re-staged proposal — it does NOT 409 as a cross-graph collision would.
+    const restaged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SIDE_EFFECTING });
+    assert.equal(restaged.body.digest, first.body.digest);
+    assert.equal((await deliveryGraphProposals(app.db).get(restaged.body.digest))?.status, "staged");
+    const retry = await api.call<{ ok: boolean; status: string; alreadyRunning?: boolean }>("dispatchDeliveryGraph", {
+      body: { digest: restaged.body.digest, idempotencyKey: "retry-key", repoless: true },
+    });
+    assert.equal(retry.status, 202);
+    assert.equal(retry.body.ok, true);
+    assert.equal(retry.body.alreadyRunning, true);
+    await app.settle();
+    // The retry short-circuited onto the existing run — the side effect did NOT fire a second time and
+    // no second run launched.
+    assert.equal(agentFired, 1, "a same-payload retry does not re-fire the side effect");
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+    // The re-staged proposal was consumed (marked dispatched), not left lingering.
+    assert.equal((await deliveryGraphProposals(app.db).get(restaged.body.digest))?.status, "dispatched");
+  });
+
+  test("an explicit idempotencyKey short-circuit onto a running SECRET-BEARING run, re-dispatched from a graph authored AS the redacted form (graphCarriesRedactedSecrets === false) that SHARES the digest → 409; the proposal is NOT consumed (the refusal must not be gated on the INCOMING graph's redaction side — identity is unprovable whenever !identityConfirmed) (thread dispatchDeliveryGraph.ts:320)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+
+    // Graph 1 CARRIES a redacted-away credential in its human prompt — its content-addressed digest is
+    // over the REDACTED display, so it is NOT a faithful identity. It parks on its human node and stays
+    // running under an explicit idempotencyKey.
+    const secretPrompt = "click done: https://user:pass@host";
+    const SECRET = { name: "manual gate", nodes: [{ id: "ack", kind: "human", human: { prompt: secretPrompt } }] };
+    // Graph 2 is authored LITERALLY as the redacted form of graph 1's prompt. Redaction is a no-op on it,
+    // so `graphCarriesRedactedSecrets` is FALSE, yet it SHARES graph 1's digest (both digest over the same
+    // redacted display). It is a DIFFERENT graph from the running secret-bearing run.
+    const redactedTwin = { name: "manual gate", nodes: [{ id: "ack", kind: "human", human: { prompt: redactFreeText(secretPrompt) } }] };
+
+    // Stage + dispatch the SECRET-bearing graph FIRST (before the twin re-stages over its same-digest
+    // row) under an explicit key — it launches and parks (running), stamping its LOSSLESS fingerprint.
+    const g1 = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SECRET });
+    const first = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: g1.body.digest, idempotencyKey: "shared-key", repoless: true },
+    });
+    assert.equal(first.status, 202);
+    await app.settle();
+    assert.equal((await deliveryGraphProposals(app.db).get(g1.body.digest))?.status, "dispatched");
+
+    // Now re-stage the redacted-twin at the SAME digest (a DIFFERENT graph re-staged over the consumed
+    // row) and dispatch it under the SAME key. It short-circuits onto the still-running SECRET run — but
+    // that run is a different graph, so its persisted fingerprint does NOT match (identityConfirmed ===
+    // false). The digest COLLISION is the crux: the twin shares graph 1's digest yet carries no redacted
+    // secret. The refusal must fire even though the INCOMING graph carries no redacted secret; otherwise
+    // the twin's proposal is marked `dispatched` while it never launched.
+    const twin = await api.call<{ digest: string }>("compileDeliveryGraph", { body: redactedTwin });
+    assert.equal(twin.body.digest, g1.body.digest);
+    assert.equal((await deliveryGraphProposals(app.db).get(twin.body.digest))?.status, "staged");
+    const second = await api.call<{ ok: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: twin.body.digest, idempotencyKey: "shared-key", repoless: true },
+    });
+    assert.equal(second.status, 409);
+    assert.equal(second.body.ok, false);
+    await app.settle();
+    // The twin proposal is still staged — it was never launched (the running run is the secret graph).
+    assert.equal((await deliveryGraphProposals(app.db).get(twin.body.digest))?.status, "staged");
+    // Only the single secret run exists — the twin dispatch launched nothing.
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+  });
+
+  test("a KEYLESS short-circuit onto a running graph whose run key equals the shared digest (an earlier explicit `idempotencyKey === digest`), re-dispatched from a redacted-twin that SHARES the digest → 409; the proposal is NOT consumed. The ambiguous-identity refusal must gate EVERY `alreadyRunning && !identityConfirmed`, not only explicit-key requests — a keyless faithful-digest dispatch collides on the digest run key just the same (thread dispatchDeliveryGraph.ts:325)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+
+    // Graph 1 CARRIES a redacted-away credential — its digest is over the REDACTED display, NOT a faithful
+    // identity. Dispatch it under an explicit `idempotencyKey` set to its OWN digest, so the run is keyed
+    // by the digest itself and parks running, stamping graph 1's LOSSLESS fingerprint.
+    const secretPrompt = "click done: https://user:pass@host";
+    const SECRET = { name: "manual gate", nodes: [{ id: "ack", kind: "human", human: { prompt: secretPrompt } }] };
+    // Graph 2 is authored LITERALLY as the redacted form — redaction is a no-op on it, so
+    // `graphCarriesRedactedSecrets` is FALSE. Because it is faithful, a KEYLESS dispatch leaves the run key
+    // undefined and the core falls back to the digest — which it SHARES with graph 1, colliding onto that
+    // still-running secret run even though NO explicit key was supplied.
+    const redactedTwin = { name: "manual gate", nodes: [{ id: "ack", kind: "human", human: { prompt: redactFreeText(secretPrompt) } }] };
+
+    const g1 = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SECRET });
+    const first = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: g1.body.digest, idempotencyKey: g1.body.digest, repoless: true },
+    });
+    assert.equal(first.status, 202);
+    await app.settle();
+    assert.equal((await deliveryGraphProposals(app.db).get(g1.body.digest))?.status, "dispatched");
+
+    // Re-stage the twin at the SAME digest and dispatch it WITHOUT a key. It short-circuits onto the
+    // running secret run (same digest run key), but that run is a different graph → identityConfirmed is
+    // false. The refusal must fire despite the request being keyless; otherwise the twin is marked
+    // `dispatched` while it never launched.
+    const twin = await api.call<{ digest: string }>("compileDeliveryGraph", { body: redactedTwin });
+    assert.equal(twin.body.digest, g1.body.digest);
+    assert.equal((await deliveryGraphProposals(app.db).get(twin.body.digest))?.status, "staged");
+    const second = await api.call<{ ok: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: twin.body.digest, repoless: true },
+    });
+    assert.equal(second.status, 409);
+    assert.equal(second.body.ok, false);
+    await app.settle();
+    // The twin proposal is still staged — nothing new launched.
+    assert.equal((await deliveryGraphProposals(app.db).get(twin.body.digest))?.status, "staged");
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+  });
+
   test("a proposal whose stored graph is corrupt JSON → 400 AND the proposal is retired (expired), never lingering staged", async () => {
     const app = await boot();
     assert.ok(app.api);
@@ -251,6 +453,59 @@ describe("dispatchDeliveryGraph — operator dispatch by staged-proposal digest"
     assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "dispatched");
   });
 
+  test("a SECRET-BEARING staged graph dispatches through the cockpit UI WITHOUT an idempotencyKey — the door supplies a stable server-side key (#778)", async () => {
+    // Regression: Option C's dispatch gate refuses a keyless dispatch of a graph whose digest is lossy,
+    // but the cockpit staged-proposals UI posts no idempotency-key field. The door must therefore derive
+    // a stable server-side key from the stored proposal so these proposals remain launchable.
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const SECRET = { name: "deploy", nodes: [{ id: "d", kind: "agent", agent: { jobType: "senior:demo", prompt: "push to https://user:pass@host.example/repo" } }] };
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SECRET });
+    // No idempotencyKey in the body — exactly what the staged UI posts.
+    const res = await api.call<{ ok: boolean; status: string; runKey: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, repoless: true },
+    });
+    assert.equal(res.status, 202);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.status, "running");
+    assert.ok(res.body.runKey.startsWith("staged-"), `expected a server-side staged- key, got ${res.body.runKey}`);
+    await app.settle();
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "dispatched");
+  });
+
+  test("an explicit idempotencyKey re-used across two SECRET-differing graphs that SHARE a digest is refused at short-circuit → 409; the re-staged proposal is NOT consumed and nothing new launches (#778 review — thread dispatchDeliveryGraph.ts:282)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    // Two graphs differing ONLY in a redacted-away credential redact to the SAME `semanticBpmn`, so they
+    // share ONE content digest and therefore ONE digest-keyed proposal row.
+    const SECRET_A = { name: "deploy", nodes: [{ id: "d", kind: "agent", agent: { jobType: "senior:demo", prompt: "push to https://user:AAAsecret@host.example/repo" } }] };
+    const SECRET_B = { name: "deploy", nodes: [{ id: "d", kind: "agent", agent: { jobType: "senior:demo", prompt: "push to https://user:BBBsecret@host.example/repo" } }] };
+    const a = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SECRET_A });
+    // Dispatch A under an explicit shared key — it launches and parks (running).
+    const first = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: a.body.digest, idempotencyKey: "shared-key", repoless: true },
+    });
+    assert.equal(first.status, 202);
+    await app.settle();
+    // B re-stages the SAME digest-keyed proposal row (its credential differs, but the digest is identical).
+    const b = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SECRET_B });
+    assert.equal(b.body.digest, a.body.digest, "the two secret-differing graphs must share one redacted digest");
+    // Dispatch B under the SAME shared key — it short-circuits onto A's still-running run. Because the
+    // digest cannot prove the running run is THIS (secret-bearing) graph, B must NOT be consumed: 409.
+    const second = await api.call<{ ok: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: b.body.digest, idempotencyKey: "shared-key", repoless: true },
+    });
+    assert.equal(second.status, 409);
+    assert.equal(second.body.ok, false);
+    await app.settle();
+    // The proposal is still staged (never falsely consumed) and only A's single run exists.
+    assert.equal((await deliveryGraphProposals(app.db).get(b.body.digest))?.status, "staged");
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+  });
+
   test("a malformed `repository` is rejected at submit → 400, nothing launched (#684/#686)", async () => {
     const app = await boot();
     assert.ok(app.api);

package/operations/dispatchDeliveryGraph.ts

@@ -10,8 +10,10 @@
 // re-dispatch of an already-running run short-circuits with `alreadyRunning`. An unknown / expired /
 // superseded / already-dispatched digest is a clean 400.
 
+import { createHash } from "node:crypto";
 import { isPlausibleBranchName } from "../app/baseBranch.ts";
-import { validateDeliveryGraph } from "../app/deliveryGraph.ts";
+import { canonicalJson, validateDeliveryGraph } from "../app/deliveryGraph.ts";
+import { digestInvisibleRawValues, graphCarriesRedactedSecrets } from "../app/deliveryGraphCompiler.ts";
 import { dispatchDeliveryGraphRun } from "../app/deliveryGraphDispatch.ts";
 import { getStagedProposal, markProposalDispatched, markProposalExpired } from "../app/deliveryGraphProposals.ts";
 import { unresolvedAgentRepoNodes } from "../app/deliveryRunner.ts";
@@ -28,6 +30,46 @@ function truncateForEcho(value: string): string {
   return value.length > MAX_ECHO_LEN ? `${value.slice(0, MAX_ECHO_LEN)}… (${value.length} chars)` : value;
 }
 
+/** A STABLE, server-side dispatch run key for a secret-bearing staged proposal (issue #778, Option C).
+ * The graph's identity is content-addressed over the REDACTED `semanticBpmn` digest, so two graphs
+ * differing ONLY in a redacted-away credential (or other {@link digestInvisibleRawValues} content) share
+ * one digest — a keyless dispatch would collapse the second onto the first's still-running instance. The
+ * dispatch core therefore REQUIRES an explicit key for such a graph, but the cockpit's staged-proposals
+ * UI posts no idempotency-key field. The operator clicking Dispatch on THIS specific stored proposal is
+ * unambiguous, so we derive a key from TWO parts:
+ *   • the proposal's semantic `digest` — which the compiler already normalises: it collapses every
+ *     omitted-vs-default field (`edges`/`emits` → `[]`, a `false` boolean vs an absent one, …) and any
+ *     top-level node/edge REORDER, so a re-stage of the same logical graph in a different encoding — which
+ *     shares the digest and OVERWRITES `proposal.graph` — yields the SAME key and short-circuits as
+ *     `alreadyRunning` instead of double-launching (issue #778 review, thread on omitted-vs-empty), and
+ *   • a fingerprint of {@link digestInvisibleRawValues} — the exact raw content the digest CANNOT see —
+ *     so a credential-differing proposal (identical digest) gets a DISTINCT key. That traversal now emits
+ *     its entries in a canonical (code-unit sorted) order, so it too collapses a top-level node reorder:
+ *     the fingerprint is reorder-invariant, matching the digest, so the whole key short-circuits a
+ *     re-stage of the same logical graph regardless of node encoding order (issue #778 review).
+ * Deriving both parts from the digest + the shared invisible-values traversal means the key needs NO
+ * per-field enumeration of the compiler's defaults (which would drift), while still disambiguating on
+ * every secret the digest drops. Prefixed so it is self-describing in run listings. */
+export function stableProposalRunKey(digest: string, graph: DeliveryGraph): string {
+  const fingerprint = canonicalJson(digestInvisibleRawValues(graph));
+  return `staged-${createHash("sha256").update(`${digest}\u0000${fingerprint}`).digest("hex").slice(0, 16)}`;
+}
+
+/** After the terminal `markProposalDispatched` no-oped — the digest row left the `stage_seq` this dispatch
+ * snapshotted between its `getStagedProposal` load and its mark — decide whether the still-`staged` row is
+ * an EQUIVALENT re-stage of the graph we just launched: a BYTE-IDENTICAL graph re-staged into the same
+ * digest row in that window (which bumps `stage_seq`). It is equivalent iff a live staged row is still
+ * present AND its raw graph JSON is byte-identical to the launched one. We compare the LOSSLESS raw
+ * `proposal.graph` (not the lossy semantic `digest`, which collapses credential-different graphs onto one
+ * key), so a genuinely different (e.g. credential-different) re-stage is NOT mistaken for equivalent. When
+ * true the door consumes the duplicate at its current revision — otherwise it would linger as an
+ * undismissable `staged` row every future dispatch short-circuits onto the already-running run without
+ * consuming; when false the row is a newer, never-launched revision the door must leave `staged` (issue
+ * #778 review — thread dispatchDeliveryGraph.ts:320). */
+export function isEquivalentReStage(reloaded: { graph: string } | null | undefined, launchedGraphJson: string): boolean {
+  return !!reloaded && reloaded.graph === launchedGraphJson;
+}
+
 /** 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. */
@@ -155,14 +197,23 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
   }
 
   // The stored graph was validated at stage time; dispatch re-compiles it to derive the run-row shape.
+  // Snapshot the proposal's stage revision NOW so the terminal `markProposalDispatched` can guard its
+  // flip against a concurrent re-stage that overwrites this same-digest row with a newer graph after we
+  // read it (issue #778 review — thread dispatchDeliveryGraph.ts:243).
+  const stageSeq = proposal.stage_seq;
   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);
+    // leaving an undismissable `staged` row that fails every dispatch attempt the same way. Guard the
+    // expiry on the SAME `stage_seq` we read the corrupt graph at — a concurrent re-stage that overwrites
+    // this same-digest row with a fresh (valid) graph in the window between `getStagedProposal` and this
+    // update bumps `stage_seq`, so the guard makes the expiry a no-op rather than retiring a revision we
+    // never inspected (issue #778 review — thread dispatchDeliveryGraph.ts:188, same revision guard as the
+    // terminal `markProposalDispatched` below).
+    await markProposalExpired(app.data, digest, stageSeq);
     return { status: 400, body: { ok: false, error: `staged proposal ${digest} is corrupt: ${err instanceof Error ? err.message : String(err)}` } };
   }
 
@@ -196,7 +247,27 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
     }
   }
 
-  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title, repository, baseBranch, repoless, ...timeouts });
+  // Derive the dispatch run key (issue #778, Option C). Honour an explicit operator-supplied
+  // `idempotencyKey` verbatim — a BLANK/whitespace-only key is already normalised to `undefined` at the
+  // request edge (`idemRaw`/`idempotencyKey` above), so `=== undefined` here covers both "omitted" and
+  // "blank" (issue #778 review — thread dispatchDeliveryGraph.ts:243, already handled upstream). When the
+  // staged graph carries credential-bearing values that redaction strips from the content-addressed
+  // digest, that digest is NOT a faithful identity — two credential-differing graphs share it — so a
+  // keyless dispatch is refused by the dispatch core. The cockpit UI posts no idempotency-key field, so
+  // supply a STABLE server-side key derived from THIS proposal's parsed graph in canonical form
+  // (`stableProposalRunKey`); a faithful-digest graph keeps its digest identity (key left undefined). A
+  // malformed graph falls through to the core's own validation.
+  let dispatchRunKey: string | undefined = idempotencyKey;
+  if (dispatchRunKey === undefined) {
+    const graphErrors = validateDeliveryGraph(graph);
+    if (graphErrors.length === 0) {
+      // biome-ignore lint/plugin: validated staged graph narrowed to its contract after validateDeliveryGraph
+      const typedGraph = graph as DeliveryGraph;
+      if (graphCarriesRedactedSecrets(typedGraph)) dispatchRunKey = stableProposalRunKey(digest, typedGraph);
+    }
+  }
+
+  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: dispatchRunKey, title: proposal.title, repository, baseBranch, repoless, expectedDigest: digest, ...timeouts });
   if (!dispatched.ok) {
     app.log.warn("dispatch-delivery-graph refused: compile", { digest, errors: dispatched.errors.length });
     const outBody: DeliveryGraphTextResult = {
@@ -226,7 +297,87 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
       },
     };
   }
-  await markProposalDispatched(app.data, digest);
+
+  // Even when `dispatched.digest === digest`, that equality does NOT prove the short-circuited run is
+  // THIS graph: the digest is content-addressed over the REDACTED `semanticBpmn`, so two graphs whose
+  // AUTHORED values differ only in redacted-away material share it (the very reason a keyless secret-
+  // bearing dispatch is refused upstream). An EXPLICIT `idempotencyKey` bypasses the lossless server-side
+  // `stableProposalRunKey`, so a caller who re-uses one key across two such digest-colliding graphs (which
+  // occupy the SAME digest-keyed proposal row, one re-staged over the other) would short-circuit onto the
+  // FIRST graph's still-running run — `dispatched.alreadyRunning` — while the re-staged graph never
+  // launched. Consuming the proposal then marks a graph `dispatched` that never ran. The run row now
+  // persists a LOSSLESS identity fingerprint (migration 113), and the dispatch core reports
+  // `identityConfirmed` — true when the running run's fingerprint MATCHES this graph's, i.e. a legitimate
+  // SAME-payload retry (a lost response / operator double-click of the identical proposal).
+  //
+  // The proof is the fingerprint MATCH, NOT the redaction side of the INCOMING graph: the ambiguity is
+  // symmetric. A secret-bearing running run collides in digest with a graph authored LITERALLY as its
+  // redacted form (`https://***@host`) — that incoming graph has `graphCarriesRedactedSecrets === false`,
+  // yet it is a DIFFERENT graph from the running run, so short-circuiting onto it is just as unprovable.
+  // Gating the refusal on the incoming graph's own redaction let that authored-as-redacted twin slip
+  // through and consume the running secret run's proposal (issue #778 review — thread
+  // dispatchDeliveryGraph.ts:320). So refuse the genuinely ambiguous CROSS-graph short-circuit whenever
+  // `!identityConfirmed` (which also covers a NULL pre-migration fingerprint we cannot prove), regardless
+  // of which side carries the redacted value; a same-payload retry (`identityConfirmed`) falls through and
+  // consumes the proposal, preserving the idempotency contract rather than 409-ing an identical retry
+  // (issue #778 review — thread dispatchDeliveryGraph.ts:332).
+  //
+  // The gate must fire for a KEYLESS request too, not only an explicit `idempotencyKey`. A faithful-digest
+  // graph (no redacted secret) dispatched WITHOUT a key leaves `dispatchRunKey` undefined, so the core
+  // falls back to the DIGEST as the run key — which a redacted twin SHARES with an earlier run that was
+  // itself keyed by that digest (e.g. an explicit `idempotencyKey === digest`). The keyless twin then
+  // short-circuits onto that different graph's run with `identityConfirmed === false`, so scoping the
+  // refusal to explicit-key requests would mark the twin `dispatched` though it never ran. `identityConfirmed`
+  // is derived from the running run's persisted fingerprint, NOT from whether a key was supplied, so a
+  // legitimate keyless same-payload retry still confirms and falls through — only a genuinely unprovable
+  // short-circuit is refused (issue #778 review — thread dispatchDeliveryGraph.ts:325).
+  if (dispatched.alreadyRunning && !dispatched.identityConfirmed) {
+    app.log.warn("dispatch-delivery-graph refused: already-running short-circuit cannot prove the running run is this graph", {
+      digest,
+      runKey: dispatched.runKey,
+    });
+    return {
+      status: 409,
+      body: {
+        ok: false,
+        error:
+          `this graph short-circuited onto an already-running delivery graph whose identity fingerprint does not match it, ` +
+          `so its content-addressed digest (${digest}) cannot prove the running run is this exact graph; the staged proposal was NOT ` +
+          "dispatched — re-dispatch with a distinct idempotencyKey per graph (or none, to use the lossless server-side key)",
+      },
+    };
+  }
+  const marked = await markProposalDispatched(app.data, digest, stageSeq);
+  if (!marked) {
+    // The row left the `staged` revision we snapshotted between our load and this flip. Distinguish the
+    // two reasons it moved, because they need OPPOSITE handling:
+    //   (a) an EQUIVALENT re-stage bumped `stage_seq` on a BYTE-IDENTICAL graph in our window — the run
+    //       we launched IS that graph, so the still-`staged` row is a duplicate of what we just
+    //       dispatched. Leaving it `staged` wedges an undismissable proposal that every future dispatch
+    //       short-circuits onto our already-running run without ever consuming (issue #778 review — thread
+    //       dispatchDeliveryGraph.ts:320). Consume it at its CURRENT revision.
+    //   (b) a re-stage overwrote it with a DIFFERENT (credential-different) graph, or a
+    //       dispatch/dismiss/supersede/expiry retired it — a newer, never-launched revision we must NOT
+    //       clobber to `dispatched`.
+    // Re-load and let `isEquivalentReStage` compare the LOSSLESS raw graph JSON (not the lossy digest,
+    // which collapses credential-different graphs): byte-identical ⇒ equivalent re-stage (a), else (b).
+    const restaged = await getStagedProposal(app.data, digest);
+    if (isEquivalentReStage(restaged, proposal.graph)) {
+      const consumed = await markProposalDispatched(app.data, digest, restaged?.stage_seq);
+      app.log.warn("dispatch-delivery-graph: equivalent re-stage consumed at bumped revision", {
+        digest,
+        stageSeq,
+        restagedSeq: restaged?.stage_seq,
+        consumed,
+      });
+    } else {
+      // A concurrent dispatch consumed it, or a re-stage overwrote it with a newer graph (bumping
+      // stage_seq), or a dismiss/supersede/expiry retired it. The run we launched still stands; we
+      // intentionally skip the mark so a newer, never-launched revision is not clobbered to `dispatched`
+      // (issue #778 review).
+      app.log.warn("dispatch-delivery-graph: staged revision changed before consume; mark skipped", { digest, stageSeq });
+    }
+  }
 
   const outBody: DeliveryGraphTextResult = {
     ok: true,

package/operations/getAgentInstructions.test.ts

@@ -40,7 +40,8 @@ test("the guide covers every capability the endpoint promises", async () => {
   const md = ((await handler(input(), app)) as any).body.instructions as string;
   // Submit a PR (converge vs. merge), submit an epic, answer escalations…
   assert(md.includes("start/convergence-loop"), "covers submitting a PR for convergence");
-  assert(md.includes("convergeOnly"), "documents review-only vs. merge");
+  assert(md.includes("autoMerge"), "documents the per-request merge control");
+  assert(!md.includes("convergeOnly"), "does not expose the legacy merge control in agent guidance");
   assert(md.includes("start/plan-fanout"), "covers submitting an epic");
   assert(md.includes("complete-user-task"), "covers answering escalations via the native user-task door");
   // …debug the system.

package/operations/startAndMessage.test.ts

@@ -143,15 +143,57 @@ test("startConvergenceLoop forwards convergeOnly:true to the loop", async () =>
   });
 });
 
+test("startConvergenceLoop maps autoMerge:true to merge-enabled convergence", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp, get } = captureApp();
+    const res = await startConvergenceLoop(input({ pr: "owner/repo#9", autoMerge: true }), capApp);
+    assertEquals((res as any).status, 202);
+    assertEquals(get(), false);
+  });
+});
+
+test("startConvergenceLoop maps autoMerge:false to review-only convergence", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp, get } = captureApp();
+    const res = await startConvergenceLoop(input({ pr: "owner/repo#10", autoMerge: false }), capApp);
+    assertEquals((res as any).status, 202);
+    assertEquals(get(), true);
+  });
+});
+
+test("startConvergenceLoop lets autoMerge override the legacy convergeOnly alias", async () => {
+  await withGithubOff(async () => {
+    const merge = captureApp();
+    const mergeRes = await startConvergenceLoop(
+      input({ pr: "owner/repo#13", autoMerge: true, convergeOnly: true }),
+      merge.app,
+    );
+    assertEquals((mergeRes as any).status, 202);
+    assertEquals(merge.get(), false);
+
+    const review = captureApp();
+    const reviewRes = await startConvergenceLoop(
+      input({ pr: "owner/repo#14", autoMerge: false, convergeOnly: false }),
+      review.app,
+    );
+    assertEquals((reviewRes as any).status, 202);
+    assertEquals(review.get(), true);
+  });
+});
+
 test("startConvergenceLoop defaults convergeOnly to false and does not truthy-coerce a non-boolean", async () => {
   await withGithubOff(async () => {
     const omitted = captureApp();
-    await startConvergenceLoop(input({ pr: "owner/repo#9" }), omitted.app);
+    await startConvergenceLoop(input({ pr: "owner/repo#11" }), omitted.app);
     assertEquals(omitted.get(), false);
 
     const stringy = captureApp();
-    await startConvergenceLoop(input({ pr: "owner/repo#10", convergeOnly: "true" }), stringy.app);
+    await startConvergenceLoop(input({ pr: "owner/repo#12", convergeOnly: "true" }), stringy.app);
     assertEquals(stringy.get(), false);
+
+    const stringyAutoMerge = captureApp();
+    await startConvergenceLoop(input({ pr: "owner/repo#15", autoMerge: "true" }), stringyAutoMerge.app);
+    assertEquals(stringyAutoMerge.get(), false);
   });
 });
 

package/operations/startConvergenceLoop.ts

@@ -3,13 +3,15 @@
 // external webhook relay, a CI job, and Swagger all POST here. Parse the PR reference and
 // register/refresh the PR aggregate (idempotent on prKey) before starting the loop.
 //
-// The request body is FLAT (`{ pr | url, dependsOn?, maxRounds?, convergeOnly? }`), not wrapped in a
-// `variables` envelope: this is a purpose-built operation, not a generic engine "start process" call,
-// so it does not leak the engine's variable-map concept to callers. The body is a `oneOf` — EXACTLY
-// ONE of `pr` or `url` — so the runtime rejects an empty or ambiguous target at the edge (a 400 that
-// names the allowed shapes); this delegate no longer coalesces `pr ?? url`, it just narrows the
-// validated variant. It keeps the PR-parse guard because the reference FORMAT (owner/repo#123 or a
-// URL) is app logic the JSON schema can't express — an unparseable reference is a 400.
+// The request body is FLAT (`{ pr | url, dependsOn?, maxRounds?, autoMerge?, convergeOnly? }`), not
+// wrapped in a `variables` envelope: this is a purpose-built operation, not a generic engine "start
+// process" call, so it does not leak the engine's variable-map concept to callers. `autoMerge` is
+// the positive, preferred form for UI/API callers; `convergeOnly` remains a legacy negative alias.
+// When both are present, `autoMerge` wins. The body is a `oneOf` — EXACTLY ONE of `pr` or `url` — so
+// the runtime rejects an empty or ambiguous target at the edge (a 400 that names the allowed
+// shapes); this delegate no longer coalesces `pr ?? url`, it just narrows the validated variant. It
+// keeps the PR-parse guard because the reference FORMAT (owner/repo#123 or a URL) is app logic the
+// JSON schema can't express — an unparseable reference is a 400.
 
 import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
@@ -29,9 +31,10 @@ export default defineOperation("startConvergenceLoop", async ({ body }, app) =>
   }
   const dependsOn = body.dependsOn ?? [];
   const maxRounds = clampRounds(body.maxRounds, MAX_ROUNDS);
-  // Per-request review-only override: when true the PR stops at `converged` and is never
-  // handed to the merge-loop, regardless of the global NANO_PR_AUTO_MERGE default.
-  const convergeOnly = body.convergeOnly === true;
+  // Prefer the positive autoMerge form so an unchecked UI box is explicitly review-only. Legacy
+  // callers that omit autoMerge retain the existing convergeOnly/global-default behavior.
+  const hasAutoMerge = typeof body.autoMerge === "boolean";
+  const convergeOnly = hasAutoMerge ? body.autoMerge !== true : body.convergeOnly === true;
   const result = await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, convergeOnly);
   app.log.info("convergence loop started", {
     prKey: parsed.prKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.189.3",
+  "version": "0.191.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/home.page.json

@@ -105,8 +105,8 @@
             "type": "number"
           },
           {
-            "key": "convergeOnly",
-            "label": "Converge only \u2014 stop at review consensus, do not merge",
+            "key": "autoMerge",
+            "label": "Auto-merge \u2014 after convergence, drive the merge-loop",
             "type": "checkbox"
           }
         ]