@nanobpm/nano-workforce 0.171.6 → 0.171.7

package/CHANGELOG.md

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

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

@@ -384,7 +384,7 @@ export const WIRE_CONTRACTS = {
     name: "io.nanobpm.agentTask.repository",
     owner: "app/repoEnvelope.ts",
     semantics:
-      "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 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 omits it so each slice's agent branches per 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).",
+      "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, branch?: { create: string } }',
   },

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/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";
@@ -486,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

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.6",
+  "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",