@nanobpm/nano-workforce 0.180.0 → 0.181.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

@@ -164,7 +164,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;
 

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,
   };
 }

package/app/sequenceIssues.test.ts

@@ -184,3 +184,134 @@ test("sequenceIssues: more than the max issues → rejected", () => {
   const issues = rejects({ issues: many });
   assert(issues.some((i) => i.path === "issues"));
 });
+
+// ── Interleaved gates (issue #740) ──────────────────────────────────────────────────────────────
+
+test("sequenceIssues: the issue's example — an npm gate between two issues generates a wait[npm] node gating the agent on prior merge AND publish", () => {
+  const graph = ok({
+    issues: [
+      "nanobpm/nano-ide#557",
+      { gate: { kind: "npm", target: "@nanobpm/agentic@0.13.0" }, issue: "jwulf/c8ctl-plugin-nano#186" },
+      "nanobpm/nano-workforce#738",
+    ],
+  });
+  // 3 issues × 3 canonical nodes + 1 interleaved gate node = 10.
+  assertEquals(graph.nodes.length, 10);
+  const gate = graph.nodes.find((n) => n.id === "gate-2");
+  assert(gate, "the interleaved gate node must exist");
+  assertEquals(gate.kind, "wait");
+  assertEquals(gate.wait.kind, "npm");
+  assertEquals(gate.wait.target, "@nanobpm/agentic@0.13.0");
+  // The gate carries the bounded default budget (not the 30-min trap).
+  assertEquals(gate.wait.poll, { everyMs: 300_000, timeoutMs: 259_200_000 });
+  assertEquals(gate.wait.onTimeout, "escalate");
+  // Gated on the prior merge: merged-1 → gate-2. Gated on the publish → the agent waits on the gate:
+  // gate-2 → open-2. Together the agent (open-2) starts only after issue-1 merged AND the npm publish.
+  assert(graph.edges.some((e) => e.from === "merged-1" && e.to === "gate-2"), "gate waits on the prior merge");
+  assert(graph.edges.some((e) => e.from === "gate-2" && e.to === "open-2"), "the agent waits on the gate");
+  // No direct merged-1 → open-2 edge — the gate is spliced in between.
+  assert(!graph.edges.some((e) => e.from === "merged-1" && e.to === "open-2"), "the gate replaces the direct sequence edge");
+  // The third (ungated) issue still sequences directly off the second's merge.
+  assert(graph.edges.some((e) => e.from === "merged-2" && e.to === "open-3"), "an ungated issue keeps the direct sequence edge");
+});
+
+test("sequenceIssues: a gate on the FIRST issue behind an epic gate chains gate-epic → gate-1 → open-1", () => {
+  const graph = ok({
+    behind: "acme/repo#100",
+    issues: [{ gate: { kind: "github-check", target: "acme/repo@main" }, issue: "acme/repo#1" }],
+  });
+  assert(graph.nodes.some((n) => n.id === "gate-epic"), "the leading epic gate exists");
+  assert(graph.nodes.some((n) => n.id === "gate-1"), "the interleaved first-issue gate exists");
+  assert(graph.edges.some((e) => e.from === "gate-epic" && e.to === "gate-1"), "epic gate → interleaved gate");
+  assert(graph.edges.some((e) => e.from === "gate-1" && e.to === "open-1"), "interleaved gate → agent");
+  assert(!graph.edges.some((e) => e.from === "gate-epic" && e.to === "open-1"), "the interleaved gate is spliced before the agent");
+});
+
+test("sequenceIssues: a gated first issue with NO behind gate starts the gate immediately (no predecessor edge)", () => {
+  const graph = ok({ issues: [{ gate: { kind: "npm", target: "pkg@1.0.0" }, issue: "acme/repo#1" }] });
+  // No inbound edge to gate-1 (nothing precedes it); the agent still waits on the gate.
+  assert(!graph.edges.some((e) => e.to === "gate-1"), "an ungated-first gate has no predecessor edge");
+  assert(graph.edges.some((e) => e.from === "gate-1" && e.to === "open-1"), "the agent waits on the gate");
+});
+
+test("sequenceIssues: a gate's `kind`/`target` are trimmed before validation AND persistence (no whitespace-poisoned probe)", () => {
+  // Surrounding whitespace must neither trip a confusing "unknown kind" rejection nor survive into
+  // the generated `wait` node, where a stray trailing space silently probes the wrong target.
+  const graph = ok({ issues: [{ gate: { kind: " npm ", target: " pkg@1.0.0 " }, issue: "acme/repo#1" }] });
+  const gate = graph.nodes.find((n) => n.id === "gate-1");
+  assert(gate, "the interleaved gate node must exist");
+  assertEquals(gate.wait.kind, "npm");
+  assertEquals(gate.wait.target, "pkg@1.0.0");
+});
+
+test("sequenceIssues: an object entry accepts optional gate fields (match, poll, onTimeout, credentialEnv)", () => {
+  const graph = ok({
+    issues: [
+      {
+        gate: {
+          kind: "http",
+          target: "https://example.test/ready",
+          match: { status: 200 },
+          poll: { everyMs: 1000, timeoutMs: 60000 },
+          onTimeout: "continue",
+          credentialEnv: "MY_TOKEN",
+        },
+        issue: "acme/repo#1",
+      },
+    ],
+  });
+  const gate = graph.nodes.find((n) => n.id === "gate-1");
+  assertEquals(gate.wait.match, { status: 200 });
+  assertEquals(gate.wait.poll, { everyMs: 1000, timeoutMs: 60000 });
+  assertEquals(gate.wait.onTimeout, "continue");
+  assertEquals(gate.wait.credentialEnv, "MY_TOKEN");
+});
+
+test("sequenceIssues: a bare-string entry is byte-for-byte identical to the object form without a gate", () => {
+  const bare = ok({ issues: ["acme/repo#1", "acme/repo#2"] });
+  const objs = ok({ issues: [{ issue: "acme/repo#1" }, { issue: "acme/repo#2" }] });
+  assertEquals(objs.nodes, bare.nodes);
+  assertEquals(objs.edges, bare.edges);
+});
+
+test("sequenceIssues: a graph with an interleaved gate passes validateDeliveryGraph AND compiles", async () => {
+  const graph = ok({
+    issues: [
+      "acme/repo#1",
+      { gate: { kind: "npm", target: "@scope/pkg@2.0.0" }, issue: "acme/repo#2" },
+    ],
+  });
+  assertEquals(validateDeliveryGraph(graph), []);
+  const compiled = await compileDeliveryGraph(graph);
+  assert(compiled.ok, `expected the gated graph to compile, got ${JSON.stringify(compiled)}`);
+});
+
+test("sequenceIssues: an unknown gate kind → rejected at issues[i].gate.kind", () => {
+  const issues = rejects({ issues: [{ gate: { kind: "no-such-probe", target: "x" }, issue: "acme/repo#1" }] });
+  assert(issues.some((i) => i.path === "issues[0].gate.kind"), `expected issues[0].gate.kind, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: a gate missing its target → rejected at issues[i].gate.target", () => {
+  const issues = rejects({ issues: [{ gate: { kind: "npm" }, issue: "acme/repo#1" }] });
+  assert(issues.some((i) => i.path === "issues[0].gate.target"), `expected issues[0].gate.target, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: a gate with onTimeout:fail → rejected at issues[i].gate.onTimeout", () => {
+  const issues = rejects({ issues: [{ gate: { kind: "npm", target: "pkg@1", onTimeout: "fail" }, issue: "acme/repo#1" }] });
+  assert(issues.some((i) => i.path === "issues[0].gate.onTimeout"), `expected issues[0].gate.onTimeout, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: an object entry missing `issue` → rejected at issues[i].issue", () => {
+  const issues = rejects({ issues: [{ gate: { kind: "npm", target: "pkg@1" } }] });
+  assert(issues.some((i) => i.path === "issues[0].issue"), `expected issues[0].issue, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: a fully-gated max-length sequence behind an epic gate exceeds the node ceiling → rejected", () => {
+  const many = Array.from({ length: MAX_SEQUENCE_ISSUES }, (_, i) => ({
+    gate: { kind: "npm", target: `pkg@${i + 1}` },
+    issue: `acme/repo#${i + 1}`,
+  }));
+  // 64 × 4 nodes + 1 epic gate = 257 > 256.
+  const issues = rejects({ behind: "acme/repo#999", issues: many });
+  assert(issues.some((i) => i.path === "issues" && /too many nodes/.test(i.message)), `expected a node-ceiling rejection, got ${JSON.stringify(issues)}`);
+});