@nanobpm/nano-workforce 0.171.5 → 0.171.7

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.171.7](https://github.com/nanobpm/nano-workforce/compare/v0.171.6...v0.171.7) (2026-09-01)
+
+### Bug Fixes
+
+* **agentic:** seed repository isolation envelope on delivery-graph agent cells ([#687](https://github.com/nanobpm/nano-workforce/issues/687)) ([8c96a7d](https://github.com/nanobpm/nano-workforce/commit/8c96a7db34a6e389d09d5b9968fbcbc362d85cd5)), closes [#686](https://github.com/nanobpm/nano-workforce/issues/686) [#684](https://github.com/nanobpm/nano-workforce/issues/684) [#685](https://github.com/nanobpm/nano-workforce/issues/685) [#551](https://github.com/nanobpm/nano-workforce/issues/551) [#686](https://github.com/nanobpm/nano-workforce/issues/686)
+
+## [0.171.6](https://github.com/nanobpm/nano-workforce/compare/v0.171.5...v0.171.6) (2026-09-01)
+
+### Bug Fixes
+
+* **agentic:** emit the repository envelope on implementation jobs so they run in an isolated clone ([#685](https://github.com/nanobpm/nano-workforce/issues/685)) ([be98081](https://github.com/nanobpm/nano-workforce/commit/be980818321f18e101d0fbef85b30b75d6a6fd15)), closes [#684](https://github.com/nanobpm/nano-workforce/issues/684)
+
 ## [0.171.5](https://github.com/nanobpm/nano-workforce/compare/v0.171.4...v0.171.5) (2026-09-01)
 
 ### Performance Improvements

package/app/baseBranch.ts

@@ -0,0 +1,56 @@
+// Base-branch name validation — the canonical, side-effect-free gate shared by every door that
+// accepts a caller-supplied branch name (the epic launch doors via `app/plan.ts`, and the
+// operator delivery-graph dispatch door in `operations/dispatchDeliveryGraph.ts`).
+//
+// This is a deliberate LEAF module: it imports nothing and runs no top-level initialization, so an
+// API door can pull in the validator without dragging in `app/plan.ts`'s substantial transitive
+// imports and its import-time env seeding (`ESCALATION_SLA_TIMEOUT`/`CAPS_WAIT_TIMEOUT`). `plan.ts`
+// re-exports these symbols, so existing importers are unaffected — this is derivation over
+// duplication (one implementation), just hoisted below the heavy module.
+
+/** Raised when a caller supplies a `baseBranch` that isn't a plausible git branch name. The
+ * value is interpolated into the authoritative implementer prompt (which carries `git`/`gh`
+ * shell snippets and inline-code Markdown), so a non-ref value could break the rendered
+ * instructions or smuggle in a command/prompt fragment — reject it at the edge instead. */
+export class InvalidBaseBranchError extends Error {
+  readonly value: string;
+  constructor(value: string) {
+    super(`invalid base branch name: ${JSON.stringify(value)}`);
+    this.name = "InvalidBaseBranchError";
+    this.value = value;
+  }
+}
+
+/** Raised when a caller supplies a blank/absent `baseBranch`. Every epic launch must name its base
+ * branch explicitly (ADR 0003): "land on the default branch" is a conscious, named, confirmed choice
+ * (the confirm-default gate), never a silent fallback. The operation edge maps this to a 400. */
+export class MissingBaseBranchError extends Error {
+  constructor() {
+    super("base branch is required (blank/absent base branches are rejected)");
+    this.name = "MissingBaseBranchError";
+  }
+}
+
+/** Conservative allowlist gate for a base-branch name. Stricter than `git check-ref-format` on
+ * purpose: only `[A-Za-z0-9._/-]`, no leading `/`/`.`/`-` (a leading dash reads as a CLI flag),
+ * no trailing `/`/`.`, no `..`/`//`, no empty or `.lock`-suffixed path component, bounded length.
+ * This rejects whitespace, shell metacharacters, command substitution, and newlines outright. */
+export function isPlausibleBranchName(s: string): boolean {
+  if (s.length === 0 || s.length > 255) return false;
+  if (!/^[A-Za-z0-9._/-]+$/.test(s)) return false;
+  if (/^[/.-]/.test(s) || /[/.]$/.test(s)) return false;
+  if (s.includes("..") || s.includes("//")) return false;
+  return s.split("/").every((seg) => seg.length > 0 && !seg.startsWith(".") && !seg.endsWith(".lock"));
+}
+
+/** Normalise a caller-supplied base branch: trim, then require it. A blank/absent value is rejected
+ * (`MissingBaseBranchError`) — ADR 0003 removed the implicit default-branch fallback, so every epic
+ * launch must name its base explicitly. A non-blank value that is not a plausible git branch name is
+ * rejected (`InvalidBaseBranchError`) rather than persisted or rendered into the agent prompt. The
+ * operation edge maps both to a 400. Always returns a non-null branch on success. */
+export function normalizeBaseBranch(input: string | null | undefined): string {
+  const s = (input ?? "").trim();
+  if (s.length === 0) throw new MissingBaseBranchError();
+  if (!isPlausibleBranchName(s)) throw new InvalidBaseBranchError(s);
+  return s;
+}

package/app/contracts.ts

@@ -382,11 +382,11 @@ export const WIRE_CONTRACTS = {
   "io.nanobpm.agentTask.repository": {
     category: "wire",
     name: "io.nanobpm.agentTask.repository",
-    owner: "app/service.ts",
+    owner: "app/repoEnvelope.ts",
     semantics:
-      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`) and the c8ctl worker harness consumes to provision an isolated clone on the PR head branch. Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `commitSha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
+      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create` (the deterministic `feat/<task.id>`, emitted only for a single-task feature run; the epic seed AND the delivery-graph run-root seed omit it so each fan-out slice's agent branches per node/MI child). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `commitSha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
     shape:
-      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string, commitSha?: string }',
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string, commitSha?: string, branch?: { create: string } }',
   },
   "epicSet.submit": {
     category: "wire",

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 } & DeliveryRunTimeouts = {},
+  options: { runKey?: string | null; title?: string | null; repository?: string | null; baseBranch?: string | null } & DeliveryRunTimeouts = {},
 ): Promise<DispatchDeliveryGraphResult> {
   const validationErrors = validateDeliveryGraph(graph);
   if (validationErrors.length > 0) {
@@ -140,6 +140,11 @@ 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).
+      repository: options.repository,
+      baseBranch: options.baseBranch,
     });
   } catch (err) {
     await markClaimFailed();

package/app/deliveryRunner.test.ts

@@ -363,6 +363,62 @@ 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 };
+}
+
+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" });
+  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);
+});
+
+test("runDeliveryGraph emits NO envelope when repository/baseBranch are absent — repo-less graphs unchanged (#686)", async () => {
+  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)}`);
+  }
+});
+
+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("the canonical `agent → converge-merge → wait[pr merged]` graph DISPATCHES with a fact-bound wait target (#570)", async () => {
   // Regression for #570: a `wait[pr]` node whose `target` is a fact reference (`open.pr`, the #548
   // late-binding shape the guide documents as canonical) COMPILED+staged but threw at dispatch —

package/app/deliveryRunner.ts

@@ -19,6 +19,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 { isoDuration } from "./reviewWait.ts";
 
 /** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
@@ -52,6 +53,18 @@ 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. */
+  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. */
+  baseBranch?: string | null;
 }
 
 const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
@@ -146,6 +159,8 @@ 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;
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId,
     variables: {
@@ -155,6 +170,20 @@ 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),
     },
   });
   // The engine can yield a numeric key; `DeliveryRunHandle.processInstanceKey` is typed `string` and

package/app/feature.test.ts

@@ -131,6 +131,36 @@ test("startFeature: seeds the single task slice + base-branch brief onto the ins
   assertEquals(v.status, null);
 });
 
+test("startFeature: seeds the pre-PR repository envelope so the harness provisions an isolated clone (#684)", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-684" });
+    },
+  } as any;
+  await startFeature(
+    memData({ feature_runs: { rows: [], key: "feature_key" } }),
+    engine,
+    PARSED,
+    "epic/x",
+    true,
+    false,
+  );
+  // Without the envelope the c8ctl harness leaves cwd undefined and the agent mutates the worker's
+  // shared launch dir; with it, the harness clones a throwaway workspace. The implementation path is
+  // PRE-PR, so it checks out the BASE branch (`ref`) and the harness cuts the deterministic
+  // `feat/<task.id>` feature branch off it (`branch.create`).
+  const repo = (captured.variables as Record<string, any>)["io.nanobpm.agentTask"].repository;
+  assertEquals(repo.url, "https://github.com/owner/repo.git");
+  assertEquals(repo.ref, "epic/x");
+  assertEquals(repo.branch.create, "feat/issue-42");
+  assertEquals(repo.branch.create, `feat/${featureTaskId(PARSED.number)}`);
+  // The blobless/single-branch monorepo shaping rides along, exactly like the PR-based envelope.
+  assertEquals(repo.singleBranch, true);
+  assertEquals(repo.filter, "blob:none");
+});
+
 test("startFeature: custom instructions ride the instance as a variable (trimmed)", async () => {
   let captured: any = null;
   const engine = {

package/app/feature.ts

@@ -19,6 +19,7 @@ import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcr
 import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
 import type { ReadinessProbe } from "./readiness.ts";
+import { repoEnvelopeVars } 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
@@ -336,6 +337,10 @@ export async function startFeature(
       updated_at: ts,
     });
   }
+  const taskId = featureTaskId(parsed.number);
+  // Pre-PR feature branch (issue #684): the deterministic `feat/<task.id>` the harness creates off the
+  // base for the implementation agent (the agent-guide's `feat/*` convention), matching `task.id`.
+  const prePrBranch = `feat/${taskId}`;
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: FEATURE_PROCESS_ID,
     variables: {
@@ -349,7 +354,7 @@ export async function startFeature(
       // (resources/prompts/feature.md); `task.id` fixes its deterministic branch `feat/<task.id>` across a
       // resume. Unlike an epic, there is no planner — the whole issue IS the slice.
       task: {
-        id: featureTaskId(parsed.number),
+        id: taskId,
         title: parsed.planKey,
         prompt:
           `Implement the GitHub issue ${parsed.planKey} end to end. Read it in full first ` +
@@ -406,6 +411,15 @@ export async function startFeature(
       // links this feature run to its agent transcript in Nano Explorer (feature.bpmn `implement-task`
       // ioMapping). Read down into the job via `=transcriptUrlBase`.
       [TRANSCRIPT_URL_BASE_VAR]: transcriptUrlBaseFor(),
+      // Host-git provisioning (c8ctl, issue #684): deliver the repository envelope so the
+      // `senior:feature` implementation agent gets an ISOLATED throwaway clone instead of inheriting
+      // the worker's launch dir (which, with several copilot workers on one host, means concurrent
+      // 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),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/plan.test.ts

@@ -241,6 +241,15 @@ test("startPlan pins the base branch: persisted on the row + seeded as baseBranc
   // Process variables the implement-task consumes.
   assertEquals(seen.baseBranch, "epic/agent-protocol");
   assertEquals(seen.baseBranchBrief.includes("gh pr create --base epic/agent-protocol"), true);
+  // Host-git provisioning (#684): the whole-epic repository envelope so each slice's implementation
+  // agent gets an isolated clone. The epic seed checks out the BASE branch (`ref`) — each slice's
+  // `feat/<task.id>` branch differs per MI child, so NO `branch.create` here (the agent branches).
+  const repo = seen["io.nanobpm.agentTask"].repository;
+  assertEquals(repo.url, "https://github.com/owner/repo.git");
+  assertEquals(repo.ref, "epic/agent-protocol");
+  assertEquals("branch" in repo, false);
+  assertEquals(repo.singleBranch, true);
+  assertEquals(repo.filter, "blob:none");
 });
 
 test("startPlan renders baseBranchBrief unconditionally now that base is required", async () => {

package/app/plan.ts

@@ -10,6 +10,12 @@
 // the process. Data access goes through the record gateway (`data.table`), never
 // hand-written SQL — matching app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import {
+  InvalidBaseBranchError,
+  isPlausibleBranchName,
+  MissingBaseBranchError,
+  normalizeBaseBranch,
+} from "./baseBranch.ts";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
 import { capsWaitTimeout, DEFAULT_CAPS_WAIT_TIMEOUT } from "./capsWait.ts";
 import { EPIC_PHASE } from "./epicPhase.ts";
@@ -24,6 +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 { clearTaskDeltas } from "./taskDelta.ts";
 
 /** The BPMN process this module drives (resources/processes/plan-fanout.bpmn). */
@@ -485,52 +492,11 @@ export function parseIssue(input: string): ParsedIssue | null {
   return null;
 }
 
-/** Raised when a caller supplies a `baseBranch` that isn't a plausible git branch name. The
- * value is interpolated into the authoritative implementer prompt (which carries `git`/`gh`
- * shell snippets and inline-code Markdown), so a non-ref value could break the rendered
- * instructions or smuggle in a command/prompt fragment — reject it at the edge instead. */
-export class InvalidBaseBranchError extends Error {
-  readonly value: string;
-  constructor(value: string) {
-    super(`invalid base branch name: ${JSON.stringify(value)}`);
-    this.name = "InvalidBaseBranchError";
-    this.value = value;
-  }
-}
-
-/** Raised when a caller supplies a blank/absent `baseBranch`. Every epic launch must name its base
- * branch explicitly (ADR 0003): "land on the default branch" is a conscious, named, confirmed choice
- * (the confirm-default gate), never a silent fallback. The operation edge maps this to a 400. */
-export class MissingBaseBranchError extends Error {
-  constructor() {
-    super("base branch is required (blank/absent base branches are rejected)");
-    this.name = "MissingBaseBranchError";
-  }
-}
-
-/** Conservative allowlist gate for a base-branch name. Stricter than `git check-ref-format` on
- * purpose: only `[A-Za-z0-9._/-]`, no leading `/`/`.`/`-` (a leading dash reads as a CLI flag),
- * no trailing `/`/`.`, no `..`/`//`, no empty or `.lock`-suffixed path component, bounded length.
- * This rejects whitespace, shell metacharacters, command substitution, and newlines outright. */
-function isPlausibleBranchName(s: string): boolean {
-  if (s.length === 0 || s.length > 255) return false;
-  if (!/^[A-Za-z0-9._/-]+$/.test(s)) return false;
-  if (/^[/.-]/.test(s) || /[/.]$/.test(s)) return false;
-  if (s.includes("..") || s.includes("//")) return false;
-  return s.split("/").every((seg) => seg.length > 0 && !seg.startsWith(".") && !seg.endsWith(".lock"));
-}
-
-/** Normalise a caller-supplied base branch: trim, then require it. A blank/absent value is rejected
- * (`MissingBaseBranchError`) — ADR 0003 removed the implicit default-branch fallback, so every epic
- * launch must name its base explicitly. A non-blank value that is not a plausible git branch name is
- * rejected (`InvalidBaseBranchError`) rather than persisted or rendered into the agent prompt. The
- * operation edge maps both to a 400. Always returns a non-null branch on success. */
-export function normalizeBaseBranch(input: string | null | undefined): string {
-  const s = (input ?? "").trim();
-  if (s.length === 0) throw new MissingBaseBranchError();
-  if (!isPlausibleBranchName(s)) throw new InvalidBaseBranchError(s);
-  return s;
-}
+/** The base-branch validation gate lives in the side-effect-free leaf `./baseBranch.ts` so an API
+ * door (e.g. `operations/dispatchDeliveryGraph.ts`) can reuse it without importing this heavy module
+ * and its import-time env seeding. Re-exported here so existing importers keep resolving through
+ * `plan.ts` — one implementation (derivation over duplication), just hoisted below the heavy module. */
+export { InvalidBaseBranchError, isPlausibleBranchName, MissingBaseBranchError, normalizeBaseBranch };
 
 /** The per-instance brief appended to an implementer agent's prompt when the plan pins a base
  * branch. It is authoritative over the static "branch off the default branch" wording in
@@ -1074,6 +1040,16 @@ export async function startPlan(
       // instance. A ROOT never runs the preflight, so its `gateKey` stays `null`, unused.
       gateKey: probes ? `preflight:${parsed.planKey}` : null,
       resolvedArtifacts: null,
+      // Host-git provisioning (c8ctl, issue #684): deliver the repository envelope so each epic slice's
+      // `senior:feature` implementation agent (plan-fanout's per-wave `implement-cell`) 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, violating the durable-resume
+      // design. This is the whole-epic seed, so it carries `ref = base` (the epic integration branch)
+      // 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),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/repoEnvelope.ts

@@ -0,0 +1,102 @@
+// nano-workforce — the repository-provisioning envelope (`io.nanobpm.agentTask.repository`).
+//
+// The ONE canonical builder of the agent-task repository envelope the c8ctl nano worker harness
+// consumes to provision an ISOLATED clone for an agent job — instead of the agent inheriting
+// whatever directory the worker was launched from (which, with several copilot workers on one host,
+// means concurrent jobs share — and clobber — one checkout; see issue #684). It lives in its own
+// module (not service.ts) so BOTH the PR-based dispatch (`service.ts`: review-round / fix-ci /
+// rebase) and the PRE-PR implementation dispatch (`feature.ts`: `startFeature`; `plan.ts`:
+// `startPlan` → the epic's `implement-cell`) derive from this single implementation without a
+// `plan.ts ↔ service.ts` import cycle (AGENTS.md "derivation over duplication — no drift surfaces").
+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";
+
+/** 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
+ * only happened to be a usable checkout for repos already present locally). `ref` is the branch the
+ * harness checks out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or —
+ * on the PRE-PR implementation path (`branchCreate` set) — the BASE branch, off which the harness
+ * cuts the new feature branch. When `ref` is unresolved we emit nothing (no `repository.url`) so the
+ * harness falls back to the legacy launch-dir behavior rather than silently cloning the repo's
+ * default branch. The static `task.prompt` header on the service task deep-merges with this over the
+ * same namespace.
+ *
+ * The clone is requested **branch-scoped and blobless** (`singleBranch: true` + `filter:
+ * "blob:none"`) so large monorepos (e.g. `camunda/camunda`, ~1.16 GB) provision within the c8ctl
+ * clone timeout instead of full-cloning the whole history (issue #287). `blob:none` is a *blobless*
+ * partial clone (trees are still fetched up-front — a *treeless* clone would be `--filter=tree:0`); it
+ * keeps the full *commit graph* (so `git merge-base` / the review 3-dot diff stays correct) while
+ * fetching file blobs lazily — small upfront, correct diffs. `--depth 1` is deliberately NOT used:
+ * it would drop the merge-base and break `git diff origin/<base>...HEAD`. When the PR base branch
+ * is known we also emit `baseRef` so the harness fetches the base tip alongside the head, keeping
+ * that base reachable for the diff.
+ *
+ * World-restore (issue #324, ADR 0062 Slice 4/5): when a PR already has a durable push-checkpoint,
+ * `commitSha` is emitted so a REPLACEMENT activation (a fresh worktree after a lease loss)
+ * reconstructs the working tree to the EXACT pushed SHA — the inversion of the round's outbound
+ * `git push` into an inbound `git fetch && git checkout <sha>` — rather than to a branch tip that may
+ * have moved. Omitted (no key) when the PR has no checkpoint yet, so a first activation clones the
+ * head branch normally.
+ *
+ * Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
+ * `implement-cell`) dispatches its agent BEFORE any PR exists, so it passes `ref = base` and a
+ * `branchCreate` naming the deterministic `feat/<task.id>` feature branch the harness cuts off that
+ * base itself (the agent-guide's `feat/*` convention) — instead of the agent branching by hand — so
+ * the isolated clone lands on the right branch deterministically across a resume. `branchCreate` is
+ * omitted on the PR-based paths, which check out an existing head. */
+export function repoEnvelopeVars(
+  repo: string,
+  ref: string | null,
+  baseRef: string | null = null,
+  commitSha: string | null = null,
+  branchCreate: string | null = null,
+): Record<string, unknown> {
+  if (!ref) return {};
+  // Defence in depth: every current caller derives `repo` from parsePr/parseIssue (regex-bounded to
+  // `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 {};
+  return {
+    [AGENT_TASK_NS]: {
+      repository: {
+        provider: "github",
+        url: `https://github.com/${repo}.git`,
+        ref,
+        // Branch-scoped, blobless partial clone (issue #287): fetch only the head branch with lazy
+        // blobs so large monorepos provision within the clone timeout. Single-branch + blob:none
+        // (not --depth 1) preserves the commit graph so the review's `git diff origin/<base>...HEAD`
+        // has a valid merge-base. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).
+        singleBranch: true,
+        filter: "blob:none",
+        // The base branch this PR targets — emitted so the harness fetches its tip alongside the
+        // single-branch head, keeping `origin/<base>` reachable for the diff. Omitted when unknown.
+        ...(baseRef ? { baseRef } : {}),
+        // World-restore (issue #324): the last pushed SHA a replacement activation reconstructs the
+        // working tree to (inverting the round's push into a fetch+checkout). Only emitted when it is
+        // a well-formed 40-hex commit SHA: `commitSha` is forwarded to the harness as an EXACT
+        // checkout target, so a non-SHA ref or a whitespace-tainted value could reconstruct to an
+        // unintended ref (a moved branch tip) or fail provisioning. A malformed value degrades to
+        // omission — the harness then clones the head branch tip, the pre-#324 behaviour. Omitted too
+        // when the PR has no durable push-checkpoint yet.
+        ...(isCommitSha(commitSha) ? { commitSha } : {}),
+        // Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
+        // implement-cell) dispatches its agent BEFORE any PR exists, so `ref` is the BASE branch, not a
+        // head. `branchCreate` asks the harness to cut the deterministic `feat/<task.id>` feature branch
+        // off that base itself (the agent-guide's `feat/*` convention) instead of the agent branching by
+        // hand — making the isolated clone land on the right branch deterministically across a resume.
+        // Omitted (no key) on the PR-based paths (review/fix-ci/rebase), which check out an existing head.
+        ...(typeof branchCreate === "string" && branchCreate.trim() !== ""
+          ? { branch: { create: branchCreate.trim() } }
+          : {}),
+      },
+    },
+  };
+}

package/app/service.test.ts

@@ -550,6 +550,34 @@ test("repoEnvelopeVars emits commitSha only for a well-formed 40-hex SHA (world-
   assertEquals("commitSha" in none, false);
 });
 
+// Pre-PR provisioning (issue #684): the implementation path has no head branch yet, so it passes
+// `ref = base` + a `branchCreate` so the harness clones the base and cuts the deterministic
+// `feat/<task.id>` feature branch off it. `branch.create` is emitted only for a non-blank branch and
+// is absent on the PR-based paths (which check out an existing head).
+test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#684)", () => {
+  const repo = (repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7") as any)["io.nanobpm.agentTask"]
+    .repository;
+  assertEquals(repo.ref, "main", "the pre-PR envelope checks out the BASE branch as its ref");
+  assertEquals(repo.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch off the base");
+  // Still branch-scoped and blobless like the PR-based envelope.
+  assertEquals(repo.singleBranch, true);
+  assertEquals(repo.filter, "blob:none");
+  // A whitespace-tainted branch is trimmed; a blank/absent one omits the `branch` key entirely so the
+  // PR-based paths (and any caller that doesn't pre-create a branch) are unaffected.
+  assertEquals(
+    (repoEnvelopeVars("owner/repo", "main", null, null, "  feat/issue-9  ") as any)["io.nanobpm.agentTask"].repository
+      .branch.create,
+    "feat/issue-9",
+  );
+  for (const blank of [null, undefined, "", "   "]) {
+    const r = (repoEnvelopeVars("owner/repo", "main", null, null, blank as any) as any)["io.nanobpm.agentTask"]
+      .repository;
+    assertEquals("branch" in r, false, `expected no branch key for ${JSON.stringify(blank)}`);
+  }
+  // The default (4-arg) PR-based call never emits a branch.create.
+  assertEquals("branch" in (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"].repository, false);
+});
+
 // Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5): `worldRestoreSha` — the seam
 // `submitPr`/`startMerge` thread into `repoEnvelopeVars` — hands the harness the last push-checkpoint
 // ONLY when the enrolled fleet advertises `durable-resume`. With no participant it degrades to null,

package/app/service.ts

@@ -85,6 +85,12 @@ import {
   readinessPollEvery,
   readinessTimeout,
 } from "./readiness.ts";
+// The repository-provisioning envelope builder lives in its own module (app/repoEnvelope.ts) so the
+// PRE-PR implementation dispatch (`feature.ts`/`plan.ts`) can reuse the ONE canonical implementation
+// without a `plan.ts ↔ service.ts` import cycle (issue #684). Imported for the PR-based callers
+// (submitPr/startMerge) and re-exported below so the long-standing `import { repoEnvelopeVars } from
+// "./service.ts"` call sites (and its tests) keep resolving.
+import { repoEnvelopeVars } from "./repoEnvelope.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
@@ -112,7 +118,7 @@ import {
 } from "./userTasks.ts";
 import { deriveWaitGate } from "./waitGate.ts";
 import { waveMergeTargets } from "./waves.ts";
-import { isCommitSha, WorldStore } from "./world/index.ts";
+import { WorldStore } from "./world/index.ts";
 
 /** The BPMN process that drives review convergence (`resources/processes/convergence-loop.bpmn`). */
 export const PROCESS_ID = "convergence-loop";
@@ -413,77 +419,10 @@ async function registerDependencies(data: DataLayer, prKey: string, depKeys: str
   }
 }
 
-/** 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";
-
-/** Build the repository slice of the agent-task envelope for a PR-based agent job (review-round,
- * fix-ci, rebase). Delivered as a *process variable* under the reserved `io.nanobpm.agentTask`
- * key so the harness provisions an isolated clone checked out on the PR's head branch — instead of
- * the agent inheriting whatever directory the worker was launched from (which only happened to be
- * a usable checkout for repos already present locally). `ref` MUST be the PR head branch; when it
- * is unresolved we emit nothing (no `repository.url`) so the harness falls back to the legacy
- * launch-dir behavior rather than silently cloning the repo's default branch. The static
- * `task.prompt` header on the service task deep-merges with this over the same namespace.
- *
- * The clone is requested **branch-scoped and blobless** (`singleBranch: true` + `filter:
- * "blob:none"`) so large monorepos (e.g. `camunda/camunda`, ~1.16 GB) provision within the c8ctl
- * clone timeout instead of full-cloning the whole history (issue #287). `blob:none` is a *blobless*
- * partial clone (trees are still fetched up-front — a *treeless* clone would be `--filter=tree:0`); it
- * keeps the full *commit graph* (so `git merge-base` / the review 3-dot diff stays correct) while
- * fetching file blobs lazily — small upfront, correct diffs. `--depth 1` is deliberately NOT used:
- * it would drop the merge-base and break `git diff origin/<base>...HEAD`. When the PR base branch
- * is known we also emit `baseRef` so the harness fetches the base tip alongside the head, keeping
- * that base reachable for the diff.
- *
- * World-restore (issue #324, ADR 0062 Slice 4/5): when a PR already has a durable push-checkpoint,
- * `commitSha` is emitted so a REPLACEMENT activation (a fresh worktree after a lease loss)
- * reconstructs the working tree to the EXACT pushed SHA — the inversion of the round's outbound
- * `git push` into an inbound `git fetch && git checkout <sha>` — rather than to a branch tip that may
- * have moved. Omitted (no key) when the PR has no checkpoint yet, so a first activation clones the
- * head branch normally. */
-export function repoEnvelopeVars(
-  repo: string,
-  ref: string | null,
-  baseRef: string | null = null,
-  commitSha: string | null = null,
-): Record<string, unknown> {
-  if (!ref) return {};
-  // Defence in depth: every current caller derives `repo` from parsePr/parseIssue (regex-bounded to
-  // `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 {};
-  return {
-    [AGENT_TASK_NS]: {
-      repository: {
-        provider: "github",
-        url: `https://github.com/${repo}.git`,
-        ref,
-        // Branch-scoped, blobless partial clone (issue #287): fetch only the head branch with lazy
-        // blobs so large monorepos provision within the clone timeout. Single-branch + blob:none
-        // (not --depth 1) preserves the commit graph so the review's `git diff origin/<base>...HEAD`
-        // has a valid merge-base. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).
-        singleBranch: true,
-        filter: "blob:none",
-        // The base branch this PR targets — emitted so the harness fetches its tip alongside the
-        // single-branch head, keeping `origin/<base>` reachable for the diff. Omitted when unknown.
-        ...(baseRef ? { baseRef } : {}),
-        // World-restore (issue #324): the last pushed SHA a replacement activation reconstructs the
-        // working tree to (inverting the round's push into a fetch+checkout). Only emitted when it is
-        // a well-formed 40-hex commit SHA: `commitSha` is forwarded to the harness as an EXACT
-        // checkout target, so a non-SHA ref or a whitespace-tainted value could reconstruct to an
-        // unintended ref (a moved branch tip) or fail provisioning. A malformed value degrades to
-        // omission — the harness then clones the head branch tip, the pre-#324 behaviour. Omitted too
-        // when the PR has no durable push-checkpoint yet.
-        ...(isCommitSha(commitSha) ? { commitSha } : {}),
-      },
-    },
-  };
-}
+// The repository-provisioning envelope builder now lives in its own module (app/repoEnvelope.ts);
+// re-export it here so the long-standing `import { repoEnvelopeVars } from "./service.ts"` call
+// sites (and its tests) keep resolving (issue #684).
+export { repoEnvelopeVars };
 
 /** The last durable push-checkpoint SHA for a PR (issue #324, ADR 0062 Slice 4/5), or `null` when it
  * has none yet. Threaded into `repoEnvelopeVars` so a replacement activation reconstructs the exact

package/e2e/feature-run.e2e.ts

@@ -123,8 +123,18 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
   }
 
   test("raise-only: an opened PR ends the run at `opened`, taking the raise-only branch", async () => {
+    // Host-git provisioning (#684): capture the repository envelope the `senior:feature` agent job
+    // carries — proof the implement-cell agent gets an ISOLATED clone (base branch + a harness-cut
+    // `feat/<task.id>`) instead of inheriting the worker's launch dir. It rides the process variable
+    // all the way down through feature.bpmn's `implement` callActivity into the cell's agent job.
+    let agentRepo: any = null;
     await withApp(
-      { "senior:feature": () => ({ status: "opened", pr: "owner/repo#101", summary: "built it" }) },
+      {
+        "senior:feature": (job) => {
+          agentRepo = (job.variables as Record<string, any>)["io.nanobpm.agentTask"]?.repository ?? null;
+          return { status: "opened", pr: "owner/repo#101", summary: "built it" };
+        },
+      },
       { baseBranch: "epic/e2e" },
       async ({ app, featureKey }) => {
         const flows = takenFlows(app);
@@ -134,6 +144,11 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         );
         assert.ok(!flows.includes("gw-converge->converge"), "the converge hand-off branch was NOT taken");
 
+        assert.ok(agentRepo, "the senior:feature job carried the io.nanobpm.agentTask repository envelope");
+        assert.equal(agentRepo.url, "https://github.com/owner/repo.git", "the harness clones the target repo");
+        assert.equal(agentRepo.ref, "epic/e2e", "a PRE-PR job checks out the BASE branch, not a head");
+        assert.equal(agentRepo.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch");
+
         const run = await featureRow(app, featureKey);
         assert.equal(run.status, "opened", "the run settled at opened");
         assert.equal(run.pr_key, "owner/repo#101", "the raised PR key was recorded");

package/e2e/plan-fanout.e2e.ts

@@ -121,6 +121,34 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
   const singleTaskPlan: Stub = () => ({ tasks: [{ id: "t1", title: "T1", prompt: "do t1" }] });
   const approveReview: Stub = () => ({ approved: true, findings: "" });
 
+  test("host-git provisioning: each slice's implement-cell agent job carries the repository envelope (#684)", async () => {
+    // The whole-epic seed emits `io.nanobpm.agentTask.repository` so every slice's `senior:feature`
+    // agent gets an ISOLATED clone instead of clobbering the worker's launch dir. The process variable
+    // rides down through the wave subprocess + `implement-cell-call` callActivity into each agent job.
+    // The epic seed carries the BASE branch as `ref` but NO `branch.create` — each slice's
+    // `feat/<task.id>` differs per MI child, so the agent cuts its own branch inside the clone.
+    let agentRepo: any = null;
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": (job) => {
+          agentRepo = (job.variables as Record<string, any>)["io.nanobpm.agentTask"]?.repository ?? null;
+          return { status: "blocked", summary: "n/a" };
+        },
+      },
+      async ({ app }) => {
+        await app.settle();
+        assert.ok(agentRepo, "the epic slice's senior:feature job carried the io.nanobpm.agentTask envelope");
+        assert.equal(agentRepo.url, "https://github.com/owner/repo.git", "the harness clones the target repo");
+        assert.equal(agentRepo.ref, "epic/e2e", "the epic seed checks out the BASE (integration) branch");
+        assert.equal("branch" in agentRepo, false, "the epic seed omits branch.create — the agent branches per slice");
+        assert.equal(agentRepo.singleBranch, true, "the blobless/single-branch monorepo shaping rides along");
+        assert.equal(agentRepo.filter, "blob:none");
+      },
+    );
+  });
+
   test("task escalation: a native userTask parks the child; answering routes back to implement-task", async () => {
     let featureCalls = 0;
     await withApp(

package/openapi.yaml

@@ -2090,6 +2090,29 @@ components:
           description: >-
             OPTIONAL run-level ISO-8601 SLA for `human` nodes (#505) before they record an `escalated`
             outcome. Absent → the `P1D` default. An invalid duration is rejected at submit.
+        repository:
+          type: string
+          maxLength: 255
+          pattern: '^[A-Za-z0-9-]+/(?!.*\.[Gg][Ii][Tt]$)[A-Za-z0-9._-]+$'
+          description: >-
+            OPTIONAL `owner/repo` the run's `agent` nodes implement against (#684/#686). When supplied
+            together with `baseBranch`, the runner seeds the canonical `io.nanobpm.agentTask.repository`
+            provisioning envelope (`repoEnvelopeVars`) as a run-root process variable so every agent
+            node's servicing `senior:*` job gets an ISOLATED throwaway clone instead of inheriting the
+            worker's launch dir. Absent → no envelope (legacy launch-dir behaviour, unchanged). A value
+            that is not exactly `owner/repo` is rejected at submit.
+        baseBranch:
+          type: string
+          maxLength: 255
+          pattern: '^(?![/.-])(?!.*[/.]$)(?!.*\.\.)(?!.*//)(?!.*/\.)(?!.*\.lock(?:/|$))[A-Za-z0-9._/-]+$'
+          description: >-
+            OPTIONAL base branch the run's `agent` nodes branch off (#684/#686) — the `ref` the harness
+            checks out in the isolated clone (the PRE-PR shape: each agent cuts its own `feat/<node.id>`
+            branch off this base). Only consulted when `repository` is also set; absent → no envelope. A
+            value that is not a plausible git branch name (whitespace, shell metacharacters, a leading
+            `-`, `..`/`//`, a path segment starting with `.` or ending in `.lock`, etc.) is rejected at
+            submit. This pattern mirrors the authoritative server-side gate (`isPlausibleBranchName`,
+            app/baseBranch.ts) so the documented contract and the door agree.
     DeliveryGraphDismissRequest:
       description: >-
         The OPERATOR dismiss request (#520). The cockpit's staged-proposals grid posts the content

package/operations/dispatchDeliveryGraph.test.ts

@@ -247,4 +247,66 @@ describe("dispatchDeliveryGraph — operator dispatch by staged-proposal digest"
     assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
     assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "dispatched");
   });
+
+  test("a malformed `repository` is rejected at submit → 400, nothing launched (#684/#686)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    // Not an `owner/repo` reference — refused at submit (by the edge `pattern` or the door's own guard),
+    // rather than silently dropped into a bogus clone URL. Nothing launches; the proposal stays staged.
+    const res = await api.call<{ ok?: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, repository: "not a repo!", baseBranch: "main" },
+    });
+    assert.equal(res.status, 400);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "staged");
+  });
+
+  test("a malformed `baseBranch` is rejected at submit → 400, nothing launched (#684/#686)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    // Not a plausible git branch name (a leading dash reads as a CLI flag / shell metacharacters) — the
+    // door's conservative allowlist refuses it at submit rather than seeding an invalid-ref envelope.
+    const res = await api.call<{ ok?: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, repository: "owner/repo", baseBranch: "-rf; rm main" },
+    });
+    assert.equal(res.status, 400);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "staged");
+  });
+
+  test("a `.lock`-suffixed `baseBranch` segment is rejected at submit → 400, nothing launched (#684/#686)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    // A path segment ending in `.lock` (or one starting with `.`) is a valid-looking ref the loose
+    // charset would admit but `isPlausibleBranchName` rejects — the door must refuse it, matching the
+    // (now tightened) OpenAPI `baseBranch` pattern rather than seeding an invalid-ref envelope.
+    const res = await api.call<{ ok?: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, repository: "owner/repo", baseBranch: "feat/x.lock" },
+    });
+    assert.equal(res.status, 400);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "staged");
+  });
+
+  test("a valid repository + baseBranch dispatches the run for isolated provisioning → 202 running (#684/#686)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    const res = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, repository: "owner/repo", baseBranch: "main" },
+    });
+    assert.equal(res.status, 202);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.status, "running");
+    await app.settle();
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "dispatched");
+  });
 });

package/operations/dispatchDeliveryGraph.ts

@@ -10,6 +10,7 @@
 // re-dispatch of an already-running run short-circuits with `alreadyRunning`. An unknown / expired /
 // superseded / already-dispatched digest is a clean 400.
 
+import { isPlausibleBranchName } from "../app/baseBranch.ts";
 import { dispatchDeliveryGraphRun } from "../app/deliveryGraphDispatch.ts";
 import { getStagedProposal, markProposalDispatched, markProposalExpired } from "../app/deliveryGraphProposals.ts";
 import { isValidIsoDuration } from "../app/reviewWait.ts";
@@ -75,6 +76,38 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
     if (parsed.value !== undefined) timeouts[field] = parsed.value;
   }
 
+  // Host-git provisioning override (#684/#686) — the OPTIONAL `owner/repo` + base branch the run's
+  // `agent` nodes implement against. When both are present the runner seeds the canonical
+  // `io.nanobpm.agentTask.repository` isolation envelope (`repoEnvelopeVars`) onto every agent cell's
+  // job so it provisions a throwaway clone instead of mutating the worker's launch dir. `repository` is
+  // shape-validated here (mirrors `repoEnvelopeVars`' own `owner/repo` allowlist) so a malformed value
+  // is a clean 400 rather than a silently-dropped envelope; both absent → no envelope (legacy behaviour).
+  const repoRaw = body && typeof body === "object" && "repository" in body && typeof body.repository === "string" ? body.repository.trim() : "";
+  let repository: string | undefined;
+  if (repoRaw !== "") {
+    if (repoRaw.length > 255 || !/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/.test(repoRaw) || /\.git$/i.test(repoRaw)) {
+      const shown = truncateForEcho(repoRaw);
+      app.log.warn("dispatch-delivery-graph rejected: invalid repository", { value: shown });
+      return { status: 400, body: { ok: false, error: `\`repository\` must be an \`owner/repo\` reference; got \`${shown}\`` } };
+    }
+    repository = repoRaw;
+  }
+  const baseRaw = body && typeof body === "object" && "baseBranch" in body && typeof body.baseBranch === "string" ? body.baseBranch.trim() : "";
+  let baseBranch: string | undefined;
+  if (baseRaw !== "") {
+    // `baseBranch` becomes the isolation envelope's `ref` — a real Git ref the harness checks out and
+    // branches off. Gate it with the canonical conservative branch-name allowlist (`app/plan.ts`,
+    // shared with the epic/feature launch paths) so whitespace, shell metacharacters, newlines, a
+    // leading `-`, `..`/`//`, etc. are a clean 400 rather than an invalid-ref/argument-parsing edge
+    // case in a downstream git invocation.
+    if (baseRaw.length > 255 || !isPlausibleBranchName(baseRaw)) {
+      const shown = truncateForEcho(baseRaw);
+      app.log.warn("dispatch-delivery-graph rejected: invalid baseBranch", { value: shown });
+      return { status: 400, body: { ok: false, error: `\`baseBranch\` must be a plausible git branch name; got \`${shown}\`` } };
+    }
+    baseBranch = baseRaw;
+  }
+
   // Load the live staged proposal for this digest — refuses an unknown/expired/superseded/already-
   // dispatched digest cleanly (no run is launched).
   const proposal = await getStagedProposal(app.data, digest);
@@ -98,7 +131,7 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
     return { status: 400, body: { ok: false, error: `staged proposal ${digest} is corrupt: ${err instanceof Error ? err.message : String(err)}` } };
   }
 
-  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title, ...timeouts });
+  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title, repository, baseBranch, ...timeouts });
   if (!dispatched.ok) {
     app.log.warn("dispatch-delivery-graph refused: compile", { digest, errors: dispatched.errors.length });
     const outBody: DeliveryGraphTextResult = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.171.5",
+  "version": "0.171.7",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",