@nanobpm/nano-workforce 0.178.5 → 0.179.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.179.0](https://github.com/nanobpm/nano-workforce/compare/v0.178.5...v0.179.0) (2026-09-04)
+
+### Features
+
+* **fan-out:** require the repository-isolation envelope on fan-out dispatch ([#730](https://github.com/nanobpm/nano-workforce/issues/730)) ([f94425d](https://github.com/nanobpm/nano-workforce/commit/f94425db5d447260a0e4c9f31b120695f8d18a7c)), closes [#729](https://github.com/nanobpm/nano-workforce/issues/729)
+
 ## [0.178.5](https://github.com/nanobpm/nano-workforce/compare/v0.178.4...v0.178.5) (2026-09-03)
 
 ### Bug Fixes

package/app/deliveryGraphDeploy.test.ts

@@ -68,7 +68,7 @@ test("deploy+advance: a well-formed graph deploys through the real engine and ev
     await engine.registerWorker("pr.readiness-probe", async () => ({ ready: true, mergedSha: "deadbeefcafe" }));
     await engine.registerWorker(DELIVERY_CONNECTOR_TASK_TYPE, async () => ({}));
 
-    const run = await runDeliveryGraph(engine, MATRIX_GRAPH);
+    const run = await runDeliveryGraph(engine, MATRIX_GRAPH, { repoless: true });
     assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
     const key = run.handle.processInstanceKey;
 
@@ -120,7 +120,7 @@ test("deploy+advance: a stalled service node escalates on its node-timeout bound
     };
     // Short node timeout so the boundary fires within one virtual-clock advance; a long SLA so the
     // human node's own escalation boundary never fires during the drive.
-    const run = await runDeliveryGraph(engine, graph, { nodeTimeout: "PT1M", escalationSlaTimeout: "PT1H" });
+    const run = await runDeliveryGraph(engine, graph, { nodeTimeout: "PT1M", escalationSlaTimeout: "PT1H", repoless: true });
     assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
     const key = run.handle.processInstanceKey;
 
@@ -256,7 +256,7 @@ test("#543 transcript correlation: a completed agent job exposes a resolvable in
       ],
       edges: [{ from: "impl", to: "review" }],
     };
-    const run = await runDeliveryGraph(engine, graph);
+    const run = await runDeliveryGraph(engine, graph, { repoless: true });
     assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
     const key = run.handle.processInstanceKey;
 
@@ -324,7 +324,7 @@ async function driveGuarded(outcome: "breaking" | "green"): Promise<{ state: str
       return {};
     });
 
-    const run = await runDeliveryGraph(engine, GUARDED_ADOPT);
+    const run = await runDeliveryGraph(engine, GUARDED_ADOPT, { repoless: true });
     assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
     const key = run.handle.processInstanceKey;
 
@@ -425,7 +425,7 @@ async function driveGuardedRealAgent(outcome: "breaking" | "compatible"): Promis
       return {};
     });
 
-    const run = await runDeliveryGraph(engine, GUARDED_ADOPT_REAL);
+    const run = await runDeliveryGraph(engine, GUARDED_ADOPT_REAL, { repoless: true });
     assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
     const key = run.handle.processInstanceKey;
 
@@ -487,7 +487,7 @@ test("S7 deploy+route: mutually-exclusive leaves join End on an exclusive merge
         doneRan = true;
         return {};
       });
-      const run = await runDeliveryGraph(engine, graph, { escalationSlaTimeout: "PT1H" });
+      const run = await runDeliveryGraph(engine, graph, { escalationSlaTimeout: "PT1H", repoless: true });
       assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
       const key = run.handle.processInstanceKey;
       let state = "?";
@@ -516,7 +516,7 @@ test("S7 deploy+route: mutually-exclusive leaves join End on an exclusive merge
         doneRan = true;
         return {};
       });
-      const run = await runDeliveryGraph(engine, graph, { escalationSlaTimeout: "PT1H" });
+      const run = await runDeliveryGraph(engine, graph, { escalationSlaTimeout: "PT1H", repoless: true });
       assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
       const key = run.handle.processInstanceKey;
       let parked = "";

package/app/deliveryGraphDispatch.test.ts

@@ -91,7 +91,7 @@ const SIDE_EFFECTING = {
 
 test("dispatchDeliveryGraphRun: a human-only graph launches straight away (running), one engine instance", async () => {
   const { app, started, runs } = makeApp();
-  const res = await dispatchDeliveryGraphRun(app, HUMAN_ONLY);
+  const res = await dispatchDeliveryGraphRun(app, HUMAN_ONLY, { repoless: true });
   assertEquals(res.ok, true);
   if (!res.ok) return;
   assertEquals(res.status, "running");
@@ -103,7 +103,7 @@ test("dispatchDeliveryGraphRun: a human-only graph launches straight away (runni
 
 test("dispatchDeliveryGraphRun: a side-effecting graph dispatches with NO approval token — the operator seam IS the approval", async () => {
   const { app, started, runs } = makeApp();
-  const res = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  const res = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING, { repoless: true });
   assertEquals(res.ok, true);
   if (!res.ok) return;
   assertEquals(res.status, "running");
@@ -114,9 +114,9 @@ test("dispatchDeliveryGraphRun: a side-effecting graph dispatches with NO approv
 
 test("dispatchDeliveryGraphRun: a re-dispatch of a still-running run short-circuits (alreadyRunning) — the side effect launches at most once", async () => {
   const { app, started } = makeApp();
-  const first = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  const first = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING, { repoless: true });
   assert(first.ok);
-  const second = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  const second = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING, { repoless: true });
   assertEquals(second.ok, true);
   if (!second.ok) return;
   assertEquals(second.alreadyRunning, true);
@@ -125,8 +125,8 @@ test("dispatchDeliveryGraphRun: a re-dispatch of a still-running run short-circu
 
 test("dispatchDeliveryGraphRun: an explicit idempotency key forces a distinct run row", async () => {
   const { app, started } = makeApp();
-  await dispatchDeliveryGraphRun(app, HUMAN_ONLY);
-  await dispatchDeliveryGraphRun(app, HUMAN_ONLY, { runKey: "second-run" });
+  await dispatchDeliveryGraphRun(app, HUMAN_ONLY, { repoless: true });
+  await dispatchDeliveryGraphRun(app, HUMAN_ONLY, { runKey: "second-run", repoless: true });
   assertEquals(started.length, 2);
 });
 

package/app/deliveryGraphDispatch.ts

@@ -49,7 +49,7 @@ export type DispatchDeliveryGraphResult =
 export async function dispatchDeliveryGraphRun(
   app: Pick<AppApi, "data" | "engine" | "log">,
   graph: unknown,
-  options: { runKey?: string | null; title?: string | null; repository?: string | null; baseBranch?: string | null } & DeliveryRunTimeouts = {},
+  options: { runKey?: string | null; title?: string | null; repository?: string | null; baseBranch?: string | null; repoless?: boolean } & DeliveryRunTimeouts = {},
 ): Promise<DispatchDeliveryGraphResult> {
   const validationErrors = validateDeliveryGraph(graph);
   if (validationErrors.length > 0) {
@@ -140,11 +140,14 @@ export async function dispatchDeliveryGraphRun(
       escalationSlaTimeout: options.escalationSlaTimeout,
       probePollEvery: options.probePollEvery,
       escalationAssignee: options.escalationAssignee,
-      // Host-git provisioning (#684/#686): forward the run-level repo/base so the runner seeds the
-      // `io.nanobpm.agentTask.repository` isolation envelope onto every agent cell's job (absent → the
-      // runner emits no envelope and the harness keeps its legacy launch-dir behaviour).
+      // Host-git provisioning (#684/#686/#729): forward the run-level repo/base so the runner seeds the
+      // `io.nanobpm.agentTask.repository` isolation envelope onto every agent cell's job. The envelope is
+      // REQUIRED unless the run is EXPLICITLY `repoless` — an unresolved repo/base on a non-`repoless`
+      // run is a hard launch failure (marked `failed` below via the catch), never a silent no-envelope
+      // fallback to the shared launch dir. The dispatch door enforces the same contract at submit (400).
       repository: options.repository,
       baseBranch: options.baseBranch,
+      repoless: options.repoless,
     });
   } catch (err) {
     await markClaimFailed();

package/app/deliveryRunner.test.ts

@@ -10,8 +10,9 @@
 // The engine-native EXECUTION of a prepared graph (deploy + run + gate + fan-in + late-bind + dedupe) is
 // proven end-to-end in `e2e/delivery-graph.e2e.ts`.
 import { test } from "node:test";
-import { assert, assertEquals } from "#test-assert";
+import { assert, assertEquals, assertRejects } from "#test-assert";
 import { prepareDeliveryGraph, renderIdempotencyPreamble, runDeliveryGraph } from "./deliveryRunner.ts";
+import { RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError } from "./repoEnvelope.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 
 const GRAPH: DeliveryGraph = {
@@ -357,7 +358,7 @@ test("runDeliveryGraph coerces a numeric engine processInstanceKey to a string h
     deployResources: async () => [],
     createInstance: async () => ({ processInstanceKey: 987654321 as unknown as string }),
   };
-  const r = await runDeliveryGraph(engine, GRAPH);
+  const r = await runDeliveryGraph(engine, GRAPH, { repoless: true });
   assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
   assertEquals(r.handle.processInstanceKey, "987654321");
   assertEquals(typeof r.handle.processInstanceKey, "string");
@@ -401,22 +402,55 @@ test("runDeliveryGraph seeds the repository isolation envelope when repository +
   assertEquals("branch" in repo, false);
 });
 
-test("runDeliveryGraph emits NO envelope when repository/baseBranch are absent — repo-less graphs unchanged (#686)", async () => {
+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("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, seen } = captureCreateInstanceVars();
-    const r = await runDeliveryGraph(engine, GRAPH, options);
-    assert(r.ok, `expected ok:true for ${JSON.stringify(options)}, got ${JSON.stringify(r)}`);
-    assertEquals("io.nanobpm.agentTask" in seen(), false, `no envelope expected for ${JSON.stringify(options)}`);
+    const { engine } = captureCreateInstanceVars();
+    await assertRejects(
+      () => runDeliveryGraph(engine, GRAPH, options),
+      RepoEnvelopeUnresolvedError,
+    );
   }
 });
 
-test("runDeliveryGraph drops a malformed repository rather than emitting a bogus clone URL (#686)", async () => {
-  const { engine, seen } = captureCreateInstanceVars();
-  // A value that is not exactly `owner/repo` (a trailing `.git`) must degrade to NO envelope — the
-  // helper's defence-in-depth guard — never a double-suffixed `…/owner/repo.git.git` clone URL.
-  const r = await runDeliveryGraph(engine, GRAPH, { repository: "owner/repo.git", baseBranch: "main" });
-  assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
-  assertEquals("io.nanobpm.agentTask" in seen(), false);
+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.
+  await assertRejects(
+    () => runDeliveryGraph(engine, GRAPH, { repository: "owner/repo.git", baseBranch: "main" }),
+    RepoEnvelopeUnresolvedError,
+  );
+});
+
+test("runDeliveryGraph 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.
+  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),
+      RepoEnvelopeConflictError,
+    );
+  }
 });
 
 test("the canonical `agent → converge-merge → wait[pr merged]` graph DISPATCHES with a fact-bound wait target (#570)", async () => {
@@ -444,7 +478,7 @@ test("the canonical `agent → converge-merge → wait[pr merged]` graph DISPATC
     deployResources: async () => [],
     createInstance: async () => ({ processInstanceKey: "555" }),
   };
-  const r = await runDeliveryGraph(engine, graph);
+  const r = await runDeliveryGraph(engine, graph, { repoless: true });
   assert(r.ok, `expected the canonical fact-bound wait[pr] graph to launch, got ${JSON.stringify(r)}`);
   assertEquals(r.handle.processInstanceKey, "555");
 });

package/app/deliveryRunner.ts

@@ -20,7 +20,7 @@ import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generate
 import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
 import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
-import { repoEnvelopeVars } from "./repoEnvelope.ts";
+import { RepoEnvelopeConflictError, requireRepoEnvelopeVars } from "./repoEnvelope.ts";
 import { isoDuration } from "./reviewWait.ts";
 
 /** The content digest of a compiled graph — `sha256(semanticBpmn)[:12]` — the single source of truth
@@ -62,18 +62,27 @@ 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. When supplied together with
-   * `baseBranch`, the runner seeds the canonical repository-provisioning envelope
-   * (`io.nanobpm.agentTask.repository`, via `repoEnvelopeVars`) 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). Absent/unresolved → NO envelope is emitted and the harness falls
-   * back to the legacy launch-dir behaviour, so today's repo-less graphs are unchanged. */
+  /** 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).
+   *
+   * 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. */
   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). Only consulted when `repository` is also set. */
+   * branch off this base inside the clone). Required (with `repository`) unless the run is `repoless`. */
   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. */
+  repoless?: boolean;
 }
 
 const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
@@ -170,6 +179,37 @@ export async function runDeliveryGraph(
   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);
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId,
     variables: {
@@ -179,20 +219,9 @@ 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(),
-      // Host-git provisioning (c8ctl, issue #684/#686): deliver the ONE canonical repository envelope
-      // (`repoEnvelopeVars`, app/repoEnvelope.ts) 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.
-      // Spread last so an unresolved repo/base (`{}`) leaves the other run-root vars untouched — a
-      // repo-less graph is then dispatched exactly as before (legacy launch-dir behaviour).
-      ...repoEnvelopeVars(repo ?? "", base, base),
+      // 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

package/app/feature.ts

@@ -20,7 +20,7 @@ import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { derivedTrackingTable } from "./instanceTracking.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
 import type { ReadinessProbe } from "./readiness.ts";
-import { repoEnvelopeVars } from "./repoEnvelope.ts";
+import { requireRepoEnvelopeVars } from "./repoEnvelope.ts";
 
 /** Optional intake-time readiness gate for a feature run (issue #295): the `capability`/`command`/…
  * probes the run must ALL satisfy before its implementation agent is dispatched (parked, durably, at
@@ -491,9 +491,12 @@ export async function startFeature(
       // implementation jobs share — and clobber — one checkout, violating the durable-resume design).
       // A feature run is PRE-PR: there is no head branch yet, so the harness checks out the BASE
       // branch (`ref = base`) and creates the deterministic `feat/<task.id>` feature branch itself
-      // (`branchCreate`), matching the agent-guide's `feat/*` convention. Spread last so an unresolved
-      // repo (`{}`) leaves the other vars untouched.
-      ...repoEnvelopeVars(parsed.repo, base, null, null, prePrBranch),
+      // (`branchCreate`), matching the agent-guide's `feat/*` convention. This is a fan-out seed, so it
+      // is REQUIRED (issue #729): `parsed.repo` is regex-bound (`parseIssue`) and `base` is
+      // `normalizeBaseBranch`-validated non-blank, so the `requireRepoEnvelopeVars` guard never trips
+      // here — but it turns an unresolved repo/base into a HARD launch failure rather than a silent `{}`
+      // that would degrade the agent to the shared launch dir.
+      ...requireRepoEnvelopeVars(parsed.repo, base, null, null, prePrBranch),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/plan.ts

@@ -30,7 +30,7 @@ import {
 import { derivedTrackingTable } from "./instanceTracking.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
 import type { ReadinessProbe } from "./readiness.ts";
-import { repoEnvelopeVars } from "./repoEnvelope.ts";
+import { requireRepoEnvelopeVars } from "./repoEnvelope.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
 
 /** The BPMN process this module drives (resources/processes/plan-fanout.bpmn). */
@@ -1048,8 +1048,11 @@ export async function startPlan(
       // but NO `branchCreate`: each slice's deterministic `feat/<task.id>` branch differs per MI child,
       // so the agent cuts its own branch inside the isolated clone (per resources/prompts/feature.md).
       // The process-level variable propagates through the wave subprocess + `implement-cell` callActivity
-      // into each agent job. Spread last so an unresolved repo (`{}`) leaves the other vars untouched.
-      ...repoEnvelopeVars(parsed.repo, base),
+      // into each agent job. This is a fan-out seed, so it is REQUIRED (issue #729): `parsed.repo` is
+      // regex-bound (`parseIssue`) and `base` is `normalizeBaseBranch`-validated non-blank, so the
+      // `requireRepoEnvelopeVars` guard never trips here — but it makes an unresolved repo/base a HARD
+      // launch failure rather than a silent `{}` that would degrade every slice to the shared launch dir.
+      ...requireRepoEnvelopeVars(parsed.repo, base),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/repoEnvelope.ts

@@ -15,6 +15,49 @@ import { isCommitSha } from "./world/index.ts";
  * (headers ∪ variables, deep-merged). See c8ctl `normalizeTaskEnvelope`. */
 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
+ * owner is a GitHub login (alphanumeric + hyphen); the repo-name segment additionally allows `.` and
+ * `_`. A trailing `.git` is rejected outright so we never emit a double-suffixed `…/owner/repo.git.git`,
+ * and the anchored allowlist bars query/fragment/host-injection chars. */
+const OWNER_REPO_RE = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/;
+function isPlainOwnerRepo(repo: string): boolean {
+  return OWNER_REPO_RE.test(repo) && !/\.git$/i.test(repo);
+}
+
+/** 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
+ * `repoEnvelopeVars` silently emit `{}` and degrade to the shared launch-dir behaviour (issue #684's
+ * field failure re-opened as a silent fallback). The API edge maps this to a clean 400 / launch error;
+ * a caller that legitimately wants no clone must opt in EXPLICITLY (never reach this helper) so the
+ * default can never silently share a checkout. */
+export class RepoEnvelopeUnresolvedError extends Error {
+  readonly reason: string;
+  constructor(reason: string) {
+    super(`repository-isolation envelope is required but its input is unresolved: ${reason}`);
+    this.name = "RepoEnvelopeUnresolvedError";
+    this.reason = reason;
+  }
+}
+
+/** Raised when a fan-out dispatch supplies a repository-isolation envelope (`repository`/`baseBranch`)
+ * AND an explicit `repoless: true` opt-out at the same time (issue #729). The two are mutually
+ * exclusive: `repoless: true` means "dispatch a genuinely checkout-less graph with NO envelope", so a
+ * caller that also names a repo/base is contradictory. The dispatch door already rejects this shape
+ * with a 400, but a PROGRAMMATIC caller that bypasses the door could still pass both — and silently
+ * disable the very isolation the envelope guards (the runner would drop the repo/base and emit `{}`).
+ * Failing loudly here too keeps the mutual exclusivity enforced at the seed point, not only at the HTTP
+ * edge, so isolation can never be silently disabled by a conflicting-but-well-meant call. */
+export class RepoEnvelopeConflictError extends Error {
+  readonly reason: string;
+  constructor(reason: string) {
+    super(`repository-isolation envelope conflicts with an explicit repoless opt-out: ${reason}`);
+    this.name = "RepoEnvelopeConflictError";
+    this.reason = reason;
+  }
+}
+
 /** Build the repository slice of the agent-task envelope for an agent job. Delivered as a *process
  * variable* under the reserved `io.nanobpm.agentTask` key so the harness provisions an isolated
  * clone — instead of the agent inheriting whatever directory the worker was launched from (which
@@ -63,10 +106,7 @@ export function repoEnvelopeVars(
   // `owner/repo`), but this is an exported helper the fan-out epic gives many new callers. A repo
   // that is not exactly `owner/repo` would build a bogus clone URL, so emit nothing (the harness
   // then falls back to the launch-dir behaviour) rather than handing the harness a malformed URL.
-  // The owner is a GitHub login (alphanumeric + hyphen); the repo-name segment additionally allows
-  // `.` and `_`. A trailing `.git` is rejected outright so we never emit a double-suffixed
-  // `…/owner/repo.git.git`, and the anchored allowlist bars query/fragment/host-injection chars.
-  if (!/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/.test(repo) || /\.git$/i.test(repo)) return {};
+  if (!isPlainOwnerRepo(repo)) return {};
   return {
     [AGENT_TASK_NS]: {
       repository: {
@@ -114,6 +154,37 @@ export function repoEnvelopeVars(
   };
 }
 
+/** 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
+ * `{}` that leaves the agent job inheriting the worker's launch dir. Every fan-out seed
+ * (`app/deliveryRunner.ts` `runDeliveryGraph`, `app/plan.ts` `startPlan`, `app/feature.ts`
+ * `startFeature`) MUST route through this helper so a run that can't be isolated fails LOUDLY at seed
+ * time — never silently shares (and clobbers) one checkout across concurrent workers on a host (issue
+ * #684, re-opened as a silent fallback). A dispatch that legitimately wants no clone must opt in
+ * EXPLICITLY at its door (e.g. delivery-graph `repoless: true`) and simply never call this. */
+export function requireRepoEnvelopeVars(
+  repo: string,
+  ref: string | null,
+  baseRef: string | null = null,
+  commitSha: string | null = null,
+  branchCreate: string | null = null,
+): Record<string, unknown> {
+  if (typeof ref !== "string" || ref.trim() === "") {
+    throw new RepoEnvelopeUnresolvedError("base/head ref is blank — the harness has no branch to check out");
+  }
+  if (!isPlainOwnerRepo(repo)) {
+    throw new RepoEnvelopeUnresolvedError(`repo is not an \`owner/repo\` reference: ${JSON.stringify(repo)}`);
+  }
+  const vars = repoEnvelopeVars(repo, ref, baseRef, commitSha, branchCreate);
+  // repoEnvelopeVars degrades to `{}` on exactly the two conditions rejected above, so a non-empty
+  // envelope is guaranteed here. Assert it so the degrade-vs-throw pair can never silently drift.
+  if (Object.keys(vars).length === 0) {
+    throw new RepoEnvelopeUnresolvedError(`envelope resolved empty for repo=${JSON.stringify(repo)} ref=${JSON.stringify(ref)}`);
+  }
+  return vars;
+}
+
 /** Resolve the clone timeout (ms) the harness applies to provisioning, from the one typed knob
  * `NANO_PR_CLONE_TIMEOUT_MS` (default 600000 = 10 min; issue #694). A branch-scoped blobless clone
  * of a large monorepo still approaches/exceeds the harness's 120s default, so we raise it here. A

package/e2e/delivery-graph-dispatch.e2e.ts

@@ -100,7 +100,7 @@ describe("delivery-graph dispatch — agent compiles→stages, operator dispatch
     assert.equal(proposal?.status, "staged");
 
     // ── Operator dispatch: dispatch the digest → deploys + runs engine-natively ───────────────────
-    const dispatched = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest } });
+    const dispatched = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest, repoless: true } });
     assert.equal(dispatched.status, 202, "dispatching a staged digest launches the run");
     assert.equal(dispatched.body.status, "running");
     assert.equal(dispatched.body.alreadyRunning, false);
@@ -122,7 +122,7 @@ describe("delivery-graph dispatch — agent compiles→stages, operator dispatch
     assert.match(String(phased?.phase), /^Parked on human node:/, `phase shows the parked human node, got ${phased?.phase}`);
 
     // ── No replay: the consumed proposal cannot re-launch ─────────────────────────────────────────
-    const replay = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest } });
+    const replay = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest, repoless: true } });
     assert.equal(replay.status, 400, "an already-dispatched digest cannot be re-dispatched");
     await app.settle();
     assert.equal(agentFired, 1, "the agent side effect STILL fired only once (no double-launch)");
@@ -146,7 +146,7 @@ describe("delivery-graph dispatch — agent compiles→stages, operator dispatch
     const graph: DeliveryGraph = { name: "manual gate", nodes: [{ id: "ack", kind: "human", human: { prompt: "click done" } }] };
     const staged = await api.call<StagedResult>("compileDeliveryGraph", { body: graph });
     assert.equal(staged.status, 200);
-    const res = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest: staged.body.digest } });
+    const res = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest: staged.body.digest, repoless: true } });
     assert.equal(res.status, 202, "dispatching a human-only graph runs it");
     assert.equal(res.body.status, "running");
     assert.equal(res.body.sideEffecting, false);

package/e2e/delivery-graph.e2e.ts

@@ -125,7 +125,7 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
       ],
     };
 
-    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S" });
+    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S", repoless: true });
     assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
     await app.settle();
 
@@ -174,7 +174,7 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
       edges: [{ from: "a.cmd", to: "w" }],
     };
 
-    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S" });
+    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S", repoless: true });
     assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
     await app.settle();
 
@@ -209,7 +209,7 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
       ],
       edges: [],
     };
-    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S", probePollEvery: "PT1S", escalationSlaTimeout: "PT1H" });
+    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S", probePollEvery: "PT1S", escalationSlaTimeout: "PT1H", repoless: true });
     assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
     await app.settle();