@nanobpm/nano-workforce 0.180.0 → 0.182.0

package/app/deliveryRunner.test.ts

@@ -31,7 +31,11 @@ const GRAPH: DeliveryGraph = {
 };
 
 async function prepareOk(graph: DeliveryGraph, options = {}) {
-  const r = await prepareDeliveryGraph(graph, options);
+  // Default to a resolvable run-level repository/baseBranch fallback (#739) so the many timeout/id/DI
+  // tests below — which don't care about repo provisioning — need not restate it; the per-node
+  // repository tests pass their own `options` (declared node repos, `repoless`, unresolved, …).
+  const opts = "repoless" in options || "repository" in options ? options : { repository: "owner/repo", baseBranch: "main", ...options };
+  const r = await prepareDeliveryGraph(graph, opts);
   assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
   return r.prepared;
 }
@@ -364,90 +368,148 @@ test("runDeliveryGraph coerces a numeric engine processInstanceKey to a string h
   assertEquals(typeof r.handle.processInstanceKey, "string");
 });
 
-// Host-git provisioning (issue #684/#686): the delivery-graph runner must seed the canonical
-// `io.nanobpm.agentTask.repository` isolation envelope (`repoEnvelopeVars`) as a run-root process
-// variable so every agent cell's servicing `senior:*` job provisions an ISOLATED throwaway clone
-// instead of mutating the worker's launch dir — the delivery-graph analog of the plan.ts epic seed.
-// These pin the createInstance variables the harness (headers ∪ variables) reads.
-function captureCreateInstanceVars(): { engine: Parameters<typeof runDeliveryGraph>[0]; seen: () => Record<string, unknown> } {
-  let captured: Record<string, unknown> = {};
-  const engine = {
-    deployResources: async () => [],
-    createInstance: async (req: { variables?: Record<string, unknown> }) => {
-      captured = req.variables ?? {};
-      return { processInstanceKey: "1" };
-    },
-  };
-  return { engine, seen: () => captured };
+// Per-node repository isolation (issue #739): the delivery-graph runner seeds the canonical
+// `io.nanobpm.agentTask.repository` isolation envelope PER agent cell as flattened `<zeebe:taskHeaders>`
+// (`io.nanobpm.agentTask.repository.url`, …) injected into the deployable BPMN — NOT as a single
+// run-root process variable. Each agent node's effective repository is its own declared `agent.repository`
+// (`agent.baseBranch`), else the run-level `repository`/`baseBranch` fallback. This lets one graph fan out
+// across DIFFERENT repos (each cell its own isolated clone) without forcing `repoless`. These pin the
+// per-node headers the harness reads and the loud-failure invariants (#729 preserved/strengthened).
+function agentHeaders(bpmn: string): string[] {
+  return (bpmn.match(/io\.nanobpm\.agentTask\.[^\n]*/g) ?? []).map((s) => s.trim());
 }
 
-test("runDeliveryGraph seeds the repository isolation envelope when repository + baseBranch are supplied (#684/#686)", async () => {
-  const { engine, seen } = captureCreateInstanceVars();
-  const r = await runDeliveryGraph(engine, GRAPH, { repository: "owner/repo", baseBranch: "main" });
+test("prepareDeliveryGraph injects the repository envelope PER agent cell from the run-level fallback (#684/#686/#739)", async () => {
+  const p = await prepareOk(GRAPH, { repository: "owner/repo", baseBranch: "main" });
+  const headers = agentHeaders(p.bpmn);
+  // The run's single agent cell (`open-b`) carries the flattened envelope headers.
+  assert(headers.some((h) => h.includes('repository.url" value="https://github.com/owner/repo.git"')), `expected a repository.url header, got ${JSON.stringify(headers)}`);
+  assert(headers.some((h) => h.includes('repository.ref" value="main"')), "ref = base branch");
+  assert(headers.some((h) => h.includes('repository.baseRef" value="main"')), "baseRef = base branch");
+  assert(headers.some((h) => h.includes('repository.provider" value="github"')), "provider header");
+  assert(headers.some((h) => h.includes('repository.singleBranch" value="true"')), "branch-scoped blobless clone (#287)");
+  assert(headers.some((h) => h.includes('repository.filter" value="blob:none"')), "blobless filter");
+  // No `__repoSpec` marker survives injection — it is the compiler's digest-stable anchor only.
+  assert(!p.bpmn.includes("__repoSpec"), "the __repoSpec marker is fully replaced");
+  // No run-root `io.nanobpm.agentTask` variable — the envelope rides headers now, not a run variable.
+});
+
+test("a node's DECLARED repository/baseBranch WINS over the run-level fallback; a bare node falls back (#739)", async () => {
+  const graph: DeliveryGraph = {
+    name: "cross-repo fan-out",
+    nodes: [
+      { id: "own", kind: "agent", agent: { jobType: "senior:feature", prompt: "own repo", repository: "acme/widget", baseBranch: "develop" } },
+      { id: "fallback", kind: "agent", agent: { jobType: "senior:feature", prompt: "run repo" } },
+    ],
+    edges: [{ from: "own", to: "fallback" }],
+  };
+  const p = await prepareOk(graph, { repository: "owner/repo", baseBranch: "main" });
+  const headers = agentHeaders(p.bpmn);
+  // The declared node points at its OWN repo + base…
+  assert(headers.some((h) => h.includes('repository.url" value="https://github.com/acme/widget.git"')), "declared repo wins");
+  assert(headers.some((h) => h.includes('repository.ref" value="develop"')), "declared base wins");
+  // …while the bare node inherits the run-level fallback.
+  assert(headers.some((h) => h.includes('repository.url" value="https://github.com/owner/repo.git"')), "bare node falls back to run repo");
+  assert(headers.some((h) => h.includes('repository.ref" value="main"')), "bare node falls back to run base");
+});
+
+test("a fully NODE-PROVISIONED cross-repo graph dispatches with NO run-level repository and NO repoless (#739)", async () => {
+  const graph: DeliveryGraph = {
+    name: "self-provisioned",
+    nodes: [
+      { id: "a", kind: "agent", agent: { jobType: "senior:feature", prompt: "a", repository: "acme/one" } },
+      { id: "b", kind: "agent", agent: { jobType: "senior:feature", prompt: "b", repository: "acme/two" } },
+    ],
+    edges: [{ from: "a", to: "b" }],
+  };
+  // Neither a run-level repository/baseBranch NOR repoless — every node self-provisions.
+  const p = await prepareOk(graph, {});
+  const headers = agentHeaders(p.bpmn);
+  assert(headers.some((h) => h.includes("acme/one.git")), "node a → acme/one");
+  assert(headers.some((h) => h.includes("acme/two.git")), "node b → acme/two");
+});
+
+test("a declared repository WITHOUT a base branch omits ref/baseRef — the harness clones the default branch (#739)", async () => {
+  const graph: DeliveryGraph = {
+    name: "no base",
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature", prompt: "a", repository: "acme/one" } }],
+    edges: [],
+  };
+  // Call the runner DIRECTLY with no run-level fallback (the shared `prepareOk` helper would inject one),
+  // so the node's declared repo is the sole source and its base is genuinely unknown.
+  const r = await prepareDeliveryGraph(graph, {});
   assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
-  const env = (seen() as Record<string, { repository?: Record<string, unknown> }>)["io.nanobpm.agentTask"];
-  assert(env?.repository, `expected the run-root vars to carry io.nanobpm.agentTask.repository, got ${JSON.stringify(seen())}`);
-  const repo = env.repository as Record<string, unknown>;
-  // PRE-PR shape: `ref = base` (the harness checks out the base; each agent cuts its own feat/<node.id>).
-  assertEquals(repo.ref, "main");
-  assertEquals(repo.url, "https://github.com/owner/repo.git");
-  assertEquals(repo.provider, "github");
-  // Branch-scoped blobless clone (#287) so large monorepos provision within the clone timeout.
-  assertEquals(repo.singleBranch, true);
-  assertEquals(repo.filter, "blob:none");
-  // baseRef = base too, so `origin/<base>` stays reachable for the review 3-dot diff.
-  assertEquals(repo.baseRef, "main");
-  // NO branch.create at the run root — a run fans out to many agent nodes, each needing its own
-  // feat/<node.id>, so a single run-level envelope names none (mirrors the plan.ts epic seed).
-  assertEquals("branch" in repo, false);
+  const headers = agentHeaders(r.prepared.bpmn);
+  assert(headers.some((h) => h.includes('repository.url" value="https://github.com/acme/one.git"')), "url present");
+  assert(!headers.some((h) => h.includes("repository.ref")), "no ref → clone the repo default branch");
+  assert(!headers.some((h) => h.includes("repository.baseRef")), "no baseRef either");
 });
 
-test("runDeliveryGraph seeds NO envelope ONLY on an EXPLICIT repoless run — the conscious opt-out (#729)", async () => {
-  const { engine, seen } = captureCreateInstanceVars();
-  const r = await runDeliveryGraph(engine, GRAPH, { repoless: true });
-  assert(r.ok, `expected ok:true for an explicit repoless run, got ${JSON.stringify(r)}`);
-  assertEquals("io.nanobpm.agentTask" in seen(), false, "an explicit repoless run must emit no envelope");
+test("prepareDeliveryGraph seeds NO envelope ONLY on an EXPLICIT repoless run — the conscious opt-out (#729)", async () => {
+  const p = await prepareOk(GRAPH, { repoless: true });
+  assert(!p.bpmn.includes("io.nanobpm.agentTask.repository"), "an explicit repoless run must emit no repository envelope");
+  assert(!p.bpmn.includes("__repoSpec"), "the marker is stripped on a repoless run too");
 });
 
-test("runDeliveryGraph THROWS on an unresolved repo/base when NOT repoless — never a silent shared launch dir (#729)", async () => {
-  // Issue #729: the fan-out seed is REQUIRED. Dispatching without a resolvable repository + base branch
-  // (and without the explicit `repoless` opt-out) must fail LOUDLY at seed time rather than silently
-  // emit `{}` and degrade every agent job to the worker's shared launch dir (issue #684's field failure
-  // re-opened as a silent fallback). Missing both, or only one of the pair, is unresolved.
-  for (const options of [{}, { repository: "owner/repo" }, { baseBranch: "main" }, { repository: "  ", baseBranch: "main" }]) {
-    const { engine } = captureCreateInstanceVars();
+test("prepareDeliveryGraph THROWS on an unresolved repo/base when NOT repoless — never a silent shared launch dir (#729/#739)", async () => {
+  // Issue #729: the fan-out seed is REQUIRED. An agent cell that declares no repository AND has no
+  // run-level repository fallback (and no explicit `repoless` opt-out) must fail LOUDLY at prepare time
+  // rather than silently degrade to the worker's shared launch dir (issue #684's field failure). GRAPH's
+  // `open-b` node declares no repository. A run-level repository WITHOUT a base is NOT unresolved (#739:
+  // the cell clones the repo's default branch) — only a missing/blank repository is unresolved.
+  for (const options of [{}, { baseBranch: "main" }, { repository: "  ", baseBranch: "main" }]) {
     await assertRejects(
-      () => runDeliveryGraph(engine, GRAPH, options),
+      () => prepareDeliveryGraph(GRAPH, options),
       RepoEnvelopeUnresolvedError,
     );
   }
 });
 
-test("runDeliveryGraph THROWS on a malformed repository rather than emitting a bogus clone URL (#729)", async () => {
-  const { engine } = captureCreateInstanceVars();
-  // A value that is not exactly `owner/repo` (a trailing `.git`) is an UNRESOLVED input on the required
-  // path — it must throw, never degrade to a double-suffixed `…/owner/repo.git.git` clone URL nor to a
-  // silent no-envelope launch-dir fallback.
+test("a run-level repository WITHOUT a base branch RESOLVES every bare cell — the default-branch clone (#739)", async () => {
+  // The #739 relaxation: an issue ref carries only `owner/repo`, no branch. A run-level repository with
+  // no base is a legitimate fallback — each bare cell clones that repo's DEFAULT branch, no ref header.
+  const r = await prepareDeliveryGraph(GRAPH, { repository: "owner/repo" });
+  assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
+  const headers = agentHeaders(r.prepared.bpmn);
+  assert(headers.some((h) => h.includes('repository.url" value="https://github.com/owner/repo.git"')), "bare cell inherits run repo");
+  assert(!headers.some((h) => h.includes("repository.ref")), "no run base → clone the default branch");
+});
+
+test("prepareDeliveryGraph THROWS on a malformed run-level repository rather than emitting a bogus clone URL (#729)", async () => {
+  // A value that is not exactly `owner/repo` (a trailing `.git`) is an UNRESOLVED fallback — it must
+  // throw, never degrade to a double-suffixed `…/owner/repo.git.git` clone URL.
   await assertRejects(
-    () => runDeliveryGraph(engine, GRAPH, { repository: "owner/repo.git", baseBranch: "main" }),
+    () => prepareDeliveryGraph(GRAPH, { repository: "owner/repo.git", baseBranch: "main" }),
     RepoEnvelopeUnresolvedError,
   );
 });
 
-test("runDeliveryGraph THROWS when repoless is combined with repository/baseBranch — never silently disables isolation (#729)", async () => {
+test("a malformed NODE-declared repository is REJECTED at validation (#739)", async () => {
+  const graph: DeliveryGraph = {
+    name: "bad node repo",
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature", prompt: "a", repository: "acme/one.git" } }],
+    edges: [],
+  };
+  // A node whose declared repository is malformed (a trailing `.git`) is caught by the semantic validator
+  // as `invalid-node-repository` — the graph never compiles, so it can never inject a bogus clone URL
+  // nor silently fall back to the run level (which would mask the operator's typo).
+  const r = await prepareDeliveryGraph(graph, { repository: "owner/repo", baseBranch: "main" });
+  assert(!r.ok, "a malformed node repository fails to prepare");
+  assert(r.errors.some((e) => e.path === "nodes[0].agent.repository"), `expected an invalid-node-repository error, got ${JSON.stringify(r.errors)}`);
+});
+
+test("prepareDeliveryGraph THROWS when repoless is combined with repository/baseBranch — never silently disables isolation (#729)", async () => {
   // `repoless: true` is mutually exclusive with `repository`/`baseBranch`. The dispatch door rejects the
   // conflicting shape with a 400, but a PROGRAMMATIC caller that bypasses the door could pass both — and
   // the runner would silently drop the repo/base and emit no envelope, re-disabling the exact isolation
-  // the repo/base named. The runner must fail LOUDLY too (defense-in-depth), so isolation can never be
-  // silently disabled by a conflicting call. Either half of the pair alongside `repoless` is a conflict.
+  // the repo/base named. The runner must fail LOUDLY too (defense-in-depth).
   for (const options of [
     { repoless: true, repository: "owner/repo", baseBranch: "main" },
     { repoless: true, repository: "owner/repo" },
     { repoless: true, baseBranch: "main" },
   ]) {
-    const { engine } = captureCreateInstanceVars();
     await assertRejects(
-      () => runDeliveryGraph(engine, GRAPH, options),
+      () => prepareDeliveryGraph(GRAPH, options),
       RepoEnvelopeConflictError,
     );
   }

package/app/deliveryRunner.ts

@@ -18,9 +18,9 @@ import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
-import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
+import { AGENT_REPO_SPEC_HEADER, assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
-import { RepoEnvelopeConflictError, requireRepoEnvelopeVars } from "./repoEnvelope.ts";
+import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, isResolvableRepo, RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError } from "./repoEnvelope.ts";
 import { isoDuration } from "./reviewWait.ts";
 
 /** The content digest of a compiled graph — `sha256(semanticBpmn)[:12]` — the single source of truth
@@ -62,26 +62,34 @@ export interface DeliveryRunOptions extends DeliveryRunTimeouts {
    * cross-correlate. Pass an explicit `runKey` only when you need a reproducible/externally-owned gate
    * scope. */
   runKey?: string;
-  /** OPTIONAL `owner/repo` the run's `agent` nodes implement against. Together with `baseBranch` the
-   * runner seeds the canonical repository-provisioning envelope (`io.nanobpm.agentTask.repository`, via
-   * `requireRepoEnvelopeVars`) as a run-root `createInstance` process variable so each `agent` cell's
-   * servicing `senior:*` job provisions an ISOLATED throwaway clone instead of inheriting the worker's
-   * launch dir (issue #684/#686 — the same isolation the legacy feature/plan paths got in #685).
+  /** OPTIONAL run-level `owner/repo` DEFAULT for `agent` nodes that do not declare their own
+   * `repository`. Per issue #739 the repository-provisioning envelope
+   * (`io.nanobpm.agentTask.repository`) is seeded PER agent cell from that node's own declared
+   * `repository`/`baseBranch` (`injectAgentRepoEnvelopes`, POST-digest, onto each service task's
+   * `<zeebe:taskHeaders>`), with this run-level value as the FALLBACK when a node omits it — so a
+   * heterogeneous cross-repo graph (each node a different repo) needs no run-level repo at all. Each
+   * cell's servicing `senior:*` job provisions an ISOLATED throwaway clone instead of inheriting the
+   * worker's launch dir (issue #684/#686 — the same isolation the legacy feature/plan paths got in
+   * #685).
    *
-   * Issue #729: the envelope is now REQUIRED unless the run is EXPLICITLY `repoless`. A run that is not
-   * `repoless` but supplies an unresolved/missing `repository`/`baseBranch` throws
-   * `RepoEnvelopeUnresolvedError` at seed time (a loud launch failure) rather than silently degrading to
-   * the shared launch-dir behaviour that let concurrent fan-out workers clobber one checkout. */
+   * Issue #729/#739: the envelope is REQUIRED (per node) unless the run is EXPLICITLY `repoless`. A run
+   * that is not `repoless` but has an `agent` node whose repository resolves to neither a declared value
+   * nor this run-level fallback throws `RepoEnvelopeUnresolvedError` at seed time (a loud launch failure)
+   * rather than silently degrading to the shared launch-dir behaviour that let concurrent fan-out
+   * workers clobber one checkout. */
   repository?: string | null;
-  /** OPTIONAL base branch the run's `agent` nodes branch off — the `ref` the harness checks out in the
-   * isolated clone (the PRE-PR shape: no PR head exists yet, so the agent cuts its own `feat/<node.id>`
-   * branch off this base inside the clone). Required (with `repository`) unless the run is `repoless`. */
+  /** OPTIONAL run-level base-branch DEFAULT for `agent` nodes that declare a `repository` but no
+   * `baseBranch` — the `ref` the harness checks out in the isolated clone (the PRE-PR shape: no PR head
+   * exists yet, so the agent cuts its own `feat/<node.id>` branch off this base inside the clone). A
+   * node with a resolvable repository but no base clones the repo's default branch, so this is a
+   * convenience default, not a hard requirement. */
   baseBranch?: string | null;
   /** EXPLICIT opt-out of repository provisioning (issue #729). `true` → the run is dispatched with NO
-   * isolation envelope (the legacy launch-dir behaviour), for a genuinely repo-less graph (e.g. one with
-   * no `agent` nodes that touch a checkout). This must be a CONSCIOUS choice at the dispatch door so the
-   * default can never silently share a checkout: when it is not set, `repository` + `baseBranch` are
-   * mandatory and an unresolved pair is a hard launch failure, not a silent no-envelope fallback. */
+   * isolation envelope on ANY node (the per-node headers are stripped, the legacy launch-dir behaviour),
+   * for a genuinely repo-less graph (e.g. one with no `agent` nodes that touch a checkout). This must be
+   * a CONSCIOUS choice at the dispatch door so the default can never silently share a checkout: when it
+   * is not set, every `agent` node must resolve a repository (its own or the run-level fallback) and an
+   * unresolved node is a hard launch failure, not a silent no-envelope fallback. */
   repoless?: boolean;
 }
 
@@ -140,7 +148,15 @@ export async function prepareDeliveryGraph(
 
   const digest = deliveryGraphDigest(compiled.semanticBpmn);
   const processDefinitionId = `${DELIVERY_GRAPH_PROCESS_ID}-${digest}`;
-  const bpmn = rewriteProcessId(compiled.bpmn, processDefinitionId);
+  // Per-node repository isolation (#739): resolve each agent cell's EFFECTIVE repository/base (its own
+  // declared `repository`/`baseBranch`, else the run-level fallback) and INJECT the flattened
+  // `io.nanobpm.agentTask.*` envelope task headers onto each agent service task POST-digest, replacing
+  // the compiler's digest-stable `__repoSpec` marker. This runs after `rewriteProcessId` and is a pure
+  // string transform of the laid-out BPMN (the digest is taken over the pre-injection semantic model,
+  // so the env-dependent `cloneTimeoutMs` and the run-level fallback never enter the content address).
+  // Throws `RepoEnvelopeUnresolvedError` when some agent cell resolves to NO repository and the run is
+  // not `repoless` — a loud launch failure, never a silent launch-dir share (#684/#729).
+  const bpmn = injectAgentRepoEnvelopes(rewriteProcessId(compiled.bpmn, processDefinitionId), graph, options);
 
   const runKey = options.runKey?.trim() || randomUUID();
   // Normalize the run-level timeouts through isoDuration so a programmatic caller that bypasses the
@@ -177,39 +193,14 @@ export async function runDeliveryGraph(
   const { processDefinitionId, bpmn, nodeInputs } = prep.prepared;
 
   await engine.deployResources([{ name: `${processDefinitionId}.bpmn`, content: bpmn, contentType: "application/xml" }]);
-  const base = typeof options.baseBranch === "string" && options.baseBranch.trim() !== "" ? options.baseBranch.trim() : null;
-  const repo = typeof options.repository === "string" && options.repository.trim() !== "" ? options.repository.trim() : null;
-  // Host-git provisioning (c8ctl, issue #684/#686/#729): resolve the ONE canonical repository envelope
-  // (`app/repoEnvelope.ts`) BEFORE seeding so every `agent` node's servicing `senior:*` job gets an
-  // ISOLATED throwaway clone instead of inheriting the worker's launch dir — otherwise several copilot
-  // workers on one host share (and clobber) a single checkout, the exact field failure #684 described.
-  // This is the delivery-graph analog of the whole-epic seed in `app/plan.ts`: a single run-root
-  // `createInstance` process variable that propagates through each agent cell's subProcess into its job.
-  // Like plan.ts's fan-out seed it carries `ref = base` but NO `branchCreate` — a run fans out to MANY
-  // agent nodes, each needing its own deterministic `feat/<node.id>` branch, so a single run-level
-  // envelope can't name one; each agent cuts its own branch off `base` inside the isolated clone (the
-  // agent-guide's `feat/*` convention, kept idempotent by the #551 preflight). `baseRef = base` too, so
-  // the harness keeps `origin/<base>` reachable for the review 3-dot diff.
-  //
-  // Issue #729: the envelope is REQUIRED here unless the run is EXPLICITLY `repoless`. A run that is not
-  // `repoless` but whose `repository`/`baseBranch` are unresolved throws `RepoEnvelopeUnresolvedError`
-  // (a loud launch failure the dispatch door surfaces as a 400 and `dispatchDeliveryGraphRun` marks the
-  // run `failed`) rather than silently emitting `{}` and degrading every agent to the shared launch dir.
-  // Only an explicit `repoless: true` (a conscious operator opt-in for a genuinely repo-less graph)
-  // dispatches with no envelope.
-  //
-  // `repoless: true` is MUTUALLY EXCLUSIVE with `repository`/`baseBranch`: the dispatch door already
-  // rejects the conflicting shape with a 400, but a PROGRAMMATIC caller (test/internal) that bypasses
-  // the door could pass both — and silently disable isolation (the `repoless` arm just drops the
-  // repo/base and emits `{}`). Re-enforce the exclusivity HERE too (defense-in-depth, mirroring the
-  // door) so a conflicting-but-well-meant call fails LOUDLY at seed time rather than quietly degrading
-  // to the shared launch dir it named a repo to avoid.
-  if (options.repoless === true && (repo !== null || base !== null)) {
-    throw new RepoEnvelopeConflictError(
-      `repoless run also named repository=${JSON.stringify(repo)} baseBranch=${JSON.stringify(base)}`,
-    );
-  }
-  const repoVars = options.repoless === true ? {} : requireRepoEnvelopeVars(repo ?? "", base, base);
+  // Per-node repository isolation (#739): the `io.nanobpm.agentTask.repository` envelope is now seeded
+  // PER agent cell as a task header (injected into `bpmn` by `prepareDeliveryGraph` →
+  // `injectAgentRepoEnvelopes`), NOT as a single run-root `createInstance` variable. A uniform run-root
+  // variable would resolve to ONE repository for every cell (wrong for a cross-repo graph) AND — because
+  // the harness lets a variable WIN over a header — would clobber each cell's per-node header. So NO
+  // repository variable is seeded here; the resolution + loud-failure invariant (unresolved agent cell
+  // on a non-`repoless` run) and the `repoless`/repo-base conflict guard all live in
+  // `injectAgentRepoEnvelopes`, which the prepare step above already ran (throwing before deploy).
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId,
     variables: {
@@ -219,9 +210,6 @@ export async function runDeliveryGraph(
       // node ioMapping in deliveryGraphCompiler). Seeded once at the run root — the same value for
       // every node — and read down into each agent job via `=transcriptUrlBase`.
       [TRANSCRIPT_URL_BASE_VAR]: transcriptUrlBaseFor(),
-      // Spread the resolved repository-isolation envelope (empty `{}` only on an explicit `repoless`
-      // run — see above) LAST so it never clobbers the other run-root vars.
-      ...repoVars,
     },
   });
   // The engine can yield a numeric key; `DeliveryRunHandle.processInstanceKey` is typed `string` and
@@ -245,6 +233,117 @@ function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
     .replace(`bpmnElement="${DELIVERY_GRAPH_PROCESS_ID}"`, `bpmnElement="${processDefinitionId}"`);
 }
 
+/** The EFFECTIVE repository/base resolved for one delivery-graph `agent` cell (#739): its OWN declared
+ * `repository`/`baseBranch`, falling back to the run-level dispatch value for either that it omits. */
+export interface ResolvedAgentRepo {
+  /** The agent node's id (for diagnostics / the unresolved-node error). */
+  nodeId: string;
+  /** The effective `owner/repo` — the node's declared `repository`, else the run-level fallback, else null. */
+  repository: string | null;
+  /** The effective base branch — the node's declared `baseBranch`, else the run-level fallback, else null. */
+  baseBranch: string | null;
+}
+
+/** Trim a caller/authored string to a non-empty value or null (a blank/whitespace/absent field is "not
+ * declared", so it falls back to the run level). */
+function trimOrNull(value: unknown): string | null {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+/** Resolve every `agent` node's EFFECTIVE repository + base (#739): the node's own declared
+ * `repository`/`baseBranch` wins, else the run-level dispatch `repository`/`baseBranch` is the fallback
+ * default. Non-agent nodes carry no repository, so they are excluded. This is the ONE resolution rule
+ * the injection AND the unresolved-node invariant both derive from, so the two can never disagree on
+ * what a cell resolves to. */
+export function resolveAgentNodeRepos(graph: DeliveryGraph, options: Pick<DeliveryRunOptions, "repository" | "baseBranch">): ResolvedAgentRepo[] {
+  const runRepo = trimOrNull(options.repository);
+  const runBase = trimOrNull(options.baseBranch);
+  const out: ResolvedAgentRepo[] = [];
+  for (const node of graph.nodes) {
+    if (node.kind !== "agent") continue;
+    out.push({
+      nodeId: node.id,
+      repository: trimOrNull(node.agent.repository) ?? runRepo,
+      baseBranch: trimOrNull(node.agent.baseBranch) ?? runBase,
+    });
+  }
+  return out;
+}
+
+/** The ids of every `agent` node that resolves to NO usable repository (#739) — it declared none AND no
+ * run-level fallback applies (or the resolved value is not a plain `owner/repo`). On a non-`repoless`
+ * run these are the cells that would silently share the worker's launch dir, so the runner throws when
+ * this is non-empty (issue #684/#729). A graph in which EVERY agent node resolves a repository (declared
+ * or defaulted) is fully node-provisioned and needs neither a run-level repository nor `repoless`. */
+export function unresolvedAgentRepoNodes(graph: DeliveryGraph, options: Pick<DeliveryRunOptions, "repository" | "baseBranch">): string[] {
+  return resolveAgentNodeRepos(graph, options)
+    .filter((r) => !isResolvableRepo(r.repository))
+    .map((r) => r.nodeId);
+}
+
+/** Escape a scalar value for an XML double-quote attribute (the injected `<zeebe:header>` value). The
+ * envelope values are URLs / `owner/repo` / `blob:none` / stringified booleans+numbers — none carry
+ * XML-hostile characters — but escape defensively so the injected BPMN is always well-formed. */
+function xmlAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/** Replace each `agent` service task's digest-stable `__repoSpec` marker task header (emitted by the
+ * compiler, carrying the node's DECLARED `{ repository, baseBranch }`) with the flattened, EFFECTIVE
+ * `io.nanobpm.agentTask.*` repository-isolation headers (#739) — the per-CELL channel the c8ctl harness
+ * reads (headers ∪ variables). The effective repo/base is the marker's declared value, else the
+ * run-level fallback in `options`. This is a PURE post-digest string transform of the laid-out BPMN
+ * (the marker is env-free graph content in the digest; the injected `cloneTimeoutMs` + run-level
+ * fallback are NOT), so the content address is unaffected.
+ *
+ * Invariants (issue #684/#729), enforced here so a run that cannot isolate fails LOUDLY before deploy:
+ *   • `repoless: true` is mutually exclusive with a run-level `repository`/`baseBranch` — a caller that
+ *     bypasses the dispatch door and passes both throws `RepoEnvelopeConflictError` (never silently
+ *     disables isolation).
+ *   • On a non-`repoless` run, ANY agent cell that resolves to no repository throws
+ *     `RepoEnvelopeUnresolvedError` (never a silent launch-dir share).
+ * On a `repoless` run every marker is stripped (no envelope — the conscious checkout-less opt-out). */
+function injectAgentRepoEnvelopes(bpmn: string, graph: DeliveryGraph, options: DeliveryRunOptions): string {
+  const repoless = options.repoless === true;
+  const runRepo = trimOrNull(options.repository);
+  const runBase = trimOrNull(options.baseBranch);
+  if (repoless && (runRepo !== null || runBase !== null)) {
+    throw new RepoEnvelopeConflictError(
+      `repoless run also named repository=${JSON.stringify(runRepo)} baseBranch=${JSON.stringify(runBase)}`,
+    );
+  }
+  if (!repoless) {
+    const unresolved = unresolvedAgentRepoNodes(graph, options);
+    if (unresolved.length > 0) {
+      throw new RepoEnvelopeUnresolvedError(
+        `agent node(s) resolve to no repository and the run is not repoless: ${unresolved.join(", ")} — ` +
+          "declare each node's `repository`, supply a run-level `repository`/`baseBranch` fallback, or dispatch `repoless: true`",
+      );
+    }
+  }
+  const markerKey = AGENT_REPO_SPEC_HEADER.replace(/[.]/g, "\\.");
+  // The compiler emits the marker as a single `<zeebe:taskHeaders>` block per agent task; match the whole
+  // block (with its indentation) so a stripped cell leaves no empty `<zeebe:taskHeaders/>` behind.
+  const blockRe = new RegExp(
+    `([ \\t]*)<zeebe:taskHeaders>\\r?\\n[ \\t]*<zeebe:header key="${markerKey}" value=(?:'([^']*)'|"([^"]*)")\\s*/>\\r?\\n[ \\t]*</zeebe:taskHeaders>(\\r?\\n)`,
+    "g",
+  );
+  return bpmn.replace(blockRe, (_full, indent: string, sq: string | undefined, dq: string | undefined, tail: string) => {
+    const raw = sq ?? (dq ?? "").replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+    const declared: { repository: string | null; baseBranch: string | null } = JSON.parse(raw);
+    // `repoless` → strip the block entirely (no isolation envelope, the launch-dir fallback).
+    if (repoless) return "";
+    const effRepo = trimOrNull(declared.repository) ?? runRepo;
+    const effBase = trimOrNull(declared.baseBranch) ?? runBase;
+    // The unresolved invariant above guarantees a resolvable repo here on a non-repoless run.
+    const envelope = agentNodeRepoEnvelope(effRepo ?? "", effBase);
+    const flat = flattenAgentTaskEnvelope(envelope);
+    const headerLines = Object.entries(flat).map(([k, v]) => `${indent}  <zeebe:header key="${xmlAttr(k)}" value="${xmlAttr(v)}" />`);
+    if (headerLines.length === 0) return "";
+    return `${indent}<zeebe:taskHeaders>\n${headerLines.join("\n")}\n${indent}</zeebe:taskHeaders>${tail}`;
+  });
+}
+
 /** The idempotency preflight prepended to EVERY `agent` node's `appendPrompt` (issue #551). A delivery
  * agent node dispatches a raw `senior:feature` job with no `feature_runs` idempotency row and no
  * PR-existence guard, and the job carries retries — so an idle/timeout re-dispatch hands the SAME

package/app/repoEnvelope.ts

@@ -13,7 +13,7 @@ import { isCommitSha } from "./world/index.ts";
 
 /** The reserved namespace key the c8ctl nano worker harness reads the agent-task envelope from
  * (headers ∪ variables, deep-merged). See c8ctl `normalizeTaskEnvelope`. */
-const AGENT_TASK_NS = "io.nanobpm.agentTask";
+export const AGENT_TASK_NS = "io.nanobpm.agentTask";
 
 /** The ONE canonical `owner/repo` allowlist, shared by `repoEnvelopeVars` (which degrades to `{}` on a
  * miss) and `requireRepoEnvelopeVars` (which throws on a miss) so the two can never drift apart. The
@@ -25,6 +25,47 @@ function isPlainOwnerRepo(repo: string): boolean {
   return OWNER_REPO_RE.test(repo) && !/\.git$/i.test(repo);
 }
 
+/** Exported predicate mirroring the internal `owner/repo` allowlist (the ONE shared by
+ * `repoEnvelopeVars`/`requireRepoEnvelopeVars`), so a caller that must resolve a per-node effective
+ * repository BEFORE seeding an envelope (delivery-graph per-node isolation, #739) uses exactly the same
+ * gate — a node whose declared/defaulted repository is not a plain `owner/repo` is "unresolved" by the
+ * identical rule the seed helper throws on, never a second divergent check. */
+export function isResolvableRepo(repo: unknown): repo is string {
+  return typeof repo === "string" && isPlainOwnerRepo(repo.trim());
+}
+
+/** Flatten a repository-isolation envelope object (as built by {@link repoEnvelopeVars} —
+ * `{ "io.nanobpm.agentTask": { repository: { … } } }`) into the FLAT, dotted `io.nanobpm.agentTask.*`
+ * key → string-value pairs the c8ctl worker harness reads from a service task's `<zeebe:taskHeaders>`
+ * (the same channel the retired `io.nanobpm.agentTask.task.prompt` header used; the harness deep-merges
+ * headers ∪ variables and reconstructs the nested envelope from dotted keys — see `normalizeTaskEnvelope`).
+ *
+ * Header VALUES are strings (a Camunda job header is `string → string`), so scalar leaves are stringified
+ * (`true`/`600000`/`https://…`); the harness coerces them back at the point of use. This is the ONLY
+ * per-CELL delivery channel for the envelope: a `createInstance` variable can only seed the reserved
+ * `io.nanobpm.agentTask` key ONCE at the run root (uniform for every cell), and a `<zeebe:ioMapping>`
+ * target with dots creates a NESTED `{io:{nanobpm:{agentTask:…}}}` object the flat-key harness never
+ * reads — so per-node isolation (#739) rides task headers, injected by the runner post-digest. Returns an
+ * empty map for an empty/`{}` envelope (an unresolved/`repoless` cell → no headers, the launch-dir
+ * fallback). */
+export function flattenAgentTaskEnvelope(envelope: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  const walk = (prefix: string, value: unknown): void => {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      for (const [k, v] of Object.entries(value)) {
+        walk(prefix === "" ? k : `${prefix}.${k}`, v);
+      }
+      return;
+    }
+    // Scalar leaf — a taskHeader value is a string, so stringify booleans/numbers verbatim; the harness
+    // coerces (`singleBranch` truthy, `cloneTimeoutMs` numeric) at the point of use.
+    if (typeof value === "string") out[prefix] = value;
+    else if (typeof value === "number" || typeof value === "boolean") out[prefix] = String(value);
+  };
+  walk("", envelope);
+  return out;
+}
+
 /** Raised by `requireRepoEnvelopeVars` when the repository-isolation envelope is REQUIRED on a fan-out
  * path but its inputs are unresolved (a blank base/head `ref`, or a `repo` that is not a plain
  * `owner/repo`). Issue #729: the fan-out dispatch paths must fail loudly here rather than let
@@ -154,6 +195,37 @@ export function repoEnvelopeVars(
   };
 }
 
+/** Build the repository-isolation envelope for ONE delivery-graph `agent` cell (#739), keyed under the
+ * reserved {@link AGENT_TASK_NS} namespace exactly like {@link repoEnvelopeVars}, but with the delivery
+ * per-node semantics: the `repository.url` is emitted whenever `repo` is a plain `owner/repo` (so the
+ * harness clones it) EVEN WHEN no base branch is known, and `ref`/`baseRef` are emitted only when `base`
+ * is present. This is the key difference from {@link repoEnvelopeVars} (which emits NOTHING without a
+ * `ref`): a cross-repo graph node carries only its `owner/repo` (an issue ref names no branch), so when
+ * neither the node nor the run declares a base the cell must still provision an isolated clone — of the
+ * repository's DEFAULT branch. The harness `provisionRepo` omits `--branch` when `ref` is blank, so a
+ * `ref`-less envelope clones the default branch (each agent then cuts its own `feat/<node.id>` branch
+ * inside the isolated clone, unchanged). Returns `{}` for a `repo` that is not a plain `owner/repo` (an
+ * unresolved cell — the runner's invariant rejects the run before this degrades to a launch-dir share).
+ * Blobless single-branch shaping + `cloneTimeoutMs` (issues #287/#694) are emitted on every cell. */
+export function agentNodeRepoEnvelope(repo: string, base: string | null): Record<string, unknown> {
+  if (!isPlainOwnerRepo(repo)) return {};
+  const ref = typeof base === "string" && base.trim() !== "" ? base.trim() : null;
+  return {
+    [AGENT_TASK_NS]: {
+      repository: {
+        provider: "github",
+        url: `https://github.com/${repo}.git`,
+        singleBranch: true,
+        filter: "blob:none",
+        cloneTimeoutMs: cloneTimeoutMs(),
+        // A per-node base (declared, or defaulted from the run level) — the branch the agent cuts its
+        // `feat/<node.id>` off. Omitted when unknown so the harness clones the repo's default branch.
+        ...(ref ? { ref, baseRef: ref } : {}),
+      },
+    },
+  };
+}
+
 /** The REQUIRED-envelope guard for the fan-out dispatch paths (issue #729). Same signature and output
  * as `repoEnvelopeVars`, but THROWS `RepoEnvelopeUnresolvedError` on an unresolved input (a blank
  * base/head `ref`, or a `repo` that is not a plain `owner/repo`) instead of degrading to the silent