@nanobpm/nano-workforce 0.171.6 → 0.171.8

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.171.8](https://github.com/nanobpm/nano-workforce/compare/v0.171.7...v0.171.8) (2026-09-01)
+
+### Bug Fixes
+
+* **agentic:** release job⇄worker correlation on terminal lifecycle event ([#688](https://github.com/nanobpm/nano-workforce/issues/688)) ([58dde6c](https://github.com/nanobpm/nano-workforce/commit/58dde6cf1c91f75828c8a38de52fef9409e3484c)), closes [#661](https://github.com/nanobpm/nano-workforce/issues/661) [#544](https://github.com/nanobpm/nano-workforce/issues/544) [#661](https://github.com/nanobpm/nano-workforce/issues/661)
+
+## [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/agentic/families/relay.family.test.ts

@@ -16,16 +16,19 @@ import { fileURLToPath } from "node:url";
 import { ConnectionRegistry } from "@nanobpm/agentic/channel";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY } from "@nanobpm/agentic/relay";
-import { type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
-import { assert, assertEquals } from "#test-assert";
+import { encodeTranscriptEvent, type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
+import { assert, assertEquals, assertThrows } from "#test-assert";
 import { noopLog } from "../../../test/log.ts";
 import { CorrelationRegistry, jobStream } from "../correlation.ts";
 import { AgenticCorrelationStore } from "../correlation-store.ts";
+import { createPresenceStore, PresenceRegistry } from "./presence.family.ts";
 import {
   type CorrelationLink,
   createRelayFamily,
   currentRelayTranscriptService,
+  engineReconcileMs,
   family as relayFamily,
+  guardOverlappingPasses,
   RELAY_FAMILY_NAME,
   RelayTranscriptService,
   sweepIntervalMs,
@@ -542,6 +545,227 @@ test("#544 element-instance enrichment: an unresolved job (never parked) leaves
   service.teardown();
 });
 
+/** A `produce` frame whose chunk is a typed transcript LIFECYCLE event at `phase` (#661). */
+const lifecycle = (stream: string, incarnation: number, phase: "open" | "completed" | "exited"): Frame =>
+  produce(stream, incarnation, encodeTranscriptEvent({ kind: "lifecycle", phase, offset: 0 }));
+
+test("#661 primary release: a terminal lifecycle event clears an idle-but-connected worker's finished job", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  // The worker relays its job's terminal → linked as active.
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "the job is active while it runs");
+  assertEquals(correlation.count(), 1);
+
+  // The job ends: the worker emits the terminal `lifecycle` event on the SAME live connection and then
+  // goes idle — it does NOT disconnect and does NOT take a new job (no supersede). Before this fix that
+  // finished job lingered forever as a phantom active job; now the terminal event releases it.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "completed"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "the finished job is released on the terminal event");
+  assertEquals(correlation.count(), 0, "count() drops — no phantom active job");
+
+  // Assert the RENDERED supply row clears too (not just the registry): the presence snapshot seeds
+  // per-worker jobKeys from the correlation registry, so an idle-but-connected worker shows no job.
+  const store = createPresenceStore(memoryDb());
+  store.ensureSchema();
+  store.register({ instance: "worker-A", connectionId: "prod", identity: "leaf", capability: {} });
+  const presence = new PresenceRegistry(store, () => new Set(["prod"]));
+  const row = presence.snapshot({ jobKeysFor: (i) => correlation.jobKeysFor(i) }).workers[0];
+  assertEquals(row.jobKeys, [], "the supply row shows no active job for the idle worker");
+  assert(row.live, "the worker is still connected — the connection persists across jobs");
+
+  // The terminal event itself is captured in the flushed transcript (release runs AFTER the ring append).
+  const meta = service.transcriptOf(jobStream("k1"));
+  assertEquals(meta?.status, "completed", "the finished job becomes a completed past session");
+  assertEquals(service.reattach(jobStream("k1"), 0)?.entries.length, 2, "the terminal event is part of the transcript");
+  service.teardown();
+});
+
+test("#661 primary release: an `exited` lifecycle also releases; a non-terminal `open` does not", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  // A `phase: "open"` lifecycle is NOT terminal — a genuinely active job must not be cleared.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "open"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "an open lifecycle keeps the active job");
+  assertEquals(correlation.count(), 1);
+
+  // An `exited` lifecycle (a crash/kill the worker still managed to report) IS terminal → released.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "exited"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "an exited lifecycle releases the job");
+  assertEquals(correlation.count(), 0);
+  service.teardown();
+});
+
+test("#661 no-regression: an ordinary (non-lifecycle) chunk never clears a genuinely active job", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  // Ordinary terminal output (raw bytes, not a typed envelope) must NOT be read as a job-end signal.
+  for (let i = 0; i < 5; i++) hub.handler?.(produce(jobStream("k1"), 1, `output ${i}`), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a running job stays active across ordinary output");
+  assertEquals(correlation.count(), 1);
+  assertEquals(service.transcriptOf(jobStream("k1")), undefined, "the live job is not completed");
+  service.teardown();
+});
+
+test("#661 defensive reconcile: an unclean exit (no lifecycle) whose engine job is gone is dropped by the reconcile pass", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // The engine reports job k1 as a live JOB park (element instance ei-1) — until the worker exits
+  // UNCLEANLY (crash/kill): it emits no terminal lifecycle event, keeps no connection to reconcile,
+  // and the engine park is gone → the resolver returns undefined.
+  let parked = true;
+  const resolveElementInstance = (jobKey: string) =>
+    Promise.resolve(parked && jobKey === "k1" ? "ei-1" : undefined);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "the job links while it runs");
+
+  // While the engine still parks the job, the reconcile pass leaves a genuinely active job alone.
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a genuinely active job is NOT cleared by the safety net");
+  assertEquals(correlation.count(), 1);
+
+  // The worker exits uncleanly (no lifecycle event) — its engine park vanishes. The next reconcile
+  // pass drops the stale correlation even though nothing on the wire signalled job end.
+  parked = false;
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "the reconcile pass drops the stale correlation");
+  assertEquals(correlation.count(), 0, "no phantom active job survives an unclean exit");
+  service.teardown();
+});
+
+test("#661 defensive reconcile: a transient engine read failure never falsely releases a job", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // The engine read throws (unavailable) — a transient fault must be treated as "unknown, keep it",
+  // NEVER as "job gone", or a live job would be wrongly cleared on every engine blip.
+  const resolveElementInstance = () => Promise.reject(new Error("engine unavailable"));
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a transient engine failure leaves the job linked");
+  assertEquals(correlation.count(), 1);
+  service.teardown();
+});
+
+test("#661 defensive reconcile: a no-op when no engine resolver is wired", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+
+  // With no element-instance resolver (engine-less host), the safety net cannot query the engine —
+  // it must be an inert no-op, leaving the correlation exactly as the primary path manages it.
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "no resolver → the reconcile pass is inert");
+  service.teardown();
+});
+
+test("#661 engineReconcileMs: defaults, disables on a non-positive/non-finite value, caps at the timer max", () => {
+  assertEquals(engineReconcileMs(), 30_000, "an omitted config uses the default cadence");
+  assertEquals(engineReconcileMs(5_000), 5_000, "a finite positive value is honoured");
+  assertEquals(engineReconcileMs(0), undefined, "zero disables the pass");
+  assertEquals(engineReconcileMs(-1), undefined, "a negative value disables the pass");
+  assertEquals(engineReconcileMs(Number.NaN), undefined, "a non-finite value disables the pass");
+  assertEquals(engineReconcileMs(Number.POSITIVE_INFINITY), undefined, "infinity disables the pass");
+  assertEquals(engineReconcileMs(2 ** 32), 2_147_483_647, "a huge value is capped at the Node timer ceiling");
+  assertEquals(engineReconcileMs(0.5), 1, "a sub-millisecond positive value floors to 1ms, never 0 (no busy setInterval(0))");
+});
+
+test("#661 guardOverlappingPasses: a tick while a pass is in flight is skipped; only one pass runs at a time", async () => {
+  let starts = 0;
+  let active = 0;
+  let maxActive = 0;
+  let release!: () => void;
+  // A pass that blocks until we release it, so we can hold one "in flight" while further ticks fire.
+  const pass = () => {
+    starts++;
+    active++;
+    maxActive = Math.max(maxActive, active);
+    return new Promise<void>((resolve) => {
+      release = () => {
+        active--;
+        resolve();
+      };
+    });
+  };
+  const tick = guardOverlappingPasses(pass);
+
+  tick(); // first tick starts a pass — now in flight
+  tick(); // skipped while the first pass is still pending
+  tick(); // skipped
+  assertEquals(starts, 1, "overlapping ticks are dropped while a pass is in flight");
+  assertEquals(maxActive, 1, "never more than one pass runs concurrently");
+
+  release(); // let the first pass settle
+  await new Promise((r) => setImmediate(r)); // flush the `finally` that clears the in-flight flag
+
+  tick(); // a tick after the previous pass settled starts a fresh pass
+  assertEquals(starts, 2, "a tick after the in-flight pass settles starts a new pass");
+  assertEquals(maxActive, 1, "still only ever one pass at a time");
+  release();
+});
+
+test("#661 guardOverlappingPasses: a pass whose work rejects but is self-caught still re-arms the guard", async () => {
+  // The guard clears its in-flight flag via `.finally`, so it re-arms whether the pass resolves OR
+  // rejects — a rejection does NOT wedge the guard. The real hazard of a rejecting pass is an
+  // *unhandled rejection* (the tick voids the returned promise), which is why the mount wraps
+  // `reconcileEngineCorrelations()` in `.catch`. Here the pass's work rejects but is self-caught
+  // (mirroring that wrapper), so there is no unhandled rejection, and we assert the guard re-arms.
+  let starts = 0;
+  const tick = guardOverlappingPasses(() => {
+    starts++;
+    // Work that rejects but settles its own error — exactly like the mount's `.catch` wrapper.
+    return Promise.reject(new Error("pass work failed")).catch(() => {});
+  });
+  tick();
+  await new Promise((r) => setImmediate(r));
+  tick();
+  await new Promise((r) => setImmediate(r));
+  assertEquals(starts, 2, "a self-caught rejecting pass settles and re-arms the guard for the next tick");
+});
+
+test("#661 guardOverlappingPasses: a pass that throws SYNCHRONOUSLY re-arms the guard (no wedge) and stays loud", () => {
+  // A synchronous throw from `pass` escapes before `.finally` is attached, so the guard must catch it,
+  // re-arm, and re-throw — otherwise a future non-`async` caller/refactor would wedge the guard
+  // permanently in-flight. We assert both: the throw propagates (stays loud, not swallowed) AND the
+  // next tick starts a fresh pass (the guard re-armed rather than sticking at in-flight).
+  let starts = 0;
+  const tick = guardOverlappingPasses(() => {
+    starts++;
+    throw new Error("synchronous boom"); // violates the "must not throw synchronously" contract
+  });
+  assertThrows(() => tick(), Error, "synchronous boom");
+  assertThrows(() => tick(), Error, "synchronous boom");
+  assertEquals(starts, 2, "the guard re-armed after a synchronous throw, so the next tick ran the pass");
+});
+
 /**
  * A {@link CorrelationLink} wrapper that delegates to a real registry but can be flipped to throw on
  * `link()`/`releaseJob()`, exercising the advisory-resilience contract: `#link`/`#unlink` are

package/app/agentic/families/relay.family.ts

@@ -24,6 +24,7 @@ import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY, RelayHub, type RelayHubOptions } from "@nanobpm/agentic/relay";
 import {
+  parseTranscriptEvent,
   type SqliteDb,
   type TranscriptLifecycle,
   type TranscriptRing,
@@ -50,6 +51,14 @@ const SWEEP_DIVISOR = 4;
  * 32-bit timer and Node silently clamps it to 1ms — turning a slow periodic tick into a busy loop. */
 const MAX_TIMER_MS = 2_147_483_647;
 
+/**
+ * Default cadence (ms) of the defensive engine-reconcile pass (#661) — the safety net that releases a
+ * correlation whose engine JOB park is gone but whose terminal `lifecycle` event never arrived (an
+ * unclean worker exit). 30s trades a small staleness bound for a light engine-read load; the precise,
+ * immediate release stays the terminal-lifecycle path, so this only ever mops up unclean exits.
+ */
+const DEFAULT_ENGINE_RECONCILE_MS = 30_000;
+
 /**
  * The retention-sweep cadence (ms) for a given ephemeral-retention window: a fraction of the window,
  * floored at 1ms and — crucially — capped at {@link MAX_TIMER_MS} so a large retention config (e.g.
@@ -64,12 +73,75 @@ export function sweepIntervalMs(ephemeralRetentionMs: number): number {
   return Math.min(MAX_TIMER_MS, Math.max(1, interval));
 }
 
+/**
+ * The defensive engine-reconcile cadence (ms) for a given config (#661), or `undefined` to DISABLE the
+ * pass. An omitted config uses {@link DEFAULT_ENGINE_RECONCILE_MS}; a non-finite or non-positive value
+ * (a broken config, or a deliberate opt-out) disables the pass rather than degrading into a 1ms busy
+ * loop; a finite positive value is floored at 1ms (so a sub-millisecond config like 0.5 cannot floor
+ * to 0 and degrade into a busy `setInterval(0)`) and capped at {@link MAX_TIMER_MS} so a large window
+ * cannot overflow Node's 32-bit timer.
+ */
+export function engineReconcileMs(configuredMs?: number): number | undefined {
+  const value = configuredMs ?? DEFAULT_ENGINE_RECONCILE_MS;
+  if (!Number.isFinite(value) || value <= 0) return undefined;
+  return Math.min(MAX_TIMER_MS, Math.max(1, Math.floor(value)));
+}
+
+/**
+ * Wrap an async pass in an in-flight guard so a periodic `setInterval` never fires OVERLAPPING runs
+ * (#661). A single pass of {@link RelayTranscriptService.reconcileEngineCorrelations} awaits an engine
+ * read per linked job, so a pass can outlast its interval (a small configured cadence, or a slow/large
+ * engine read-model); an unguarded `setInterval` would then stack concurrent passes, piling up engine
+ * reads and log volume. While a pass is still pending, every subsequent tick is skipped; the next tick
+ * after it settles — whether it resolves OR rejects, since the guard clears via `.finally` — starts a
+ * fresh pass. The guard clears on BOTH failure modes so it can never wedge in-flight: (1) a
+ * *synchronous* throw from `pass` escapes before `.finally` is attached, so it is caught here — the
+ * guard is re-armed and the fault is re-thrown so it stays loud rather than being silently swallowed;
+ * (2) an async rejection is cleared by `.finally`, but the tick `void`s (does not await) the returned
+ * promise, so `pass` must still settle its own rejections or an unhandled rejection results — which is
+ * why the mount wraps `reconcileEngineCorrelations()` in `.catch`. Making the guard resilient to (1)
+ * removes a subtle footgun for a future caller (or refactor) that returns a non-`async` `pass`. Mirrors
+ * the "one pass at a time" discipline the main poll loop enforces by self-scheduling. Returns the tick
+ * callback to hand to `setInterval`.
+ */
+export function guardOverlappingPasses(pass: () => Promise<void>): () => void {
+  let inFlight = false;
+  return () => {
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      void pass().finally(() => {
+        inFlight = false;
+      });
+    } catch (err) {
+      // A synchronous throw never attaches the `.finally`; re-arm the guard so it does not wedge,
+      // then re-throw so a contract violation still surfaces instead of being silently swallowed.
+      inFlight = false;
+      throw err;
+    }
+  };
+}
+
 /** Read a property off an unknown value without an unsafe `as` cast (mirrors the loader's helper). */
 function readProp(value: unknown, key: string): unknown {
   if (!value || typeof value !== "object") return undefined;
   return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
 }
 
+/**
+ * Decode a single relay chunk through the ONE canonical transcript parser and report whether it is a
+ * TERMINAL `lifecycle` event (`phase` `completed`/`exited`) — the authoritative "job end" signal a
+ * clean agent run emits on its transcript stream (#661). Anything else — raw terminal bytes, a
+ * non-envelope JSON value, a `phase: "open"` lifecycle, any other event kind — is not terminal.
+ * Reusing {@link parseTranscriptEvent} keeps transcript-vocab knowledge out of the content-agnostic
+ * relay ring and off any forked decoder (Derivation Over Duplication): the ring still sees opaque
+ * bytes; only this narrow seam classifies them.
+ */
+function isTerminalLifecycleChunk(chunk: string): boolean {
+  const event = parseTranscriptEvent({ offset: 0, chunk });
+  return event.kind === "lifecycle" && (event.phase === "completed" || event.phase === "exited");
+}
+
 /**
  * A resume-from-offset source with no retained chunks — used to flush/complete a stream that a
  * producer opened logically but never wrote to, so its transcript is still stamped `completed`
@@ -424,11 +496,41 @@ export class RelayTranscriptService {
     this.#streams.clear();
   }
 
-  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, then delegate. */
+  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, delegate, then
+   * release on a terminal `lifecycle` event (#661 — AFTER the hub appended the chunk, so the terminal
+   * event itself is captured in the flushed transcript). */
   #onFrame(frame: Frame, conn: RelayConnectionCtx): void {
     this.#reconcile();
     this.#observe(frame, conn);
     this.relay.handle(frame, conn);
+    this.#observeTerminalLifecycle(frame);
+  }
+
+  /**
+   * Primary job-end release (#661): when a `produce` frame carries the terminal `lifecycle` event
+   * (`phase` `completed`/`exited`), complete its stream so the worker's job⇄instance correlation is
+   * released the moment the job ends — even though the worker's relay connection stays open across jobs
+   * (the disconnect/supersede release paths miss that idle-after-last-job tail, so an idle worker's
+   * finished job would otherwise linger as a phantom active job on its supply row). Runs AFTER the hub
+   * appends the chunk to the ring, so the terminal event is part of the flushed transcript. A narrow,
+   * self-contained decode at the correlation seam that reuses the ONE canonical
+   * {@link parseTranscriptEvent} — the content-agnostic relay ring keeps treating chunks as opaque
+   * bytes, and no transcript-vocab knowledge is forked into it. Non-terminal chunks (raw bytes, a
+   * `phase: "open"` lifecycle, any other event kind) never complete a live stream, so a genuinely
+   * active job is never cleared. Advisory — never throws into the frame handler.
+   */
+  #observeTerminalLifecycle(frame: Frame): void {
+    if (readProp(frame.payload, "op") !== "produce") return;
+    const stream = readProp(frame.payload, "stream");
+    if (typeof stream !== "string" || stream === "") return;
+    const chunk = readProp(frame.payload, "chunk");
+    if (typeof chunk !== "string" || chunk === "") return;
+    const state = this.#streams.get(stream);
+    // Idempotent: an unknown or already-completed stream needs no (further) release — a second terminal
+    // event, or a late one after the disconnect/supersede path already completed the stream, is a no-op.
+    if (state === undefined || state.completed) return;
+    if (!isTerminalLifecycleChunk(chunk)) return;
+    this.completeStream(stream);
   }
 
   /** Record `produce` ownership so a producer disconnect can drive ephemeral completion. */
@@ -624,6 +726,61 @@ export class RelayTranscriptService {
     }
   }
 
+  /**
+   * Defensive engine-reconcile safety net (#661): release any linked jobKey whose engine JOB park is
+   * no longer live. The precise, fast release is the terminal `lifecycle` event
+   * ({@link #observeTerminalLifecycle}), but an UNCLEAN worker exit (crash/kill) can skip that event —
+   * and because the worker's relay connection is persistent across jobs, the disconnect release never
+   * fires either, so the finished job would linger as a phantom active job on the worker's supply row.
+   * This periodic pass asks the engine read model (the same {@link ElementInstanceResolver} the link
+   * path uses at #544) whether each linked job is still parked; a job the engine no longer parks
+   * (resolver returns `undefined`) is released and its transcript completed. Bounds staleness regardless
+   * of whether the worker emitted a clean terminal event — and also covers a worker that emitted nothing
+   * and merely went quiet.
+   *
+   * Advisory and best-effort: a no-op with no resolver wired, and a resolver THROW / REJECTION for a
+   * given job is treated as "unknown — keep it linked" (never a false release of a genuinely active
+   * job). The linked set is snapshotted before any await so a concurrent completion (a terminal
+   * lifecycle event landing mid-pass) cannot corrupt iteration, and each release re-checks the current
+   * stream state so a job already released between snapshot and resolution is not double-completed.
+   */
+  async reconcileEngineCorrelations(): Promise<void> {
+    const resolve = this.#resolveElementInstance;
+    if (resolve === undefined) return;
+    const linked: { stream: string; jobKey: string; processInstanceKey?: string }[] = [];
+    for (const [stream, state] of this.#streams) {
+      if (!state.linked || state.completed) continue;
+      const jobKey = jobKeyOfStream(stream);
+      if (jobKey === undefined) continue;
+      const processInstanceKey = this.#correlation()?.resolve?.(jobKey)?.processInstanceKey;
+      linked.push({ stream, jobKey, processInstanceKey });
+    }
+    for (const { stream, jobKey, processInstanceKey } of linked) {
+      let activeKey: string | undefined;
+      try {
+        activeKey = await resolve(jobKey, processInstanceKey);
+      } catch (err) {
+        // A transient engine read failure must NOT be read as "job gone" — leave the job linked; a
+        // later pass (or the terminal lifecycle event) releases it. Advisory, never a false release.
+        this.#log.warn("agentic relay engine-reconcile read failed — leaving correlation linked", {
+          stream,
+          jobKey,
+          err: String(err),
+        });
+        continue;
+      }
+      // A live JOB park (a resolved element-instance key) means the job is genuinely active — keep it.
+      if (activeKey !== undefined) continue;
+      // The engine no longer parks this job → it ended (possibly via an unclean exit that skipped the
+      // terminal lifecycle event). Re-check the current state — a concurrent completion may already
+      // have released it — then release its correlation and flush its transcript.
+      const current = this.#streams.get(stream);
+      if (current === undefined || current.completed || !current.linked) continue;
+      this.#log.info("agentic relay engine-reconcile released a stale correlation", { stream, jobKey });
+      this.completeStream(stream);
+    }
+  }
+
   /**
    * The still-live relay ring for a stream, for the read path to serve BEFORE a durable flush (#486).
    *
@@ -670,11 +827,18 @@ export function createRelayFamily(options: {
   readonly relay?: RelayHubOptions;
   readonly transcript?: TranscriptStoreOptions;
   readonly ensureSchema?: boolean;
+  /**
+   * Cadence (ms) of the defensive engine-reconcile pass (#661). Defaults to
+   * {@link DEFAULT_ENGINE_RECONCILE_MS}. Clamped to Node's 32-bit timer ceiling; a non-positive /
+   * non-finite value disables the pass (the terminal-lifecycle release path still runs).
+   */
+  readonly engineReconcileIntervalMs?: number;
   /** Called with the live service once mounted, so a driver can drive completion/reattach. */
   readonly onMounted?: (service: RelayTranscriptService) => void;
 } = {}): AgenticFamily {
   let service: RelayTranscriptService | undefined;
   let sweepTimer: ReturnType<typeof setInterval> | undefined;
+  let engineReconcileTimer: ReturnType<typeof setInterval> | undefined;
   return {
     name: RELAY_FAMILY_NAME,
     mount(ctx: AgenticContext): void {
@@ -729,6 +893,31 @@ export function createRelayFamily(options: {
         tick();
       }
 
+      // Defensive engine-reconcile safety net (#661): periodically release any linked correlation
+      // whose engine JOB park is gone but whose terminal `lifecycle` event never arrived (an unclean
+      // worker exit), so a crashed worker's finished job stops showing as a phantom active job. Only
+      // useful when an element-instance resolver is wired (engine read-model access); harmless no-op
+      // otherwise. Advisory — a reconcile fault is logged, never thrown, and never keeps the process
+      // alive on its own.
+      if (ctx.resolveElementInstance !== undefined) {
+        const reconcileInterval = engineReconcileMs(options.engineReconcileIntervalMs);
+        if (reconcileInterval !== undefined) {
+          // In-flight guard: `reconcileEngineCorrelations()` is async and awaits an engine read per
+          // linked job, so a pass can outlast `reconcileInterval` (a small interval, or a slow/large
+          // engine read-model). Without a guard, `setInterval` would fire overlapping passes that pile
+          // up concurrent engine reads and log volume. {@link guardOverlappingPasses} skips a tick while
+          // the previous pass is still running so only one reconcile runs at a time — the same "one pass
+          // at a time" discipline the main poll loop enforces by self-scheduling.
+          const reconcileTick = guardOverlappingPasses(() =>
+            (service?.reconcileEngineCorrelations() ?? Promise.resolve()).catch((err: unknown) => {
+              ctx.log.warn("agentic relay engine-reconcile failed", { err: String(err) });
+            }),
+          );
+          engineReconcileTimer = setInterval(reconcileTick, reconcileInterval);
+          engineReconcileTimer.unref?.();
+        }
+      }
+
       options.onMounted?.(service);
     },
     teardown(): void {
@@ -736,6 +925,10 @@ export function createRelayFamily(options: {
         clearInterval(sweepTimer);
         sweepTimer = undefined;
       }
+      if (engineReconcileTimer !== undefined) {
+        clearInterval(engineReconcileTimer);
+        engineReconcileTimer = undefined;
+      }
       service?.teardown();
       if (currentService === service) setCurrentRelayTranscriptService(undefined);
       service = undefined;

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.8",
   "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",