@nanobpm/nano-workforce 0.171.11 → 0.172.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.172.0](https://github.com/nanobpm/nano-workforce/compare/v0.171.11...v0.172.0) (2026-09-01)
+
+### Features
+
+* **service:** emit repository.cloneTimeoutMs in the agent-task envelope ([#697](https://github.com/nanobpm/nano-workforce/issues/697)) ([0d8a358](https://github.com/nanobpm/nano-workforce/commit/0d8a3582769f6561d647563168a8a50d0d54f3df)), closes [#694](https://github.com/nanobpm/nano-workforce/issues/694)
+
 ## [0.171.11](https://github.com/nanobpm/nano-workforce/compare/v0.171.10...v0.171.11) (2026-09-01)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -96,6 +96,14 @@ export const ENV_CONTRACTS = {
     semantics: "Poller cadence in milliseconds for the self-scheduling reconciliation loop.",
     default: "60000",
   },
+  NANO_PR_CLONE_TIMEOUT_MS: {
+    category: "env",
+    name: "NANO_PR_CLONE_TIMEOUT_MS",
+    owner: "app/repoEnvelope.ts",
+    semantics:
+      "Clone timeout in milliseconds emitted as `repository.cloneTimeoutMs` in the agent-task envelope so the c8ctl harness raises its 120s default for large-repo provisioning (branch-scoped blobless clones of big monorepos still approach/exceed 120s; issue #694). Inherited by both the review-round and merge paths via the one `repoEnvelopeVars` builder.",
+    default: "600000",
+  },
   NANO_PR_MAX_ROUNDS: {
     category: "env",
     name: "NANO_PR_MAX_ROUNDS",
@@ -384,9 +392,9 @@ 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 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 `sha` — 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. The field is named `sha` because that is the field the c8ctl harness's `provisionRepo` reads to drive the checkout — an earlier `commitSha` key was a silent no-op (issue #695). 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) and a `cloneTimeoutMs` (from `NANO_PR_CLONE_TIMEOUT_MS`, default 600000 = 10 min) that raises the harness's 120s default so a large monorepo's blobless single-branch clone provisions instead of dying at 120s (issue #694). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `sha` — 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. The field is named `sha` because that is the field the c8ctl harness's `provisionRepo` reads to drive the checkout — an earlier `commitSha` key was a silent no-op (issue #695). Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
     shape:
-      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string, sha?: string, branch?: { create: string } }',
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", cloneTimeoutMs: number, baseRef?: string, sha?: string, branch?: { create: string } }',
   },
   "epicSet.submit": {
     category: "wire",

package/app/repoEnvelope.ts

@@ -8,6 +8,7 @@
 // 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 { readEnvOr } from "./contracts.ts";
 import { isCommitSha } from "./world/index.ts";
 
 /** The reserved namespace key the c8ctl nano worker harness reads the agent-task envelope from
@@ -78,6 +79,13 @@ export function repoEnvelopeVars(
         // has a valid merge-base. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).
         singleBranch: true,
         filter: "blob:none",
+        // Raise the harness's 120s default clone timeout for large-repo provisioning (issue #694).
+        // A branch-scoped blobless clone of a 24.6k-file monorepo (`camunda/camunda`) still
+        // approaches/exceeds 120s, so we emit `cloneTimeoutMs` (default 600000 = 10 min, via the
+        // `NANO_PR_CLONE_TIMEOUT_MS` knob) rather than let the harness fall back to its 120000ms
+        // default. Emitted on ALL paths from this one builder, so BOTH the review-round path
+        // (`service.ts` `submitPr`) and the merge path (`service.ts` `startMerge`) inherit it.
+        cloneTimeoutMs: cloneTimeoutMs(),
         // 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 } : {}),
@@ -105,3 +113,16 @@ export function repoEnvelopeVars(
     },
   };
 }
+
+/** Resolve the clone timeout (ms) the harness applies to provisioning, from the one typed knob
+ * `NANO_PR_CLONE_TIMEOUT_MS` (default 600000 = 10 min; issue #694). A branch-scoped blobless clone
+ * of a large monorepo still approaches/exceeds the harness's 120s default, so we raise it here. A
+ * non-numeric or non-positive override degrades to the registered default rather than emitting a
+ * bogus (0 / NaN) timeout the harness would then treat as "use the 120s default". */
+function cloneTimeoutMs(): number {
+  const raw = Number(readEnvOr("NANO_PR_CLONE_TIMEOUT_MS"));
+  return Number.isFinite(raw) && raw > 0 ? raw : Number(envDefaultCloneTimeoutMs);
+}
+
+/** The registered default, resolved once from the schema so the fallback stays single-sourced. */
+const envDefaultCloneTimeoutMs = readEnvOr("NANO_PR_CLONE_TIMEOUT_MS", "600000", {});

package/app/service.test.ts

@@ -483,6 +483,38 @@ test("repoEnvelopeVars emits the repository envelope keyed on the PR head branch
   assertEquals(env.repository.filter, "blob:none");
   // The base branch is emitted so the harness fetches its tip, keeping `origin/<base>` reachable.
   assertEquals(env.repository.baseRef, "main");
+  // The clone timeout is raised above the harness's 120s default for large-repo provisioning (#694).
+  assertEquals(env.repository.cloneTimeoutMs, 600000);
+});
+
+test("repoEnvelopeVars emits cloneTimeoutMs from NANO_PR_CLONE_TIMEOUT_MS, default 600000 (#694)", () => {
+  // Default (knob unset): 600000ms = 10 min, raising the harness's 120000ms default so a
+  // branch-scoped blobless clone of a large monorepo provisions instead of dying at 120s.
+  const prev = process.env.NANO_PR_CLONE_TIMEOUT_MS;
+  delete process.env.NANO_PR_CLONE_TIMEOUT_MS;
+  try {
+    const def = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"];
+    assertEquals(def.repository.cloneTimeoutMs, 600000);
+    // Override wins.
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "900000";
+    const over = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"];
+    assertEquals(over.repository.cloneTimeoutMs, 900000);
+    // A non-positive / non-numeric override degrades to the registered default rather than emitting
+    // a bogus 0/NaN the harness would treat as "use the 120s default".
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "0";
+    assertEquals(
+      ((repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"]).repository.cloneTimeoutMs,
+      600000,
+    );
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "notanumber";
+    assertEquals(
+      ((repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"]).repository.cloneTimeoutMs,
+      600000,
+    );
+  } finally {
+    if (prev === undefined) delete process.env.NANO_PR_CLONE_TIMEOUT_MS;
+    else process.env.NANO_PR_CLONE_TIMEOUT_MS = prev;
+  }
 });
 
 test("repoEnvelopeVars omits baseRef when the base branch is unresolved", () => {
@@ -492,6 +524,8 @@ test("repoEnvelopeVars omits baseRef when the base branch is unresolved", () =>
   assertEquals(env.repository.filter, "blob:none");
   // …but `baseRef` is omitted entirely rather than emitted as null (no key at all).
   assertEquals("baseRef" in env.repository, false);
+  // The clone timeout is still emitted (it's base-ref-independent).
+  assertEquals(env.repository.cloneTimeoutMs, 600000);
 });
 
 test("repoEnvelopeVars emits nothing when the head branch is unresolved", () => {

package/package.json

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