@nanobpm/nano-workforce 0.180.0 → 0.182.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.182.0](https://github.com/nanobpm/nano-workforce/compare/v0.181.0...v0.182.0) (2026-09-04)
+
+### Features
+
+* stamp each agent node's repository for per-node delivery-graph isolation ([#742](https://github.com/nanobpm/nano-workforce/issues/742)) ([e8dcdfc](https://github.com/nanobpm/nano-workforce/commit/e8dcdfce2122bdb2a7e881a0900ca1f607d6d402)), closes [#739](https://github.com/nanobpm/nano-workforce/issues/739)
+
+## [0.181.0](https://github.com/nanobpm/nano-workforce/compare/v0.180.0...v0.181.0) (2026-09-04)
+
+### Features
+
+* delivery-graph MCP DX — interleaved sequence gates, paginated guide sections, stage-supersede visibility ([#741](https://github.com/nanobpm/nano-workforce/issues/741)) ([6f10e8a](https://github.com/nanobpm/nano-workforce/commit/6f10e8a25721645af4e5f932f2cbaa9ad6025b70)), closes [#740](https://github.com/nanobpm/nano-workforce/issues/740) [#460](https://github.com/nanobpm/nano-workforce/issues/460) [#740](https://github.com/nanobpm/nano-workforce/issues/740)
+
 ## [0.180.0](https://github.com/nanobpm/nano-workforce/compare/v0.179.2...v0.180.0) (2026-09-04)
 
 ### Features

package/app/agentGuide.test.ts

@@ -10,9 +10,11 @@ import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import {
   GUIDE_SECTIONS,
+  GUIDE_SECTION_PAGE_DEFAULT,
   guideToc,
   renderAgentGuide,
   renderGuideSection,
+  renderGuideSectionChunk,
   splitGuideSections,
 } from "./agentGuide.ts";
 
@@ -105,6 +107,91 @@ test("an unknown section id resolves to undefined (the op turns that into a 400)
   assertEquals(renderGuideSection("does-not-exist", "https://x/app/api"), undefined);
 });
 
+// ── Paginated section retrieval (issue #740) ────────────────────────────────────────────────────
+
+test("renderGuideSectionChunk: paging through a section reassembles it exactly, chunk by chunk", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("delivery-graphs", base)!;
+  const totalChars = Array.from(full).length;
+  const PAGE = 4000;
+  let start = 0;
+  let assembled = "";
+  let pages = 0;
+  let lastTotal = -1;
+  // Follow the nextStart cursor until it is null — the classic pagination loop.
+  for (;;) {
+    const chunk = renderGuideSectionChunk("delivery-graphs", base, start, PAGE)!;
+    assert(chunk, "a known section must page");
+    assert(Array.from(chunk.instructions).length <= PAGE, "a page must be bounded by the window");
+    assertEquals(chunk.start, start);
+    assertEquals(chunk.totalLength, totalChars);
+    if (lastTotal !== -1) assertEquals(chunk.totalLength, lastTotal);
+    lastTotal = chunk.totalLength;
+    assembled += chunk.instructions;
+    pages++;
+    if (chunk.nextStart === null) break;
+    start = chunk.nextStart;
+    assert(pages < 100, "pagination must terminate");
+  }
+  assert(pages > 1, "a large section must span multiple pages at this window");
+  assertEquals(assembled, full, "the reassembled pages must equal the whole section");
+});
+
+test("renderGuideSectionChunk: a window past the end returns an empty last page with nextStart null", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("orient", base)!;
+  const total = Array.from(full).length;
+  const chunk = renderGuideSectionChunk("orient", base, total + 500, 100)!;
+  assertEquals(chunk.start, total);
+  assertEquals(chunk.length, 0);
+  assertEquals(chunk.instructions, "");
+  assertEquals(chunk.nextStart, null);
+});
+
+test("renderGuideSectionChunk: the first page of a fitting section equals the whole section (nextStart null)", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("orient", base)!;
+  const chunk = renderGuideSectionChunk("orient", base, 0, GUIDE_SECTION_PAGE_DEFAULT)!;
+  // `orient` fits well under the default page, so one page carries it whole with no continuation.
+  assertEquals(chunk.instructions, full);
+  assertEquals(chunk.nextStart, null);
+});
+
+test("renderGuideSectionChunk: a zero-length window on a non-empty section terminates (nextStart null, no loop)", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("delivery-graphs", base)!;
+  assert(Array.from(full).length > 0, "precondition: the section has content");
+  // A caller (or a direct invoker bypassing the op's `length >= 1` validation) that asks for a
+  // zero-length window gets an empty page — but `nextStart` MUST be null so a "page until nextStart
+  // is null" loop cannot spin forever on a cursor that never advances.
+  const chunk = renderGuideSectionChunk("delivery-graphs", base, 0, 0)!;
+  assertEquals(chunk.start, 0);
+  assertEquals(chunk.length, 0);
+  assertEquals(chunk.instructions, "");
+  assertEquals(chunk.nextStart, null);
+});
+
+test("renderGuideSectionChunk: an unknown section id is undefined (the op turns that into a 400)", () => {
+  assertEquals(renderGuideSectionChunk("does-not-exist", "https://x/app/api", 0, 100), undefined);
+});
+
+test("renderGuideSectionChunk: chunk boundaries never split a multi-byte character", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("delivery-graphs", base)!;
+  // Page at every 1-char window across a stretch that contains the guide's arrows/emoji; each
+  // reassembled result must round-trip losslessly (no U+FFFD replacement from a split code point).
+  let assembled = "";
+  let start = 0;
+  for (let i = 0; i < 200 && start < Array.from(full).length; i++) {
+    const chunk = renderGuideSectionChunk("delivery-graphs", base, start, 7)!;
+    assembled += chunk.instructions;
+    if (chunk.nextStart === null) break;
+    start = chunk.nextStart;
+  }
+  assert(!assembled.includes("\uFFFD"), "no replacement characters — code points were never split");
+  assertEquals(assembled, Array.from(full).slice(0, Array.from(assembled).length).join(""));
+});
+
 test("no content regression: each section body is a verbatim slice of the raw guide", () => {
   // Rendering keys examples to an instance; the UN-substituted section bodies must be exact
   // substrings of the authored doc, so the addressable surface never rewrites guide content.

package/app/agentGuide.ts

@@ -174,3 +174,64 @@ export function renderGuideSection(id: string, apiBase: string): string | undefi
   const base = apiBase.replace(/\/+$/, "");
   return section.body.replaceAll("__BASE__", base).replaceAll("__ENGINE__", resolveEngineBase());
 }
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// Paginated section retrieval (issue #740).
+//
+// The addressable guide exists to avoid the ~43KB monolith, but a single section can ITSELF overflow
+// a typical MCP tool-result limit — `delivery-graphs` alone renders to ~25KB, the one section an
+// author most needs. So a section is additionally retrievable in BOUNDED CHUNKS via a `start`/`length`
+// window with a `nextStart` continuation cursor. Offsets are UNICODE CHARACTER (code-point) offsets —
+// NOT raw byte offsets — so a chunk boundary never splits a multi-byte character (the arrows/emoji in
+// the guide) into mojibake. A plain `renderGuideSection` (no window) is untouched, so existing
+// `section=<id>` calls that already fit stay byte-for-byte identical.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/** The default window size (characters) when a caller engages pagination without an explicit
+ *  `length` — comfortably under a typical MCP tool-result limit so a single page never overflows. */
+export const GUIDE_SECTION_PAGE_DEFAULT = 12_000;
+
+/** One page of a section's markdown: the `instructions` slice plus the cursor state so a caller can
+ *  page through with `nextStart` until it is `null`. Offsets/lengths are CHARACTER counts. */
+export interface GuideSectionChunk {
+  readonly instructions: string;
+  /** The (clamped) character offset this page starts at. */
+  readonly start: number;
+  /** The number of characters actually returned in this page. */
+  readonly length: number;
+  /** The total number of characters in the fully-rendered section. */
+  readonly totalLength: number;
+  /** The character offset to pass as `start` for the next page, or `null` when this is the last page. */
+  readonly nextStart: number | null;
+}
+
+/** Render a bounded WINDOW of a single section's markdown for a given app control-API base, with
+ *  `__BASE__`/`__ENGINE__` substituted exactly as {@link renderGuideSection} does. `start` and
+ *  `length` are CHARACTER offsets (clamped to the section bounds; a non-positive `length` yields an
+ *  empty page). Returns `undefined` for an unknown id (the caller turns that into a 400). */
+export function renderGuideSectionChunk(
+  id: string,
+  apiBase: string,
+  start: number,
+  length: number,
+): GuideSectionChunk | undefined {
+  const full = renderGuideSection(id, apiBase);
+  if (full === undefined) return undefined;
+  const chars = Array.from(full);
+  const total = chars.length;
+  const from = Math.min(Math.max(0, Math.trunc(start)), total);
+  const take = Math.max(0, Math.trunc(length));
+  const slice = chars.slice(from, from + take);
+  const end = from + slice.length;
+  return {
+    instructions: slice.join(""),
+    start: from,
+    length: slice.length,
+    totalLength: total,
+    // Only advance when this page actually consumed characters. A zero-length window (`length <= 0`)
+    // returns an empty page that made NO progress, so it must terminate the cursor (`null`) rather
+    // than hand back a `nextStart` equal to `start` — a non-advancing cursor would loop a caller
+    // that pages until `nextStart` is null forever.
+    nextStart: slice.length > 0 && end < total ? end : null,
+  };
+}

package/app/deliveryGraph.ts

@@ -19,8 +19,10 @@
 // Every error carries a JSON-path-qualified `path` (`nodes[2].kind`, `edges[1].from`, …) so the
 // caller can point the author straight at the offending input.
 
+import { isPlausibleBranchName } from "./baseBranch.ts";
 import { isConvergeTarget } from "./convergeTargets.ts";
 import { isRawConvergeMergeJobType, NODE_COMPLETION_POLICIES } from "./nodePolicy.ts";
+import { isResolvableRepo } from "./repoEnvelope.ts";
 
 /** The CLOSED node-kind allowlist (ADR 0005 Decision 2) — the trust boundary. Extensible only by a
  * deliberate ADR/PR (add the openapi variant + a case here), never by a graph author. Kept as the
@@ -94,6 +96,8 @@ export type DeliveryGraphErrorCode =
   | "raw-converge-node"
   | "merge-requires-converge"
   | "converge-merge-type"
+  | "invalid-node-repository"
+  | "invalid-node-base-branch"
   | "unbound-pr";
 
 /** A single semantic validation failure. `path` is a JSON-path-qualified pointer at the offending
@@ -164,7 +168,7 @@ const GRAPH_NAME_MAX_LENGTH = 255;
  * like the library import/save doors' `graphJson`, where the schema never touches the parsed value)
  * would otherwise let an oversized-but-compilable graph reach the layout/compiler and be persisted —
  * both violating the declared contract and exposing the import path to avoidable CPU/memory growth. */
-const GRAPH_MAX_NODES = 256;
+export const GRAPH_MAX_NODES = 256;
 const GRAPH_MAX_EDGES = 1024;
 const NODE_MAX_EMITS = 32;
 
@@ -428,6 +432,31 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
             code: "merge-requires-converge",
           });
         }
+        // #739: an `agent` node may declare its OWN `repository` (`owner/repo`) + `baseBranch`, so a
+        // cross-repo graph provisions each cell's isolation envelope from that node's own repo (no
+        // uniform run-level repo, no `repoless`). Both are OPTIONAL (absent → the run-level fallback),
+        // but a PRESENT value must pass the SAME allowlists the dispatch door / `repoEnvelopeVars` apply
+        // — a plain `owner/repo` (no `.git`, no host/query chars) and a plausible git branch name — so a
+        // graph that bypassed OpenAPI shape validation cannot smuggle a malformed clone URL / ref past
+        // this gate into the per-node envelope. Rejected path-qualified rather than silently dropped.
+        if (kind === "agent" && config.repository !== undefined && !isResolvableRepo(config.repository)) {
+          errors.push({
+            path: `${path}.${configKey}.repository`,
+            message:
+              "`agent.repository`, when present, must be an `owner/repo` reference (no trailing `.git`, no " +
+              `host/query characters) — got ${JSON.stringify(config.repository)} (#739)`,
+            code: "invalid-node-repository",
+          });
+        }
+        if (kind === "agent" && config.baseBranch !== undefined && (typeof config.baseBranch !== "string" || !isPlausibleBranchName(config.baseBranch))) {
+          errors.push({
+            path: `${path}.${configKey}.baseBranch`,
+            message:
+              "`agent.baseBranch`, when present, must be a plausible git branch name (no whitespace, shell " +
+              `metacharacters, leading \`-\`, \`..\`/\`//\`, etc.) — got ${JSON.stringify(config.baseBranch)} (#739)`,
+            code: "invalid-node-base-branch",
+          });
+        }
         // #548: register a converge-connector / pr-wait as a PR-binding consumer (pass 4 validates the
         // binding once edges are resolved). Only when the id is usable so pass 4 can key by node id.
         if (typeof id === "string" && id.length > 0) {

package/app/deliveryGraphCompiler.ts

@@ -45,6 +45,18 @@ import {
   validateDeliveryGraph,
 } from "./deliveryGraph.ts";
 import { DELIVERY_HUMAN_ELEMENT, GENERIC_HUMAN_FORM } from "./deliveryHuman.ts";
+import { AGENT_TASK_NS } from "./repoEnvelope.ts";
+
+/** The task-header key that carries an `agent` node's DECLARED per-node repository spec (#739) into the
+ * compiled BPMN. It is a DIGEST-STABLE, env-free marker — pure graph content — so two graphs differing
+ * only in a node's declared `repository`/`baseBranch` content-address differently (they are different
+ * graphs), while the env-dependent parts of the real envelope (`cloneTimeoutMs`) and the run-level
+ * FALLBACK repo are NOT baked here (they are injected by the runner POST-digest, so the same graph in
+ * two environments / two runs still shares one id). The runner replaces this single marker header on
+ * every agent service task with the flattened EFFECTIVE `io.nanobpm.agentTask.*` envelope headers
+ * (declared ?? run-level), or strips it for an unresolved/`repoless` cell. The `__` prefix marks it as
+ * an internal marker the harness never reads. */
+export const AGENT_REPO_SPEC_HEADER = `${AGENT_TASK_NS}.__repoSpec`;
 
 /** The engine-native BODY every node kind delegates to (Decision 2 — the graph SCHEDULES, it does not
  * re-implement execution). Each node compiles to an EMBEDDED `bpmn:subProcess` (call activities are a
@@ -1027,7 +1039,7 @@ function innerBodyLines(w: NodeWiring, requiredEmits: ReadonlySet<string>): stri
       // as a required data dependency. A broken producer (returns `in_progress`, or omits a required
       // emit) escalates AT this node instead of threading an incomplete result onward.
       const contractGate = { requiredEmits: normaliseEmits(node).filter((f) => requiredEmits.has(f.name)) };
-      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], node.agent.jobType, contractGate);
+      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], node.agent.jobType, contractGate, agentRepoSpecHeaderLines(node));
     }
     case "connector":
       return serviceBodyLines(el, node.id, `type="${DELEGATE_TASK_TYPE.connector}"`, [], `connector → ${node.connector.target}`);
@@ -1040,11 +1052,25 @@ function innerBodyLines(w: NodeWiring, requiredEmits: ReadonlySet<string>): stri
   }
 }
 
+/** Render the DECLARED per-node repository-spec marker task header (#739) for an `agent` node — a single
+ * `<zeebe:taskHeaders>` block carrying {@link AGENT_REPO_SPEC_HEADER} with a compact JSON of the node's
+ * DECLARED `{ repository, baseBranch }` (each `null` when absent). It is emitted on EVERY agent service
+ * task (even one with no declared repo → `{"repository":null,"baseBranch":null}`) so the runner has a
+ * single, uniform anchor to replace with the effective envelope on every cell. Digest-stable and
+ * env-free — only the declared values (pure graph content) appear here; the run-level fallback and the
+ * env-dependent `cloneTimeoutMs` are injected by the runner POST-digest. Declared values pass the
+ * `owner/repo` + branch-name allowlists (validator/OpenAPI), so the JSON carries no XML-hostile chars. */
+function agentRepoSpecHeaderLines(node: Extract<DeliveryNode, { kind: "agent" }>): string[] {
+  const trimOrNull = (v: unknown): string | null => (typeof v === "string" && v.trim() !== "" ? v.trim() : null);
+  const spec = JSON.stringify({ repository: trimOrNull(node.agent.repository), baseBranch: trimOrNull(node.agent.baseBranch) });
+  return [
+    "          <zeebe:taskHeaders>",
+    `            <zeebe:header key="${AGENT_REPO_SPEC_HEADER}" ${attr("value", spec)} />`,
+    "          </zeebe:taskHeaders>",
+  ];
+}
+
 /** `agent`/`connector` body: `start → serviceTask → end`, with a bounded `=nodeTimeout` boundary that
- * escalates the stalled node onto a human-completable user task. `taskDefAttr` is the pre-rendered
- * `type="…"` attribute; `taskProps` are optional `<zeebe:property>` envelope lines; `descriptor`
- * names the stalled work (job type / connector target) for the escalation task's context line (#499). */
-/** The FEEL boolean an `agent` node's producer-contract gate (issue #731) evaluates on its `_gate`
  * exclusive split's SUCCESS flow: the completion proceeds onward only when the self-reported `status`
  * is a terminal success (or absent/null) AND every required-data-dependency emit is populated non-null.
  * Reads the job's returned variables from the subProcess scope (the emit source var for an agent fact
@@ -1095,23 +1121,16 @@ function serviceBodyLines(
   taskProps: readonly string[],
   descriptor: string,
   contractGate?: { requiredEmits: readonly DeliveryFact[] },
+  taskHeaders: readonly string[] = [],
 ): string[] {
   const esc = escalationTaskElement(el);
-  const taskExt =
-    taskProps.length > 0
-      ? [
-          "        <bpmn:extensionElements>",
-          `          <zeebe:taskDefinition ${taskDefAttr} />`,
-          "          <zeebe:properties>",
-          ...taskProps,
-          "          </zeebe:properties>",
-          "        </bpmn:extensionElements>",
-        ]
-      : [
-          "        <bpmn:extensionElements>",
-          `          <zeebe:taskDefinition ${taskDefAttr} />`,
-          "        </bpmn:extensionElements>",
-        ];
+  const taskExt = [
+    "        <bpmn:extensionElements>",
+    `          <zeebe:taskDefinition ${taskDefAttr} />`,
+    ...(taskProps.length > 0 ? ["          <zeebe:properties>", ...taskProps, "          </zeebe:properties>"] : []),
+    ...taskHeaders,
+    "        </bpmn:extensionElements>",
+  ];
   const timeoutEscalation = escalationTaskLines(
     esc,
     nodeId,

package/app/deliveryGraphProposals.test.ts

@@ -178,6 +178,47 @@ test("stageProposal: proposals with DIFFERENT logical keys coexist — supersede
   });
 });
 
+// ── StageOutcome visibility (issue #740) ────────────────────────────────────────────────────────
+test("stageProposal outcome: a FIRST stage reports nothing superseded and no live siblings", async () => {
+  await withData(async (data) => {
+    const outcome = await stageProposal(data, row({ digest: "d1" }));
+    assertEquals(outcome.row.digest, "d1");
+    assertEquals(outcome.superseded, []);
+    assertEquals(outcome.siblingsStaged, 0);
+  });
+});
+
+test("stageProposal outcome: a same-logical-key re-stage reports the retired digest in `superseded`", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row({ digest: "d1" }));
+    const outcome = await stageProposal(data, row({ digest: "d2" })); // same logical_key "runbook"
+    assertEquals(outcome.row.digest, "d2");
+    assertEquals(outcome.superseded, ["d1"], "the prior same-key staged digest was retired");
+    assertEquals(outcome.siblingsStaged, 0, "no OTHER-logical-key live proposal exists");
+  });
+});
+
+test("stageProposal outcome: an idempotent re-stage of the SAME live digest supersedes nothing", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row({ digest: "d1", createdAt: "2999-01-01T00:00:00.000Z" }));
+    const outcome = await stageProposal(data, row({ digest: "d1", createdAt: "2999-01-01T00:00:00.000Z" }));
+    assertEquals(outcome.row.digest, "d1");
+    assertEquals(outcome.superseded, [], "re-staging the identical live digest retires nothing");
+    assertEquals(outcome.siblingsStaged, 0);
+  });
+});
+
+test("stageProposal outcome: an orphan sibling under a DIFFERENT logical key is counted in `siblingsStaged`", async () => {
+  await withData(async (data) => {
+    // The footgun: a renamed graph stages under a new logical key without superseding the old one.
+    await stageProposal(data, row({ digest: "d1", logicalKey: "runbook-old" }));
+    const outcome = await stageProposal(data, row({ digest: "d2", logicalKey: "runbook-new" }));
+    assertEquals(outcome.row.digest, "d2");
+    assertEquals(outcome.superseded, [], "a different logical key supersedes nothing");
+    assertEquals(outcome.siblingsStaged, 1, "the still-live orphan under the old key is visible");
+  });
+});
+
 test("stageProposal: reconciles to EXACTLY ONE live proposal — an older stage whose supersede pass runs AFTER a newer stage neither clobbers it (zero) nor coexists with it (two)", async () => {
   await withData(async (data) => {
     const table = deliveryGraphProposals(data);
@@ -200,6 +241,25 @@ test("stageProposal: reconciles to EXACTLY ONE live proposal — an older stage
   });
 });
 
+test("stageProposal outcome: `row` reflects the POST-reconcile status — a stage immediately superseded by a newer sibling reports its own row as `superseded`, not the pre-reconcile `staged`", async () => {
+  await withData(async (data) => {
+    const table = deliveryGraphProposals(data);
+    // A newer staged sibling (d2) is already committed for logical_key "runbook".
+    const newer = row({ digest: "d2" });
+    newer.updated_at = "2999-01-01T00:00:00.000Z";
+    await table.insert(newer);
+    // The older stage (d1) runs last; the reconcile immediately supersedes its own row.
+    const outcome = await stageProposal(data, row({ digest: "d1" }));
+    assertEquals(outcome.row.digest, "d1");
+    assertEquals(
+      outcome.row.status,
+      "superseded",
+      "the returned row is re-read post-reconcile, matching what is actually persisted",
+    );
+    assertEquals((await table.get("d1"))?.status, "superseded");
+  });
+});
+
 test("getStagedProposal: an EXPIRED staged proposal is not live", async () => {
   await withData(async (data) => {
     await stageProposal(data, row());

package/app/deliveryGraphProposals.ts

@@ -153,6 +153,27 @@ export function buildProposalRow(input: {
   };
 }
 
+/** The outcome of a {@link stageProposal} — the written row PLUS a supersede/sibling summary the stage
+ * doors surface so an agent can warn the operator precisely about what its stage did to the cockpit's
+ * Delivery Graphs list (issue #740). Supersede keys on the LOGICAL graph key (derived from the graph
+ * `name`), so re-staging the "same" runbook under a CHANGED `name` creates a sibling with a different
+ * logical key that is NOT superseded — a silent footgun. Making the collision VISIBLE here (rather than
+ * silent) lets the agent tell the operator exactly which digests it retired and how many other live
+ * proposals remain (potential orphaned siblings). */
+export interface StageOutcome {
+  /** The row this stage wrote, RE-READ after the supersede reconcile so it reflects the actually-
+   * persisted state (a concurrent newer stage can leave this digest `superseded` immediately). */
+  row: DeliveryGraphProposal;
+  /** Digests of OTHER proposals sharing this row's logical key that this stage flipped to
+   * `superseded` — the same-logical-graph proposals it cleanly replaced. Empty on a first stage. */
+  superseded: string[];
+  /** How many OTHER live `staged` proposals remain after this stage (a DIFFERENT logical key from this
+   * row) — i.e. proposals this stage did NOT supersede. A non-zero count flags possible orphaned
+   * siblings (e.g. an earlier stage of the same runbook under a different `name`) cluttering the
+   * operator's list, so the agent can name them for cleanup. */
+  siblingsStaged: number;
+}
+
 /** Persist a compiled graph as a `staged` proposal and SUPERSEDE any prior staged proposal for the
 * same logical graph. Idempotent on `digest` (a re-stage of an identical, still-live digest refreshes
 * `updated_at` but preserves `created_at`, so the TTL stays anchored to the first stage; a re-stage of
@@ -162,10 +183,20 @@ export function buildProposalRow(input: {
  * exactly one live proposal per logical graph (the latest digest the operator would dispatch). The
  * supersede RECONCILES to the globally-newest staged row (`updated_at`, `digest`-tie-broken) rather than
  * flipping only rows older than the just-written one, so concurrent stages of two different digests
- * converge to EXACTLY ONE live proposal — never zero, and never two — regardless of arrival order. */
-export async function stageProposal(data: DataLayer, row: DeliveryGraphProposal): Promise<DeliveryGraphProposal> {
+ * converge to EXACTLY ONE live proposal — never zero, and never two — regardless of arrival order.
+ *
+ * Returns a {@link StageOutcome} — the written row plus the supersede/sibling summary (issue #740) the
+ * stage doors surface so an agent can warn the operator precisely about siblings it did / did not
+ * retire. */
+export async function stageProposal(data: DataLayer, row: DeliveryGraphProposal): Promise<StageOutcome> {
   const table = deliveryGraphProposals(data);
   const existing = await table.get(row.digest);
+  // Capture the same-logical-key staged siblings that exist BEFORE this stage writes (excluding our own
+  // digest) — the supersede reconcile below normally flips them all to `superseded`; we re-read them
+  // after to report exactly which digests this stage retired.
+  const priorSameKey = (await table.find({ status: "staged" })).filter(
+    (r) => r.logical_key === row.logical_key && r.digest !== row.digest && isLiveStaged(r),
+  );
   const toWrite = existing
     ? buildProposalRow({
         digest: row.digest,
@@ -208,7 +239,34 @@ export async function stageProposal(data: DataLayer, row: DeliveryGraphProposal)
       `UPDATE "delivery_graph_proposals" SET "status" = 'superseded', "updated_at" = ? WHERE "logical_key" = ? AND "status" = 'staged' AND EXISTS (SELECT 1 FROM "delivery_graph_proposals" AS "newer" WHERE "newer"."logical_key" = "delivery_graph_proposals"."logical_key" AND "newer"."status" = 'staged' AND ("newer"."updated_at" > "delivery_graph_proposals"."updated_at" OR ("newer"."updated_at" = "delivery_graph_proposals"."updated_at" AND "newer"."digest" > "delivery_graph_proposals"."digest")))`,
       [now(), row.logical_key],
     );
-  return toWrite;
+
+  // Report what the stage did to siblings (issue #740). `superseded` = the same-logical-key proposals
+  // this stage retired (re-read post-reconcile so a concurrent newer stage that kept ITS row live —
+  // leaving ours superseded — is reported honestly). `siblingsStaged` = OTHER live staged proposals
+  // with a DIFFERENT logical key that remain (the orphaned-sibling footgun: a re-stage under a changed
+  // `name` never supersedes them).
+  // Re-check ONLY the pre-stage staged siblings captured above (typically zero or a handful of
+  // concurrently-live same-key rows), reporting exactly those this reconcile flipped to `superseded`.
+  // Re-reading each `priorSameKey` digest keeps staging O(live same-key siblings) — a global
+  // `find({ status: "superseded" })` scans EVERY superseded row ever written (proposals are never
+  // deleted) and grows without bound. Matching strictly on `status === "superseded"` (not merely
+  // `!== "staged"`) avoids misreporting a sibling that concurrently went `dispatched`/`dismissed`/
+  // `expired`.
+  const superseded: string[] = [];
+  for (const prev of priorSameKey) {
+    const after = await table.get(prev.digest);
+    if (after?.status === "superseded") superseded.push(prev.digest);
+  }
+  const siblingsStaged = (await listStagedProposals(data)).filter((r) => r.logical_key !== row.logical_key).length;
+
+  // Re-read the just-written row AFTER the reconcile so `row` reports the ACTUALLY-persisted state, not
+  // the pre-reconcile `toWrite`: a concurrent newer stage of a different digest can flip THIS digest to
+  // `superseded` in the reconcile above, so returning `toWrite` (still `staged`) would report a status
+  // that doesn't match the DB. Fall back to `toWrite` only if the row somehow vanished (it shouldn't —
+  // we just wrote it), keeping the return non-null.
+  const persisted = (await table.get(toWrite.digest)) ?? toWrite;
+
+  return { row: persisted, superseded, siblingsStaged };
 }
 
 /** The ONE definition of "a live, dispatchable-RIGHT-NOW staged proposal" (issue #608): the row is

package/app/deliveryGraphStage.ts

@@ -39,6 +39,10 @@ export interface StagedResult {
   nodeCount: number;
   humanNodeCount: number;
   sideEffectCount: number;
+  /** Digests of same-logical-graph proposals this stage superseded (issue #740). */
+  superseded: string[];
+  /** How many OTHER live staged proposals remain after this stage — potential orphaned siblings. */
+  siblingsStaged: number;
 }
 
 /** A rejected compile — the `CompileDeliveryGraphErrors` body, verbatim from the compiler. */
@@ -75,7 +79,7 @@ export async function compileAndStageDeliveryGraph(
       ? result.resolved.name.trim()
       : null;
   const preview = buildProposalPreview(result);
-  await stageProposal(
+  const outcome = await stageProposal(
     data,
     buildProposalRow({
       digest,
@@ -99,10 +103,16 @@ export async function compileAndStageDeliveryGraph(
       digest,
       preview,
       reviewUrl: proposalReviewUrl(digest, origin),
+      // Supersede/sibling visibility (issue #740): the agent surfaces these so the operator learns
+      // precisely which prior proposals this stage retired and whether other live proposals remain.
+      superseded: outcome.superseded,
+      siblingsStaged: outcome.siblingsStaged,
     },
     digest,
     nodeCount: result.resolved.nodes.length,
     humanNodeCount: result.humanNodes.length,
     sideEffectCount: result.sideEffects.length,
+    superseded: outcome.superseded,
+    siblingsStaged: outcome.siblingsStaged,
   };
 }