@nanobpm/nano-workforce 0.171.4 → 0.171.6

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.171.6](https://github.com/nanobpm/nano-workforce/compare/v0.171.5...v0.171.6) (2026-09-01)
+
+### Bug Fixes
+
+* **agentic:** emit the repository envelope on implementation jobs so they run in an isolated clone ([#685](https://github.com/nanobpm/nano-workforce/issues/685)) ([be98081](https://github.com/nanobpm/nano-workforce/commit/be980818321f18e101d0fbef85b30b75d6a6fd15)), closes [#684](https://github.com/nanobpm/nano-workforce/issues/684)
+
+## [0.171.5](https://github.com/nanobpm/nano-workforce/compare/v0.171.4...v0.171.5) (2026-09-01)
+
+### Performance Improvements
+
+* **agents:** warm the build cache once, then build module-scoped — never a cold `-am` reactor build ([#682](https://github.com/nanobpm/nano-workforce/issues/682)) ([338057b](https://github.com/nanobpm/nano-workforce/commit/338057b7f65cbf4e61cf4d74efaa596b3422532b)), closes [#681](https://github.com/nanobpm/nano-workforce/issues/681)
+
 ## [0.171.4](https://github.com/nanobpm/nano-workforce/compare/v0.171.3...v0.171.4) (2026-09-01)
 
 ### Bug Fixes

package/app/contracts.ts

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

package/app/feature.test.ts

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

package/app/feature.ts

@@ -19,6 +19,7 @@ import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcr
 import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
 import type { ReadinessProbe } from "./readiness.ts";
+import { repoEnvelopeVars } from "./repoEnvelope.ts";
 
 /** Optional intake-time readiness gate for a feature run (issue #295): the `capability`/`command`/…
  * probes the run must ALL satisfy before its implementation agent is dispatched (parked, durably, at
@@ -336,6 +337,10 @@ export async function startFeature(
       updated_at: ts,
     });
   }
+  const taskId = featureTaskId(parsed.number);
+  // Pre-PR feature branch (issue #684): the deterministic `feat/<task.id>` the harness creates off the
+  // base for the implementation agent (the agent-guide's `feat/*` convention), matching `task.id`.
+  const prePrBranch = `feat/${taskId}`;
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: FEATURE_PROCESS_ID,
     variables: {
@@ -349,7 +354,7 @@ export async function startFeature(
       // (resources/prompts/feature.md); `task.id` fixes its deterministic branch `feat/<task.id>` across a
       // resume. Unlike an epic, there is no planner — the whole issue IS the slice.
       task: {
-        id: featureTaskId(parsed.number),
+        id: taskId,
         title: parsed.planKey,
         prompt:
           `Implement the GitHub issue ${parsed.planKey} end to end. Read it in full first ` +
@@ -406,6 +411,15 @@ export async function startFeature(
       // links this feature run to its agent transcript in Nano Explorer (feature.bpmn `implement-task`
       // ioMapping). Read down into the job via `=transcriptUrlBase`.
       [TRANSCRIPT_URL_BASE_VAR]: transcriptUrlBaseFor(),
+      // Host-git provisioning (c8ctl, issue #684): deliver the repository envelope so the
+      // `senior:feature` implementation agent gets an ISOLATED throwaway clone instead of inheriting
+      // the worker's launch dir (which, with several copilot workers on one host, means concurrent
+      // implementation jobs share — and clobber — one checkout, violating the durable-resume design).
+      // A feature run is PRE-PR: there is no head branch yet, so the harness checks out the BASE
+      // branch (`ref = base`) and creates the deterministic `feat/<task.id>` feature branch itself
+      // (`branchCreate`), matching the agent-guide's `feat/*` convention. Spread last so an unresolved
+      // repo (`{}`) leaves the other vars untouched.
+      ...repoEnvelopeVars(parsed.repo, base, null, null, prePrBranch),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/plan.test.ts

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

package/app/plan.ts

@@ -24,6 +24,7 @@ import {
 import { derivedTrackingTable } from "./instanceTracking.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
 import type { ReadinessProbe } from "./readiness.ts";
+import { repoEnvelopeVars } from "./repoEnvelope.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
 
 /** The BPMN process this module drives (resources/processes/plan-fanout.bpmn). */
@@ -1074,6 +1075,16 @@ export async function startPlan(
       // instance. A ROOT never runs the preflight, so its `gateKey` stays `null`, unused.
       gateKey: probes ? `preflight:${parsed.planKey}` : null,
       resolvedArtifacts: null,
+      // Host-git provisioning (c8ctl, issue #684): deliver the repository envelope so each epic slice's
+      // `senior:feature` implementation agent (plan-fanout's per-wave `implement-cell`) gets an
+      // ISOLATED throwaway clone instead of inheriting the worker's launch dir — otherwise several
+      // copilot workers on one host share (and clobber) a single checkout, violating the durable-resume
+      // design. This is the whole-epic seed, so it carries `ref = base` (the epic integration branch)
+      // but NO `branchCreate`: each slice's deterministic `feat/<task.id>` branch differs per MI child,
+      // so the agent cuts its own branch inside the isolated clone (per resources/prompts/feature.md).
+      // The process-level variable propagates through the wave subprocess + `implement-cell` callActivity
+      // into each agent job. Spread last so an unresolved repo (`{}`) leaves the other vars untouched.
+      ...repoEnvelopeVars(parsed.repo, base),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/repoEnvelope.ts

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

package/app/service.test.ts

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

package/app/service.ts

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

package/docs/agent-guide.md

@@ -154,6 +154,30 @@ Track a plan the same way you track PRs — its `process_key` is an engine insta
 can inspect in §5, and the PRs it opens show up in `/status` as ordinary convergence
 loops.
 
+### Build hygiene — implementation agents warm up once, then build module-scoped
+
+Implementation and CI-fix agents run on **stateless / ephemeral workers**: the
+workspace, including its build outputs, is thrown away between runs, so each worker pays any
+cold whole-reactor build tax independently. To keep iterations fast, the implementation
+prompts (`resources/prompts/feature.md`, `resources/prompts/fix-ci.md`) instruct every
+agent to, **before iterating on a build in the target repo**:
+
+1. **Read the target repo's own `AGENTS.md` / `CONTRIBUTING.md` build section** — the
+   recipe is authored there, never duplicated into nano-workforce (a per-repo copy here
+   would rot as the target's build changes).
+2. **Run the prescribed dependency warm-up once**, right after checkout. For a Maven
+   monorepo that ships the fast path (e.g. camunda), that is
+   `./mvnw install -Dquickly -T1C` — it installs every reactor SNAPSHOT into `~/.m2`.
+3. **Then build only the changed module, offline, without `-am`** —
+   `./mvnw -Dquickly -o -pl <module> <goals>`. Never run a cold `-am` reactor build per
+   iteration.
+
+The repo-agnostic infra levers behind this — a host-persisted `~/.m2` and a shared
+remote Maven build cache for JVM-capable worker hosts — live in worker-host config, not
+in per-repo files here. The retro loop (`resources/prompts/retro.md`) promotes any
+durable "warm the cache, then build module-scoped" lesson into the *target repo's*
+`AGENTS.md`, keeping each target's recipe sharp without nano-workforce owning it.
+
 ---
 
 ## 3. Answer escalations (unblock a human-in-the-loop wait)

package/e2e/feature-run.e2e.ts

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

package/e2e/plan-fanout.e2e.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.171.4",
+  "version": "0.171.6",
   "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",

package/resources/prompts/feature.md

@@ -91,6 +91,28 @@ against the wrong base will not be merged into the epic.
    pointing at an issue).
 5. Clean up any scratch clone/worktree you created outside the commit.
 
+## Build hygiene — warm up once, then build module-scoped; never a cold `-am` reactor build
+
+Before you iterate on a build in the target repo,
+**read its `AGENTS.md` / `CONTRIBUTING.md` build section** and run the prescribed
+**dependency warm-up exactly once** right after checkout, then scope every
+subsequent build to the module you changed. Do **not** run a cold whole-reactor /
+all-modules build on each iteration — a stateless worker that skips the warm-up
+pays the upstream reactor-compile tax inline on every run, which can block for
+many minutes.
+
+- **Warm up once (blocking, right after branching).** For a Maven monorepo that
+  ships this fast path (e.g. camunda), that is
+  `./mvnw install -Dquickly -T1C` — it installs every reactor SNAPSHOT into
+  `~/.m2` so later module builds resolve them instead of recompiling them.
+- **Then build only the changed module, offline, without `-am`.** e.g.
+  `./mvnw -Dquickly -o -pl <module> test-compile`. Dropping `-am` after the
+  warm-up is what keeps each iteration to seconds; a per-iteration
+  `-am <goals>` (e.g. `-am clean test-compile`) re-compiles the upstream modules from source.
+- **The recipe lives in the target repo, not here.** Always defer to that repo's
+  own `AGENTS.md` / `CONTRIBUTING.md` build section for the exact commands — the
+  Maven lines above are the common case, not a substitute for reading it.
+
 ## Closing keywords vs. scope splits — don't close a broader-scoped parent
 
 The convergence loop runs a **scope-integrity classifier** on your PR before it

package/resources/prompts/fix-ci.md

@@ -50,6 +50,14 @@ the PR's checks yourself (`gh pr checks`, `gh run view`).
 3. Apply the **minimal, correct** fix. Keep it scoped to what the failing checks
    demand — do not refactor unrelated code.
 4. Run the relevant check locally to confirm it now passes.
+   **Build module-scoped, not cold.** Before iterating, read the target repo's
+   `AGENTS.md` / `CONTRIBUTING.md` build section and run its prescribed
+   **dependency warm-up once** (for a Maven monorepo that ships it, e.g. camunda,
+   `./mvnw install -Dquickly -T1C`), then scope the build to the changed module
+   and drop `-am` (`./mvnw -Dquickly -o -pl <module> <goals>`). Never run a cold
+   whole-reactor `-am` build per iteration — a stateless worker that skips the
+   warm-up pays the upstream reactor-compile tax inline and can block for many
+   minutes.
 5. Commit (sign off with `-s` if the repo enforces DCO) and push to the branch.
 6. **Make CI re-validate your fix.** Some repos deliberately run CI only when a
    PR is *opened* (to keep review cheap), so a follow-up push does **not**

package/resources/prompts/retro.md

@@ -44,7 +44,11 @@ You have `gh` / git authenticated for the target repository.
 4. **Choose the right home for each promoted lesson** — the whole point is to make the knowledge
    *load-bearing*, not just written down:
    - **`AGENTS.md`** (or `CONTRIBUTING.md`) — a convention, a "before you build, run X", a
-     non-obvious constraint. The default home.
+     non-obvious constraint. The default home. A **build recipe** is the textbook case:
+     a durable "warm the dependency cache once, then build module-scoped — never a cold
+     whole-reactor build" lesson (e.g. Maven's `./mvnw install -Dquickly -T1C` warm-up,
+     then `-pl <module>` without `-am`) belongs in the *target repo's* `AGENTS.md`
+     build section, never duplicated into nano-workforce.
    - **A script** — if the lesson is "always run these steps in this order", encode it as a
      script (or a `make`/`npm`/`deno task` target) so it can't be forgotten.
    - **A CI step** — if the lesson is "this class of mistake should never merge", add a guard/gate