@nanobpm/nano-workforce 0.87.0 → 0.88.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.88.0](https://github.com/nanobpm/nano-workforce/compare/v0.87.0...v0.88.0) (2026-08-18)
+
+
+### Features
+
+* **service:** branch-scoped treeless clone for review-job repo envelope ([#287](https://github.com/nanobpm/nano-workforce/issues/287)) ([#288](https://github.com/nanobpm/nano-workforce/issues/288)) ([c90dc23](https://github.com/nanobpm/nano-workforce/commit/c90dc23274fbb5e19835e25eef755f88337ab86f)), closes [jwulf/c8ctl-plugin-nano#91](https://github.com/jwulf/c8ctl-plugin-nano/issues/91)
+
 # [0.87.0](https://github.com/nanobpm/nano-workforce/compare/v0.86.0...v0.87.0) (2026-08-18)
 
 

package/SPEC.md

@@ -193,9 +193,17 @@ Consequences the prompt (`resources/prompts/review-round.md`) encodes:
   `io.nanobpm.agentTask.repository.url`; the **app** supplies it — plus the head
   branch as `…repository.ref` — as a process variable at `createInstance`
   (`repoEnvelopeVars` in `app/service.ts`, resolving the head via `fetchPrMeta`/
-  `fetchPrHead`). The harness is PR-agnostic: it does **not** derive the head branch
-  from `prNumber`/`prUrl`. When the head can't be resolved the envelope is omitted and
-  the agent falls back to the worker's launch directory (the legacy behavior).
+  `fetchPrHead`). The envelope also carries clone-shaping fields so large monorepos
+  provision within the c8ctl clone timeout (issue #287): `singleBranch: true` and
+  `filter: "blob:none"` request a **branch-scoped, blobless partial clone** (trees are
+  still fetched up-front — a *treeless* clone would be `--filter=tree:0`; the full
+  commit graph is kept — no `--depth 1` — so `git merge-base` / the review 3-dot diff
+  stays correct while blobs fetch lazily), and, when the PR base branch is resolvable,
+  an optional `…repository.baseRef` so the harness fetches the base tip alongside the
+  head and keeps `origin/<base>` reachable for the diff. The harness is PR-agnostic: it
+  does **not** derive the head branch from `prNumber`/`prUrl`. When the head can't be
+  resolved the envelope is omitted and the agent falls back to the worker's launch
+  directory (the legacy behavior).
 
 ## 6. Signals
 
@@ -625,8 +633,11 @@ but encode incompatible decisions about a shared contract** — a genuine design
   integration provisions the repo and checks out the PR's head branch (it must
   already give the worker repo access to work at all). The **app** resolves the head
   branch and passes it in the `io.nanobpm.agentTask.repository.{url,ref}` envelope
-  (a `createInstance` process variable — see `repoEnvelopeVars`); the harness is
-  PR-agnostic and provisions from that envelope. The worker stays a pure provisioner.
+  (a `createInstance` process variable — see `repoEnvelopeVars`), along with the
+  branch-scoped, blobless clone-shaping fields (`singleBranch`, `filter`, optional
+  `baseRef`) that let large monorepos provision within the clone timeout (#287); the
+  harness is PR-agnostic and provisions from that envelope. The worker stays a pure
+  provisioner.
 - **review-ready via GitHub webhook** — same message, swappable faster trigger,
   when the app is publicly reachable. Deferred (poller-only for v1).
 - **Supervised vs external worker** — the agent runs as an external

package/app/contracts.ts

@@ -334,6 +334,15 @@ export const WIRE_CONTRACTS = {
       "Op-tagged relay control frame a worker terminal chunk producer emits and the hub consumes. The op-tagged shape superseded the legacy positional `{stream, offset, chunk}` frame (nano-ide #234/#236); a producer must emit the op-tagged shape or the hub rejects it as `malformed relay message payload`.",
     shape: '{ op: "produce", incarnation: number, stream: string, offset: number, chunk: string }',
   },
+  "io.nanobpm.agentTask.repository": {
+    category: "wire",
+    name: "io.nanobpm.agentTask.repository",
+    owner: "app/service.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). Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
+    shape:
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

package/app/github.ts

@@ -406,6 +406,10 @@ export interface PrMeta {
    * workspace checkout (`io.nanobpm.agentTask.repository.ref`) so the review agent lands on the
    * PR branch instead of the worker's launch directory. `null` when GitHub doesn't return it. */
   headRef: string | null;
+  /** The PR's base branch name (e.g. `main`). Emitted in the repository envelope so the c8ctl
+   * harness fetches the base tip alongside the single-branch head clone, keeping `git diff
+   * origin/<base>...HEAD` (the review 3-dot diff) computable. `null` when GitHub doesn't return it. */
+  baseRef: string | null;
 }
 
 export async function fetchPrMeta(
@@ -414,10 +418,10 @@ export async function fetchPrMeta(
   token: string,
 ): Promise<PrMeta | null> {
   if (await useGh()) {
-    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "title,body,headRefName"]);
+    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "title,body,headRefName,baseRefName"]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const j = JSON.parse(out) as { title?: string; body?: string; headRefName?: string | null };
-    return { title: j.title ?? null, body: j.body ?? "", headRef: j.headRefName ?? null };
+    const j = JSON.parse(out) as { title?: string; body?: string; headRefName?: string | null; baseRefName?: string | null };
+    return { title: j.title ?? null, body: j.body ?? "", headRef: j.headRefName ?? null, baseRef: j.baseRefName ?? null };
   }
   if (!token) return null;
   const r = await fetch(`https://api.github.com/repos/${repo}/pulls/${number}`, {
@@ -425,8 +429,8 @@ export async function fetchPrMeta(
   });
   if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const j = (await r.json()) as { title?: string; body?: string; head?: { ref?: string | null } };
-  return { title: j.title ?? null, body: j.body ?? "", headRef: j.head?.ref ?? null };
+  const j = (await r.json()) as { title?: string; body?: string; head?: { ref?: string | null }; base?: { ref?: string | null } };
+  return { title: j.title ?? null, body: j.body ?? "", headRef: j.head?.ref ?? null, baseRef: j.base?.ref ?? null };
 }
 
 /** Fetch an issue's title via the configured transport, mirroring `fetchPrMeta` (both `gh` and
@@ -666,12 +670,12 @@ export async function fetchPrHead(
   repo: string,
   number: number | string,
   token: string,
-): Promise<{ headRef: string | null; headSha: string | null } | null> {
+): Promise<{ headRef: string | null; headSha: string | null; baseRef: string | null } | null> {
   if (await useGh()) {
-    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "headRefName,headRefOid"]);
+    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "headRefName,headRefOid,baseRefName"]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const j = JSON.parse(out) as { headRefName?: string | null; headRefOid?: string | null };
-    return { headRef: j.headRefName ?? null, headSha: j.headRefOid ?? null };
+    const j = JSON.parse(out) as { headRefName?: string | null; headRefOid?: string | null; baseRefName?: string | null };
+    return { headRef: j.headRefName ?? null, headSha: j.headRefOid ?? null, baseRef: j.baseRefName ?? null };
   }
   if (!token) return null;
   const r = await fetch(`https://api.github.com/repos/${repo}/pulls/${number}`, {
@@ -679,8 +683,8 @@ export async function fetchPrHead(
   });
   if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const j = (await r.json()) as { head?: { ref?: string | null; sha?: string | null } };
-  return { headRef: j.head?.ref ?? null, headSha: j.head?.sha ?? null };
+  const j = (await r.json()) as { head?: { ref?: string | null; sha?: string | null }; base?: { ref?: string | null } };
+  return { headRef: j.head?.ref ?? null, headSha: j.head?.sha ?? null, baseRef: j.base?.ref ?? null };
 }
 
 /** The PR's current base branch ref — the branch this PR would land *into*. `null` when no

package/app/service.test.ts

@@ -439,11 +439,26 @@ test("startMerge reads root_request_key off the PR row onto the merge instance",
 // checkout ref, and omitted entirely when the head branch couldn't be resolved (so the harness
 // falls back to the legacy launch-dir behavior instead of cloning the wrong default branch).
 test("repoEnvelopeVars emits the repository envelope keyed on the PR head branch", () => {
-  const vars = repoEnvelopeVars("owner/repo", "feat/issue-12");
+  const vars = repoEnvelopeVars("owner/repo", "feat/issue-12", "main");
   const env = (vars as any)["io.nanobpm.agentTask"];
   assertEquals(env.repository.url, "https://github.com/owner/repo.git");
   assertEquals(env.repository.ref, "feat/issue-12");
   assertEquals(env.repository.provider, "github");
+  // Branch-scoped, blobless partial clone (issue #287): large monorepos provision within the clone
+  // timeout while the full commit graph is kept so `git diff origin/<base>...HEAD` has a merge-base.
+  assertEquals(env.repository.singleBranch, true);
+  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");
+});
+
+test("repoEnvelopeVars omits baseRef when the base branch is unresolved", () => {
+  const env = (repoEnvelopeVars("owner/repo", "feat/issue-12") as any)["io.nanobpm.agentTask"];
+  // The single-branch/blobless partial-clone request still stands without a base ref…
+  assertEquals(env.repository.singleBranch, true);
+  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);
 });
 
 test("repoEnvelopeVars emits nothing when the head branch is unresolved", () => {

package/app/service.ts

@@ -323,8 +323,18 @@ const AGENT_TASK_NS = "io.nanobpm.agentTask";
  * 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. */
-export function repoEnvelopeVars(repo: string, ref: string | null): Record<string, unknown> {
+ * `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. */
+export function repoEnvelopeVars(repo: string, ref: string | null, baseRef: 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
@@ -336,7 +346,20 @@ export function repoEnvelopeVars(repo: string, ref: string | null): Record<strin
   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 },
+      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 } : {}),
+      },
     },
   };
 }
@@ -364,12 +387,14 @@ export async function submitPr(
   const token = process.env.GITHUB_TOKEN ?? "";
   let title: string | null = null;
   let headRef: string | null = null;
+  let baseRef: string | null = null;
   const depKeys = new Set(dependsOn.map((d) => parsePr(d)?.prKey).filter((k): k is string => !!k));
   try {
     const meta = await fetchPrMeta(parsed.repo, parsed.number, token);
     if (meta) {
       title = meta.title;
       headRef = meta.headRef;
+      baseRef = meta.baseRef;
       for (const k of parseDependsOn(meta.body)) depKeys.add(k);
     }
   } catch (err) {
@@ -468,7 +493,7 @@ export async function submitPr(
       // Host-git provisioning (c8ctl): deliver the repository envelope so the `senior:pr-review`
       // harness clones an isolated workspace checked out on the PR head branch. Spread last so an
       // unresolved head (`{}`) leaves the other vars untouched.
-      ...repoEnvelopeVars(parsed.repo, headRef),
+      ...repoEnvelopeVars(parsed.repo, headRef, baseRef),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
@@ -504,8 +529,11 @@ export async function startMerge(
   // means the envelope is omitted and the agent falls back to the worker's launch dir.
   const token = process.env.GITHUB_TOKEN ?? "";
   let headRef: string | null = null;
+  let baseRef: string | null = null;
   try {
-    headRef = (await fetchPrHead(pr.repo, pr.number, token))?.headRef ?? null;
+    const head = await fetchPrHead(pr.repo, pr.number, token);
+    headRef = head?.headRef ?? null;
+    baseRef = head?.baseRef ?? null;
   } catch (err) {
     console.warn(`[startMerge] ${pr.prKey} head branch fetch: ${err}`);
   }
@@ -531,7 +559,7 @@ export async function startMerge(
       abandonBrief: renderAbandonBrief(abUrl),
       // Host-git provisioning (c8ctl): same repository envelope as the convergence loop, so the
       // fix-ci/rebase agents operate on an isolated checkout of the PR head branch.
-      ...repoEnvelopeVars(pr.repo, headRef),
+      ...repoEnvelopeVars(pr.repo, headRef, baseRef),
     },
   });
   if (processInstanceKey != null) {

package/package.json

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

package/pages/overview.page.json

@@ -67,6 +67,7 @@
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "pr_key", "truncate": true, "width": "36%", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "incident_message", "header": "Incident", "truncate": true, "badge": { "tone": "danger", "label": "1" } },
           { "field": "current_round", "template": "{{current_round}} · {{active_worker}}", "header": "Round · Agent" },
           { "field": "updated_at", "header": "Updated", "width": "9rem" }
         ]