@nanobpm/nano-workforce 0.195.0 → 0.195.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.195.1](https://github.com/nanobpm/nano-workforce/compare/v0.195.0...v0.195.1) (2026-09-30)
+
+### Bug Fixes
+
+* **service:** commit review/fix-ci/rebase rounds to the PR branch, not a nano/agent-work fallback ([#817](https://github.com/nanobpm/nano-workforce/issues/817)) ([212e0cc](https://github.com/nanobpm/nano-workforce/commit/212e0cc9755d2cbba34ed5f170952a5e6a142729)), closes [jwulf/c8ctl-plugin-nano#231](https://github.com/jwulf/c8ctl-plugin-nano/issues/231) [#776](https://github.com/nanobpm/nano-workforce/issues/776)
+
 ## [0.195.0](https://github.com/nanobpm/nano-workforce/compare/v0.194.0...v0.195.0) (2026-09-30)
 
 ### Features

package/app/contracts.ts

@@ -424,7 +424,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 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 for a single-task feature run AND — per issue #776 — the deterministic `feat/<node.id>` for each single-instance delivery-graph agent cell, injected per-cell by `agentNodeRepoEnvelope`/`app/deliveryRunner.ts` so a forgetful agent can never be left committing on the base branch and stranding its run on a non-ff push; the epic plan-fanout seed still omits it because its MI children each cut a per-child `feat/<task.id>` the app can't name at compile time, so those agents branch themselves). 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). Alongside the `repository` slice the envelope carries a sibling `task.allowPr: true` (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the git credential (GITHUB_TOKEN, or the `gh` default) for repo provisioning behind that flag, so every repo-backed envelope sets it or the clone dies with `unable to get password from user`; the repoless path emits no envelope and so no `task`. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91, branch-cut guard jwulf/c8ctl-plugin-nano#231).",
+      "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`. On the PRE-PR path `branch.create` is the deterministic `feat/<task.id>` (emitted for a single-task feature run AND — per issue #776 — the deterministic `feat/<node.id>` for each single-instance delivery-graph agent cell, injected per-cell by `agentNodeRepoEnvelope`/`app/deliveryRunner.ts` so a forgetful agent can never be left committing on the base branch and stranding its run on a non-ff push; the epic plan-fanout seed still omits it because its MI children each cut a per-child `feat/<task.id>` the app can't name at compile time, so those agents branch themselves). On the PR-based paths `branch.create` is set to the PR HEAD branch itself (equal to `ref`, jwulf/c8ctl-plugin-nano#231): without it the harness's base-branch guard treats the checkout as base-like and cuts a throwaway `nano/agent-work/<base>-<run>` fallback, stranding the round's commits OFF the PR; with `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR head branch. So `branch.create` is present on both the pre-PR and PR-based paths (only a blank/omitted value drops the key). 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). Alongside the `repository` slice the envelope carries a sibling `task.allowPr: true` (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the git credential (GITHUB_TOKEN, or the `gh` default) for repo provisioning behind that flag, so every repo-backed envelope sets it or the clone dies with `unable to get password from user`; the repoless path emits no envelope and so no `task`. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91, branch-cut guard jwulf/c8ctl-plugin-nano#231).",
     shape:
       'io.nanobpm.agentTask: { repository: { provider: "github", url: string, ref?: string, singleBranch: true, filter: "blob:none", cloneTimeoutMs: number, baseRef?: string, sha?: string, branch?: { create: string } }, task: { allowPr: true } }',
   },

package/app/repoEnvelope.ts

@@ -133,8 +133,14 @@ export class RepoEnvelopeConflictError extends Error {
  * `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. */
+ * the isolated clone lands on the right branch deterministically across a resume. The PR-based paths
+ * (review-round / fix-ci / rebase) ALSO pass `branchCreate = ref` (the PR HEAD branch, equal to
+ * `ref`): without an explicit `branch.create` the harness's base-branch guard
+ * (jwulf/c8ctl-plugin-nano#231) treats the checkout as base-like and cuts a throwaway
+ * `nano/agent-work/<base>-<run>` fallback, stranding the round's commits OFF the PR; with
+ * `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR
+ * head branch itself. `branchCreate` is therefore emitted on both the pre-PR and PR-based paths (only
+ * a blank/omitted value drops the key). */
 export function repoEnvelopeVars(
   repo: string,
   ref: string | null,
@@ -186,7 +192,10 @@ export function repoEnvelopeVars(
         // 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.
+        // The PR-based paths (review/fix-ci/rebase) ALSO pass `branchCreate = ref` (the PR head): without
+        // it the harness's base-branch guard (jwulf/c8ctl-plugin-nano#231) cuts a throwaway
+        // `nano/agent-work/*` fallback OFF the PR; with `ref == create == head` it commits/pushes to the
+        // head branch. Only a blank/omitted value drops the key.
         ...(typeof branchCreate === "string" && branchCreate.trim() !== ""
           ? { branch: { create: branchCreate.trim() } }
           : {}),

package/app/service.test.ts

@@ -1226,8 +1226,10 @@ test("repoEnvelopeVars emits the push-checkpoint under the harness-read `sha` ke
 
 // 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).
+// `feat/<task.id>` feature branch off it. `branch.create` is emitted only for a non-blank branch.
+// The PR-based paths (review-round / fix-ci / rebase) now pass `branchCreate = headRef` too (equal
+// to `ref`) so the harness commits/pushes to the PR head branch instead of cutting a throwaway
+// `nano/agent-work/*` fallback (jwulf/c8ctl-plugin-nano#231); see the PR-path test below.
 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;
@@ -1252,7 +1254,95 @@ test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#
   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
+// PR-path provisioning (jwulf/c8ctl-plugin-nano#231): the review-round / fix-ci / rebase call sites
+// pass `branchCreate = headRef` (equal to `ref`, the PR head). Without it the harness's base-branch
+// guard treats the checkout as base-like and cuts a throwaway `nano/agent-work/<base>-<run>` fallback,
+// stranding the round's commits OFF the PR (the head never advances → no-progress escalation). With
+// `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR
+// head branch itself.
+test("repoEnvelopeVars emits branch.create = head on the PR path (ref == create == head) (#231)", () => {
+  const repo = (repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12") as any)[
+    "io.nanobpm.agentTask"
+  ].repository;
+  assertEquals(repo.ref, "feat/issue-12", "the PR-path envelope checks out the head branch");
+  assertEquals(repo.branch.create, "feat/issue-12", "and asks the harness to work on that same head branch, not a fallback");
+  // Still branch-scoped and blobless, and the base tip stays reachable for the 3-dot diff.
+  assertEquals(repo.singleBranch, true);
+  assertEquals(repo.filter, "blob:none");
+  assertEquals(repo.baseRef, "main");
+});
+
+// Regression guard for the ACTUAL call sites (Copilot PR #817 review): the helper test above would
+// still pass if `submitPr`/`startMerge` dropped the 5th `branchCreate` argument, because
+// `repoEnvelopeVars` accepted it before this change. Drive both PUBLIC entry points with a mocked
+// PR-head response and assert the seeded `createInstance` envelope carries `branch.create === headRef`
+// — i.e. the call sites really thread the PR head into the branch-create slot (jwulf/c8ctl-plugin-nano#231).
+// Both `fetchPrMeta` (submit) and `fetchPrHead` (merge) read the same token-transport pulls endpoint,
+// so one fetch stub returning `head.ref` covers both.
+function withGithubHead(headRef: string, baseRef: string, run: () => Promise<void>): Promise<void> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "t0ken";
+  globalThis.fetch = ((url: string | URL | Request) => {
+    void url;
+    return Promise.resolve(
+      new Response(
+        JSON.stringify({ title: "PR title", body: "", head: { ref: headRef, sha: "HEADSHA" }, base: { ref: baseRef } }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
+    );
+  }) as typeof fetch;
+  return run().finally(() => {
+    globalThis.fetch = prevFetch;
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+    else delete process.env["GITHUB_TOKEN"];
+  });
+}
+
+test("submitPr threads the resolved PR head into the envelope branch.create (#231)", async () => {
+  await withGithubHead("feat/issue-12", "main", async () => {
+    const { data, engine, get } = captureVars();
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 12,
+      url: "https://github.com/owner/repo/pull/12",
+      prKey: "owner/repo#12",
+    });
+    const repo = (get()?.["io.nanobpm.agentTask"] as any)?.repository;
+    assertEquals(repo?.ref, "feat/issue-12", "submitPr checks out the PR head branch");
+    assertEquals(repo?.branch?.create, "feat/issue-12", "submitPr passes headRef as branch.create, not a fallback");
+  });
+});
+
+test("startMerge threads the resolved PR head into the envelope branch.create (#231)", async () => {
+  await withGithubHead("feat/issue-13", "main", async () => {
+    const { data, engine, get } = captureVars();
+    await data.table("pull_requests", "pr_key").insert({
+      pr_key: "owner/repo#13",
+      repo: "owner/repo",
+      number: 13,
+      url: "https://github.com/owner/repo/pull/13",
+      status: "converged",
+      abandon_token: "tok-13",
+      root_request_key: "owner/repo#13",
+    });
+    await startMerge(data, engine, {
+      repo: "owner/repo",
+      number: 13,
+      url: "https://github.com/owner/repo/pull/13",
+      prKey: "owner/repo#13",
+      round: 2,
+    });
+    const repo = (get()?.["io.nanobpm.agentTask"] as any)?.repository;
+    assertEquals(repo?.ref, "feat/issue-13", "startMerge checks out the PR head branch");
+    assertEquals(repo?.branch?.create, "feat/issue-13", "startMerge passes headRef as branch.create, not a fallback");
+  });
+});
+
 // `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,
 // so the round redrives from scratch (exactly as today). Proven against a REAL in-memory SQLite db

package/app/service.ts

@@ -758,7 +758,14 @@ async function submitPrCritical(
       // 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, baseRef, worldSha),
+      //
+      // Pass `headRef` as `branch.create` too (5th arg): on a PR path `ref` is the head branch, but
+      // WITHOUT an explicit `branch.create` the harness's base-branch guard (jwulf/c8ctl-plugin-nano#231)
+      // treats the checkout as base-like and cuts a throwaway `nano/agent-work/<base>-<run>` fallback,
+      // stranding the round's commits OFF the PR (the head never advances → no-progress escalation).
+      // With `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes
+      // to the PR head branch itself. Mirrors the delivery-graph node path (`agentNodeRepoEnvelope`, #776).
+      ...repoEnvelopeVars(parsed.repo, headRef, baseRef, worldSha, headRef),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
@@ -919,8 +926,10 @@ export async function startMerge(
       abandonUrl: abUrl,
       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, baseRef, worldSha),
+      // fix-ci/rebase agents operate on an isolated checkout of the PR head branch. `headRef` is
+      // passed as `branch.create` (5th arg) so the harness commits/pushes to the PR head branch
+      // instead of cutting a `nano/agent-work/*` fallback (jwulf/c8ctl-plugin-nano#231); see submitPr.
+      ...repoEnvelopeVars(pr.repo, headRef, baseRef, worldSha, headRef),
     },
   });
   if (processInstanceKey != null) {

package/package.json

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