@nanobpm/nano-workforce 0.180.0 → 0.182.0

package/app/sequenceIssues.test.ts

@@ -35,7 +35,9 @@ function handAuthored(behind: string | null, issues: string[]): AnyGraph {
     nodes.push({
       id: `open-${n}`,
       kind: "agent",
-      agent: { jobType: "senior:feature", prompt: `Implement ${issue} and open a PR.` },
+      // #739: the generator stamps each agent cell with the issue's OWN repository, so a multi-repo
+      // sequence provisions each cell's isolation envelope from that issue's repo.
+      agent: { jobType: "senior:feature", prompt: `Implement ${issue} and open a PR.`, repository: issue.split("#")[0] },
       emits: [{ name: "pr", type: "pr" }],
     });
     nodes.push({ id: `land-${n}`, kind: "connector", connector: { target: "converge-merge", payload: { pr: `open-${n}.pr` } } });
@@ -106,6 +108,15 @@ test("sequenceIssues: each issue emits agent(senior:feature,emits pr) → connec
   assert(graph.edges.some((e) => e.from === "open-1.pr" && e.to === "merged-1"));
 });
 
+test("sequenceIssues: each agent cell is stamped with its OWN issue's repository — a cross-repo sequence (#739)", () => {
+  // Two issues in DIFFERENT repos → each `open-*` agent node declares that issue's repository, so the
+  // delivery runner provisions each cell's isolation envelope from its own repo (no uniform run-level
+  // repository, no `repoless`). This is the generator half of #739.
+  const graph = ok({ issues: ["acme/one#1", "beta/two#2"] });
+  assertEquals(graph.nodes.find((n) => n.id === "open-1").agent.repository, "acme/one");
+  assertEquals(graph.nodes.find((n) => n.id === "open-2").agent.repository, "beta/two");
+});
+
 test("sequenceIssues: merge/epic gates carry a realistic poll budget (not the 30-min default trap)", () => {
   const graph = ok({ behind: "acme/repo#9", issues: ["acme/repo#1"] });
   const gate = graph.nodes.find((n) => n.id === "gate-epic");
@@ -184,3 +195,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)}`);
+});

package/app/sequenceIssues.ts

@@ -19,8 +19,9 @@
 // `pr`-typed emits, threaded fact edges, a DAG. It is validated against the S3 vocabulary
 // (`deliveryGraphVocabulary`) so an unknown connector target / probe kind is rejected at the door with
 // `issues[{path,message}]` rather than only surfacing at compile time.
-import type { DeliveryEdge, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
+import type { DeliveryEdge, DeliveryGraph, DeliveryNode, ReadinessProbe } from "../nano-generated/api-io.d.ts";
 import { CONVERGE_MERGE_TARGET } from "./convergeTargets.ts";
+import { GRAPH_MAX_NODES } from "./deliveryGraph.ts";
 import { deliveryGraphVocabulary } from "./deliveryGraphVocabulary.ts";
 import { type ParsedIssue, parseIssue } from "./plan.ts";
 
@@ -31,10 +32,42 @@ export interface SequenceIssueError {
   readonly message: string;
 }
 
-/** The `sequenceIssues` intent body — an optional leading `behind` gate plus the ordered `issues`. */
+/** An interleaved `wait` GATE that must go green before a given issue's agent starts (issue #740).
+ * Reuses the exact probe schema `wait` nodes already accept — the `npm`/`github-check`/`http`/…
+ * vocabulary — so an author can insert e.g. "wait for `@nanobpm/agentic@0.13.0` to publish" between
+ * two sequence steps without falling off the intent onto raw node/edge JSON. */
+export interface SequenceGate {
+  /** The wait-probe kind (must be a known kind in the S3 vocabulary — `npm`, `github-check`, `http`,
+   * `command`, `capability`, `pr`, `epic`). */
+  kind: string;
+  /** The probe target — kind-specific (`pkg@version` for `npm`, `owner/repo@ref` for `github-check`,
+   * a URL for `http`, …). */
+  target: string;
+  /** Optional kind-specific readiness `match` fields (e.g. `{ version }` for `npm`). */
+  match?: Record<string, unknown>;
+  /** Optional poll budget; defaults to the bounded merge-gate budget ({@link MERGE_POLL}) so a gate
+   * never falls into the 30-minute default trap. */
+  poll?: { everyMs?: number; timeoutMs?: number };
+  /** What to do when the gate never goes green within its budget — `escalate` (default) or `continue`.
+   * `fail` is rejected (not yet supported by the compiler/engine). */
+  onTimeout?: "escalate" | "continue";
+  /** Optional env-key name supplying a credential for the probe (`http`/`capability`). */
+  credentialEnv?: string;
+}
+
+/** One `issues[]` entry with an OPTIONAL leading {@link SequenceGate} — the object form. A bare string
+ * entry (no gate) keeps today's behaviour byte-for-byte. */
+export interface SequenceIssueEntry {
+  gate?: SequenceGate;
+  issue: string;
+}
+
+/** The `sequenceIssues` intent body — an optional leading `behind` gate plus the ordered `issues`,
+ * each of which may be a bare `owner/repo#N` string OR a `{ gate?, issue }` object interleaving a
+ * `wait` gate before that issue's agent (issue #740). */
 export interface SequenceIssuesIntent {
   behind?: string;
-  issues: string[];
+  issues: (string | SequenceIssueEntry)[];
 }
 
 /** The result of {@link buildSequenceGraph}: either the constructed graph, or the path-qualified
@@ -63,6 +96,30 @@ export const MAX_SEQUENCE_ISSUES = 64;
  * downstream connector / `wait[pr]` node late-binds its target PR from the fact (§9.4, issue #548). */
 const PR_EMIT = { name: "pr", type: "pr" as const };
 
+/** A validated, ready-to-emit interleaved gate: `poll` and `onTimeout` are resolved to concrete values
+ * (defaults applied) so {@link assembleGraph} can drop it straight into a `wait` node's config. */
+interface BuiltGate {
+  kind: ReadinessProbe["kind"];
+  target: string;
+  match?: Record<string, unknown>;
+  poll: { everyMs?: number; timeoutMs?: number };
+  onTimeout: "escalate" | "continue";
+  credentialEnv?: string;
+}
+
+/** A parsed `issues[]` entry: the parsed issue (carrying its `owner/repo#N` target, used to stamp the
+ * generated agent node's own `repository` — issue #739) plus its optional interleaved gate (#740). */
+interface ParsedEntry {
+  issue: ParsedIssue;
+  gate: BuiltGate | null;
+}
+
+/** Narrow a validated string to the closed `ReadinessProbe["kind"]` union — backed by the runtime
+ * vocabulary set so the type guard and the door validation share one source of truth. */
+function isProbeKind(kind: string, probeKinds: Set<string>): kind is ReadinessProbe["kind"] {
+  return probeKinds.has(kind);
+}
+
 /** Parse a ref into an issue target ONLY if its number is a positive, safe integer. `parseIssue`'s
  * `\d+` accepts `#0` and precision-overflowing numbers (e.g. `#99999999999999999999`, which coerces
  * past `Number.MAX_SAFE_INTEGER`), but such a target can never resolve to a real issue/PR — staging a
@@ -74,12 +131,111 @@ function parseIssueRef(ref: unknown): ParsedIssue | null {
   return Number.isSafeInteger(parsed.number) && parsed.number >= 1 ? parsed : null;
 }
 
+/** Validate one interleaved `gate` spec against the probe vocabulary, applying defaults. Returns the
+ * built gate or path-qualified `issues[{path,message}]` rejections (keyed under `path`, e.g.
+ * `issues[1].gate.kind`). Reuses the same probe schema `wait` nodes accept: `{ kind, target, match?,
+ * poll?, onTimeout?, credentialEnv? }`. */
+function parseGate(raw: unknown, path: string, probeKinds: Set<string>): { gate?: BuiltGate; errors: SequenceIssueError[] } {
+  const errors: SequenceIssueError[] = [];
+  if (!isRecord(raw)) {
+    return { errors: [{ path, message: "`gate` must be an object carrying a `wait` probe (`{ kind, target, … }`)." }] };
+  }
+
+  // Trim before validating AND before persisting: harmless 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 (`pkg@1.0.0 ` → a gate that never goes
+  // green). The persisted value is always the trimmed one.
+  let validKind: ReadinessProbe["kind"] | null = null;
+  const kind = raw.kind;
+  if (typeof kind !== "string" || kind.trim() === "") {
+    errors.push({ path: `${path}.kind`, message: "`gate.kind` is required and must be a non-empty wait-probe kind." });
+  } else {
+    const trimmedKind = kind.trim();
+    if (!isProbeKind(trimmedKind, probeKinds)) {
+      errors.push({ path: `${path}.kind`, message: `wait-probe kind \`${trimmedKind}\` is not in the delivery-graph vocabulary.` });
+    } else {
+      validKind = trimmedKind;
+    }
+  }
+
+  let validTarget: string | null = null;
+  const target = raw.target;
+  if (typeof target !== "string" || target.trim() === "") {
+    errors.push({ path: `${path}.target`, message: "`gate.target` is required and must be a non-empty string." });
+  } else {
+    validTarget = target.trim();
+  }
+
+  let match: Record<string, unknown> | undefined;
+  if (raw.match !== undefined) {
+    if (!isRecord(raw.match)) {
+      errors.push({ path: `${path}.match`, message: "`gate.match`, when present, must be an object of readiness fields." });
+    } else {
+      match = raw.match;
+    }
+  }
+
+  const poll: { everyMs?: number; timeoutMs?: number } = { ...MERGE_POLL };
+  if (raw.poll !== undefined) {
+    if (!isRecord(raw.poll)) {
+      errors.push({ path: `${path}.poll`, message: "`gate.poll`, when present, must be `{ everyMs?, timeoutMs? }`." });
+    } else {
+      for (const key of ["everyMs", "timeoutMs"] as const) {
+        const v = raw.poll[key];
+        if (v === undefined) continue;
+        if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 1) {
+          errors.push({ path: `${path}.poll.${key}`, message: `\`gate.poll.${key}\`, when present, must be a positive integer (milliseconds).` });
+        } else {
+          poll[key] = v;
+        }
+      }
+    }
+  }
+
+  let onTimeout: "escalate" | "continue" = "escalate";
+  if (raw.onTimeout !== undefined) {
+    if (raw.onTimeout !== "escalate" && raw.onTimeout !== "continue") {
+      errors.push({
+        path: `${path}.onTimeout`,
+        message: "`gate.onTimeout` must be `escalate` (default) or `continue` — `fail` is not supported on a `wait` node.",
+      });
+    } else {
+      onTimeout = raw.onTimeout;
+    }
+  }
+
+  let credentialEnv: string | undefined;
+  if (raw.credentialEnv !== undefined) {
+    if (typeof raw.credentialEnv !== "string" || raw.credentialEnv.trim() === "") {
+      errors.push({ path: `${path}.credentialEnv`, message: "`gate.credentialEnv`, when present, must be a non-empty env-key name." });
+    } else {
+      credentialEnv = raw.credentialEnv;
+    }
+  }
+
+  if (errors.length > 0 || validKind === null || validTarget === null) return { errors };
+  return {
+    gate: {
+      kind: validKind,
+      target: validTarget,
+      ...(match ? { match } : {}),
+      poll,
+      onTimeout,
+      ...(credentialEnv ? { credentialEnv } : {}),
+    },
+    errors: [],
+  };
+}
+
 /**
  * Build the canonical delivery graph for a `sequenceIssues` intent, or return path-qualified
  * `issues[{path,message}]` rejections for invalid input. Validates:
  *   - `issues` is a non-empty array within {@link MAX_SEQUENCE_ISSUES};
- *   - every `issues[i]` and the optional `behind` parse as an `owner/repo#N` reference;
- *   - the connector target and wait-probe kinds it emits are known to the S3 vocabulary (drift guard).
+ *   - every `issues[i]` (a bare ref, or a `{ gate?, issue }` object) and the optional `behind` parse
+ *     as an `owner/repo#N` reference;
+ *   - each interleaved `gate` names a wait-probe kind known to the S3 vocabulary (issue #740);
+ *   - the connector target and wait-probe kinds it emits are known to the S3 vocabulary (drift guard);
+ *   - the generated graph stays within the compiler's node ceiling.
  * Pure — no I/O. The constructed graph passes `validateDeliveryGraph` by construction.
  */
 export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
@@ -89,8 +245,12 @@ export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
   const rawIssues = body.issues;
   const rawBehind = body.behind;
 
-  // ── `issues`: a non-empty, bounded array of parseable refs ───────────────────────────────────
-  const parsedIssues: string[] = [];
+  // The vocabulary is needed up front to validate interleaved gate `kind`s as each entry is parsed.
+  const vocab = deliveryGraphVocabulary();
+  const probeKinds = new Set(vocab.waitProbeKinds.map((p) => p.kind));
+
+  // ── `issues`: a non-empty, bounded array of parseable refs, each optionally carrying a gate ────
+  const parsedEntries: ParsedEntry[] = [];
   if (!Array.isArray(rawIssues)) {
     issues.push({ path: "issues", message: "`issues` must be a non-empty array of `owner/repo#N` issue references." });
   } else if (rawIssues.length === 0) {
@@ -101,16 +261,26 @@ export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
       message: `\`issues\` has too many entries (${rawIssues.length}) — the limit is ${MAX_SEQUENCE_ISSUES}.`,
     });
   } else {
-    rawIssues.forEach((ref, i) => {
-      const parsed = parseIssueRef(ref);
+    rawIssues.forEach((entry, i) => {
+      // A bare string entry is a gate-less issue (today's behaviour, byte-for-byte). An object entry
+      // carries a required `issue` ref plus an OPTIONAL leading `gate` (issue #740).
+      const rawRef = isRecord(entry) ? entry.issue : entry;
+      const parsed = parseIssueRef(rawRef);
       if (!parsed) {
+        const shown = isRecord(entry) ? String(rawRef) : String(entry);
         issues.push({
-          path: `issues[${i}]`,
-          message: `\`${String(ref)}\` is not a valid \`owner/repo#N\` issue reference.`,
+          path: isRecord(entry) ? `issues[${i}].issue` : `issues[${i}]`,
+          message: `\`${shown}\` is not a valid \`owner/repo#N\` issue reference.`,
         });
         return;
       }
-      parsedIssues.push(parsed.planKey);
+      let gate: BuiltGate | null = null;
+      if (isRecord(entry) && entry.gate !== undefined && entry.gate !== null) {
+        const parsedGate = parseGate(entry.gate, `issues[${i}].gate`, probeKinds);
+        issues.push(...parsedGate.errors);
+        gate = parsedGate.gate ?? null;
+      }
+      parsedEntries.push({ issue: parsed, gate });
     });
   }
 
@@ -135,7 +305,6 @@ export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
   // ── Vocabulary drift guard (S3): the target/probe kinds this generator emits MUST be known to the
   // structured vocabulary. This can only trip if the closed vocabulary changes underneath us — it is
   // surfaced as a door `issue` (not a throw) so the failure mode is a clean rejection, not a 500. ──
-  const vocab = deliveryGraphVocabulary();
   const realTargets = new Set(vocab.connectorTargets.filter((t) => t.status === "real").map((t) => t.target));
   if (!realTargets.has(CONVERGE_MERGE_TARGET)) {
     issues.push({
@@ -143,28 +312,44 @@ export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
       message: `connector target \`${CONVERGE_MERGE_TARGET}\` is not a real target in the delivery-graph vocabulary.`,
     });
   }
-  const probeKinds = new Set(vocab.waitProbeKinds.map((p) => p.kind));
   for (const kind of behindKey ? [PR_PROBE_KIND, EPIC_PROBE_KIND] : [PR_PROBE_KIND]) {
     if (!probeKinds.has(kind)) {
       issues.push({ path: "issues", message: `wait-probe kind \`${kind}\` is not in the delivery-graph vocabulary.` });
     }
   }
 
+  // ── Node-budget guard: interleaved gates add a node per gated issue, so a fully-gated max-length
+  // sequence (plus the optional `behind` gate) can push past the compiler's node ceiling. Reject it
+  // at the door so a SUCCESSFULLY generated graph always validates `by construction`. ──
+  if (issues.length === 0) {
+    const projectedNodes = (behindKey ? 1 : 0) + parsedEntries.reduce((n, e) => n + 3 + (e.gate ? 1 : 0), 0);
+    if (projectedNodes > GRAPH_MAX_NODES) {
+      issues.push({
+        path: "issues",
+        message: `the generated graph would have too many nodes (${projectedNodes}) — the limit is ${GRAPH_MAX_NODES}; use fewer issues or interleaved gates.`,
+      });
+    }
+  }
+
   if (issues.length > 0) return { ok: false, issues };
 
-  return { ok: true, graph: assembleGraph(parsedIssues, behindKey) };
+  return { ok: true, graph: assembleGraph(parsedEntries, behindKey) };
 }
 
-/** Assemble the canonical node/edge chain for the (already-validated) issue keys + optional gate. */
-function assembleGraph(issueKeys: string[], behindKey: string | null): DeliveryGraph {
+/** Assemble the canonical node/edge chain for the (already-validated) parsed entries + optional gate.
+ * Each entry emits `agent → connector[converge-merge] → wait[pr, merged]`; an entry with an
+ * interleaved `gate` gets a leading `wait[<gate.kind>]` node spliced between the prior sequence step
+ * and its agent, so the agent starts only once the prior issue merged AND the gate went green. Each
+ * agent node is stamped with its own `repository` (issue #739) from the issue it implements. */
+function assembleGraph(entries: ParsedEntry[], behindKey: string | null): DeliveryGraph {
   const nodes: DeliveryNode[] = [];
   const edges: DeliveryEdge[] = [];
 
   // Optional leading `wait[epic]` gate — the whole sequence waits for `behind` to be fully merged.
-  const GATE_ID = "gate-epic";
+  const EPIC_GATE_ID = "gate-epic";
   if (behindKey) {
     nodes.push({
-      id: GATE_ID,
+      id: EPIC_GATE_ID,
       kind: "wait",
       wait: {
         kind: EPIC_PROBE_KIND,
@@ -177,18 +362,50 @@ function assembleGraph(issueKeys: string[], behindKey: string | null): DeliveryG
     });
   }
 
-  issueKeys.forEach((issueKey, i) => {
+  entries.forEach((entry, i) => {
+    const issue = entry.issue;
     const n = i + 1;
     const openId = `open-${n}`;
     const landId = `land-${n}`;
     const mergedId = `merged-${n}`;
     const prRef = `${openId}.pr`;
+    const issueKey = issue.planKey;
+
+    // The sequence predecessor whose completion releases THIS issue: the prior issue's merge, else the
+    // leading epic gate for the first issue (null when the first issue is ungated by `behind`).
+    const predecessor = i === 0 ? (behindKey ? EPIC_GATE_ID : null) : `merged-${i}`;
 
-    // agent → opens the PR, emits it as a typed `pr` fact the downstream nodes late-bind.
+    // Interleaved gate (issue #740): a `wait[<kind>]` node the issue's agent waits on. It inherits the
+    // sequence predecessor's edge (so it only starts probing once the prior issue merged) and the
+    // agent then waits on the gate — gating the agent on the prior merge AND the gate condition.
+    let agentPredecessor = predecessor;
+    if (entry.gate) {
+      const gateId = `gate-${n}`;
+      const g = entry.gate;
+      nodes.push({
+        id: gateId,
+        kind: "wait",
+        wait: {
+          kind: g.kind,
+          target: g.target,
+          ...(g.match ? { match: g.match } : {}),
+          poll: { ...g.poll },
+          onTimeout: g.onTimeout,
+          ...(g.credentialEnv ? { credentialEnv: g.credentialEnv } : {}),
+        },
+      });
+      if (predecessor) edges.push({ from: predecessor, to: gateId });
+      agentPredecessor = gateId;
+    }
+
+    // agent → opens the PR, emits it as a typed `pr` fact the downstream nodes late-bind. Stamp the
+    // node's OWN `repository` (#739) from the `owner/repo#N` it implements, so a cross-repo sequence
+    // provisions each cell's isolation envelope node-locally — no uniform run-level repo, no `repoless`.
+    // The base branch is left to the run-level fallback (an issue ref names no branch — issue #739 Notes).
     nodes.push({
       id: openId,
       kind: "agent",
-      agent: { jobType: AGENT_JOB_TYPE, prompt: `Implement ${issueKey} and open a PR.` },
+      agent: { jobType: AGENT_JOB_TYPE, prompt: `Implement ${issueKey} and open a PR.`, repository: issue.repo },
       emits: [{ ...PR_EMIT }],
     });
     // connector[converge-merge] → drive the opened PR through review convergence + the merge loop.
@@ -214,18 +431,16 @@ function assembleGraph(issueKeys: string[], behindKey: string | null): DeliveryG
     edges.push({ from: prRef, to: landId });
     edges.push({ from: prRef, to: mergedId });
 
-    // Sequence: this issue's agent starts once the PRIOR issue merged; the first waits on the gate.
-    if (i === 0) {
-      if (behindKey) edges.push({ from: GATE_ID, to: openId });
-    } else {
-      edges.push({ from: `merged-${i}`, to: openId });
-    }
+    // Sequence: this issue's agent starts once its predecessor (prior merge / epic gate / interleaved
+    // gate) released. A first ungated issue has no predecessor edge (it starts immediately).
+    if (agentPredecessor) edges.push({ from: agentPredecessor, to: openId });
   });
 
+  const gateCount = entries.filter((e) => e.gate).length;
   const name =
-    issueKeys.length === 1
-      ? `sequence ${issueKeys[0]}`
-      : `sequence ${issueKeys.length} issues${behindKey ? ` behind ${behindKey}` : ""}`;
+    entries.length === 1
+      ? `sequence ${entries[0].issue.planKey}`
+      : `sequence ${entries.length} issues${gateCount > 0 ? ` with ${gateCount} gate${gateCount === 1 ? "" : "s"}` : ""}${behindKey ? ` behind ${behindKey}` : ""}`;
 
   return { name, nodes, edges };
 }

package/e2e/addressable-guide.e2e.ts

@@ -69,6 +69,49 @@ describe("S5 — the addressable operator guide over MCP (#611)", () => {
     assert(res.text.length < 30000, "one section must fit a typical tool-result budget in a single call");
   });
 
+  test("section pagination: start/length pages a section and nextStart walks it to completion (#740)", async () => {
+    const whole = await h.callTool("getAgentGuide", { section: "delivery-graphs" });
+    const wholeSection = (whole.json as { section?: { instructions: string } }).section!;
+    const wholeChars = Array.from(wholeSection.instructions);
+
+    const PAGE = 4000;
+    let start = 0;
+    let assembled = "";
+    let pages = 0;
+    let total = -1;
+    for (;;) {
+      const res = await h.callTool("getAgentGuide", { section: "delivery-graphs", start, length: PAGE });
+      assert(!res.isError, `a paged fetch must not error: ${res.text}`);
+      const body = res.json as {
+        kind?: string;
+        section?: { id: string; instructions: string; start: number; length: number; totalLength: number; nextStart: number | null };
+      };
+      assert.equal(body.kind, "section");
+      const s = body.section!;
+      assert.equal(s.id, "delivery-graphs");
+      assert(Array.from(s.instructions).length <= PAGE, "a page must be bounded by `length`");
+      assert.equal(s.start, start);
+      if (total !== -1) assert.equal(s.totalLength, total, "totalLength is stable across pages");
+      total = s.totalLength;
+      assembled += s.instructions;
+      pages++;
+      if (s.nextStart === null) break;
+      start = s.nextStart;
+      assert(pages < 100, "pagination must terminate");
+    }
+    assert(pages > 1, "a large section must span multiple pages at this window");
+    assert.equal(total, wholeChars.length, "totalLength equals the full section length");
+    assert.equal(assembled, wholeSection.instructions, "the reassembled pages equal the whole section");
+  });
+
+  test("section pagination: a non-integer/negative start is a uniform issues[{path,message}] 400 (#740)", async () => {
+    const res = await h.callTool("getAgentGuide", { section: "delivery-graphs", start: -5 });
+    assert(res.isError, "an invalid pagination arg must surface as a tool-level error");
+    const body = res.json as { issues?: { path: string; message: string }[] };
+    assert(Array.isArray(body.issues) && body.issues.length >= 1, "must answer with issues[]");
+    assert(body.issues!.some((i) => i.path.includes("start")), "the issue must name the `start` argument");
+  });
+
   test("an unknown section id is rejected with issues[{path,message}]", async () => {
     const res = await h.callTool("getAgentGuide", { section: "no-such-section" });
     assert(res.isError, "an unknown section id must surface as a tool-level error");