@nanobpm/nano-workforce 0.187.0 → 0.187.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.187.1](https://github.com/nanobpm/nano-workforce/compare/v0.187.0...v0.187.1) (2026-09-12)
+
+### Bug Fixes
+
+* **delivery-graph:** emit a deterministic branch.create so agent cells never commit on the base branch ([#781](https://github.com/nanobpm/nano-workforce/issues/781)) ([56f6488](https://github.com/nanobpm/nano-workforce/commit/56f6488344b439a5ac12f5069567facd9519bf66)), closes [#776](https://github.com/nanobpm/nano-workforce/issues/776) [pre-#776](https://github.com/nanobpm/pre-/issues/776) [#776](https://github.com/nanobpm/nano-workforce/issues/776)
+
 ## [0.187.0](https://github.com/nanobpm/nano-workforce/compare/v0.186.4...v0.187.0) (2026-09-12)
 
 ### Features

package/app/contracts.ts

@@ -399,7 +399,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 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). 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).",
+      "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).",
     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/deliveryGraphCompiler.ts

@@ -1057,15 +1057,19 @@ function innerBodyLines(w: NodeWiring, requiredEmits: ReadonlySet<string>): stri
 
 /** Render the DECLARED per-node repository-spec marker task header (#739) for an `agent` node — a single
  * `<zeebe:taskHeaders>` block carrying {@link AGENT_REPO_SPEC_HEADER} with a compact JSON of the node's
- * DECLARED `{ repository, baseBranch }` (each `null` when absent). It is emitted on EVERY agent service
- * task (even one with no declared repo → `{"repository":null,"baseBranch":null}`) so the runner has a
- * single, uniform anchor to replace with the effective envelope on every cell. Digest-stable and
- * env-free — only the declared values (pure graph content) appear here; the run-level fallback and the
- * env-dependent `cloneTimeoutMs` are injected by the runner POST-digest. Declared values pass the
- * `owner/repo` + branch-name allowlists (validator/OpenAPI), so the JSON carries no XML-hostile chars. */
+ * `id` and its DECLARED `{ repository, baseBranch }` (each `null` when absent). It is emitted on EVERY
+ * agent service task (even one with no declared repo → `{"repository":null,"baseBranch":null}`) so the
+ * runner has a single, uniform anchor to replace with the effective envelope on every cell. The node
+ * `id` is carried here (issue #776) so the runner can emit the deterministic per-node `feat/<node.id>`
+ * `branch.create` on the injected envelope — the identity is not otherwise recoverable from the isolated
+ * `<zeebe:taskHeaders>` block the runner rewrites. Digest-stable and env-free — only the node id and
+ * declared values (pure graph content) appear here; the run-level fallback and the env-dependent
+ * `cloneTimeoutMs` are injected by the runner POST-digest. The id + declared values pass the
+ * `owner/repo` + node-id/branch-name allowlists (validator/OpenAPI), so the JSON carries no XML-hostile
+ * chars. */
 function agentRepoSpecHeaderLines(node: Extract<DeliveryNode, { kind: "agent" }>): string[] {
   const trimOrNull = (v: unknown): string | null => (typeof v === "string" && v.trim() !== "" ? v.trim() : null);
-  const spec = JSON.stringify({ repository: trimOrNull(node.agent.repository), baseBranch: trimOrNull(node.agent.baseBranch) });
+  const spec = JSON.stringify({ nodeId: node.id, repository: trimOrNull(node.agent.repository), baseBranch: trimOrNull(node.agent.baseBranch) });
   return [
     "          <zeebe:taskHeaders>",
     `            <zeebe:header key="${AGENT_REPO_SPEC_HEADER}" ${attr("value", spec)} />`,

package/app/deliveryRunner.test.ts

@@ -13,7 +13,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertRejects } from "#test-assert";
 import { AGENT_TERMINAL_SUCCESS_STATUSES } from "./deliveryGraphCompiler.ts";
 import { prepareDeliveryGraph, renderEmitContract, renderIdempotencyPreamble, renderProducerContract, runDeliveryGraph } from "./deliveryRunner.ts";
-import { RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError } from "./repoEnvelope.ts";
+import { RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError, agentNodeRepoEnvelope } from "./repoEnvelope.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 
 const GRAPH: DeliveryGraph = {
@@ -488,6 +488,9 @@ test("prepareDeliveryGraph injects the repository envelope PER agent cell from t
   // Repo-provisioning auth gate (issue #770): the per-cell envelope carries `task.allowPr:true` so the
   // c8ctl harness resolves the git credential for the clone instead of failing on password prompt.
   assert(headers.some((h) => h.includes('task.allowPr" value="true"')), `expected a task.allowPr header, got ${JSON.stringify(headers)}`);
+  // The deterministic per-node isolation branch (issue #776): the harness cuts `feat/<node.id>` itself,
+  // so the agent can never be left committing on the base branch (a non-ff push that strands the run).
+  assert(headers.some((h) => h.includes('repository.branch.create" value="feat/open-b"')), `expected a per-node branch.create header, got ${JSON.stringify(headers)}`);
   // No `__repoSpec` marker survives injection — it is the compiler's digest-stable anchor only.
   assert(!p.bpmn.includes("__repoSpec"), "the __repoSpec marker is fully replaced");
   // No run-root `io.nanobpm.agentTask` variable — the envelope rides headers now, not a run variable.
@@ -542,6 +545,68 @@ test("a declared repository WITHOUT a base branch omits ref/baseRef — the harn
   assert(headers.some((h) => h.includes('repository.url" value="https://github.com/acme/one.git"')), "url present");
   assert(!headers.some((h) => h.includes("repository.ref")), "no ref → clone the repo default branch");
   assert(!headers.some((h) => h.includes("repository.baseRef")), "no baseRef either");
+  // Even without a known base, the deterministic isolation branch is still emitted (issue #776): the
+  // harness cuts `feat/<node.id>` off the cloned default tip, so the agent never commits on the default.
+  assert(headers.some((h) => h.includes('repository.branch.create" value="feat/a"')), `expected branch.create even without a base, got ${JSON.stringify(headers)}`);
+});
+
+test("each agent cell gets its OWN deterministic feat/<node.id> branch.create — never a shared branch (#776)", async () => {
+  const graph: DeliveryGraph = {
+    name: "deterministic isolation branches",
+    nodes: [
+      { id: "impl-a", kind: "agent", agent: { jobType: "senior:feature", prompt: "a", repository: "acme/one" } },
+      { id: "impl-b", kind: "agent", agent: { jobType: "senior:feature", prompt: "b", repository: "acme/two" } },
+    ],
+    edges: [{ from: "impl-a", to: "impl-b" }],
+  };
+  const p = await prepareOk(graph, {});
+  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("repository.branch.create"));
+  // Two distinct cells → two distinct per-node branches, so no two agents can collide on one branch.
+  assert(branches.some((h) => h.includes('value="feat/impl-a"')), `expected feat/impl-a, got ${JSON.stringify(branches)}`);
+  assert(branches.some((h) => h.includes('value="feat/impl-b"')), `expected feat/impl-b, got ${JSON.stringify(branches)}`);
+  assertEquals(branches.length, 2, "exactly one branch.create per agent cell");
+});
+
+test("an explicit repoless run emits NO branch.create — no envelope at all (#776/#729)", async () => {
+  const p = await prepareOk(GRAPH, { repoless: true });
+  assert(!p.bpmn.includes("repository.branch.create"), "a repoless run carries no isolation branch either");
+});
+
+test("a node id that derives an invalid git ref degrades to NO branch.create — never emits an unusable feat/... (#776)", async () => {
+  // Node ids are only constrained by `^[A-Za-z_][A-Za-z0-9_.-]*$`, laxer than git's ref rules: `a..b` and
+  // `a.lock` pass id validation but produce ill-formed `feat/...` refs the harness cannot create. The
+  // runner must degrade to the pre-#776 agent-cuts-its-own-branch behaviour (no branch.create) for those,
+  // not emit a branch the harness will choke on — while a sibling with a valid id still gets its branch.
+  const graph: DeliveryGraph = {
+    name: "invalid-ref node ids degrade",
+    nodes: [
+      { id: "a..b", kind: "agent", agent: { jobType: "senior:feature", prompt: "a", repository: "acme/one" } },
+      { id: "a.lock", kind: "agent", agent: { jobType: "senior:feature", prompt: "b", repository: "acme/two" } },
+      { id: "ok", kind: "agent", agent: { jobType: "senior:feature", prompt: "c", repository: "acme/three" } },
+    ],
+    edges: [{ from: "a..b", to: "a.lock" }, { from: "a.lock", to: "ok" }],
+  };
+  const p = await prepareOk(graph, {});
+  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("repository.branch.create"));
+  // Only the valid-id cell keeps a branch.create; the two invalid-ref ids emit none (their agents still
+  // provision an isolated clone, they just cut their own branch inside it — the pre-#776 fallback).
+  assertEquals(branches.length, 1, `only the valid id keeps a branch.create, got ${JSON.stringify(branches)}`);
+  assert(branches[0].includes('value="feat/ok"'), `expected feat/ok, got ${JSON.stringify(branches)}`);
+});
+
+test("agentNodeRepoEnvelope emits branch.create off the base when known, off the default when not, and omits it when blank (#776)", () => {
+  const withBase = (agentNodeRepoEnvelope("acme/one", "main", "feat/n1") as any)["io.nanobpm.agentTask"].repository;
+  assertEquals(withBase.ref, "main", "known base → checked-out ref");
+  assertEquals(withBase.branch.create, "feat/n1", "the harness cuts feat/<node.id> off the base");
+  const noBase = (agentNodeRepoEnvelope("acme/one", null, "feat/n2") as any)["io.nanobpm.agentTask"].repository;
+  assertEquals("ref" in noBase, false, "no base → clone the default branch");
+  assertEquals(noBase.branch.create, "feat/n2", "branch.create is still emitted off the default tip");
+  // A whitespace-tainted branch is trimmed; a blank/absent one omits the `branch` key (pre-#776 behaviour).
+  assertEquals((agentNodeRepoEnvelope("acme/one", "main", "  feat/n3  ") as any)["io.nanobpm.agentTask"].repository.branch.create, "feat/n3");
+  for (const blank of [null, undefined, "", "   "]) {
+    const r = (agentNodeRepoEnvelope("acme/one", "main", blank as any) as any)["io.nanobpm.agentTask"].repository;
+    assertEquals("branch" in r, false, `expected no branch key for ${JSON.stringify(blank)}`);
+  }
 });
 
 test("prepareDeliveryGraph seeds NO envelope ONLY on an EXPLICIT repoless run — the conscious opt-out (#729)", async () => {

package/app/deliveryRunner.ts

@@ -18,6 +18,7 @@ import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
+import { isPlausibleBranchName } from "./baseBranch.ts";
 import { AGENT_REPO_SPEC_HEADER, AGENT_TERMINAL_SUCCESS_STATUSES, assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
 import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, isResolvableRepo, RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError } from "./repoEnvelope.ts";
@@ -80,9 +81,10 @@ export interface DeliveryRunOptions extends DeliveryRunTimeouts {
   repository?: string | null;
   /** OPTIONAL run-level base-branch DEFAULT for `agent` nodes that declare a `repository` but no
    * `baseBranch` — 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). A
-   * node with a resolvable repository but no base clones the repo's default branch, so this is a
-   * convenience default, not a hard requirement. */
+   * exists yet). Per issue #776 the harness itself cuts the deterministic `feat/<node.id>` branch off
+   * this base (emitted as `branch.create`) so a forgetful agent can never be left committing on the base
+   * branch; a node with a resolvable repository but no base clones the repo's default branch, so this is
+   * a convenience default, not a hard requirement. */
   baseBranch?: string | null;
   /** EXPLICIT opt-out of repository provisioning (issue #729). `true` → the run is dispatched with NO
    * isolation envelope on ANY node (the per-node headers are stripped, the legacy launch-dir behaviour),
@@ -345,13 +347,28 @@ function injectAgentRepoEnvelopes(bpmn: string, graph: DeliveryGraph, options: D
   );
   return bpmn.replace(blockRe, (_full, indent: string, sq: string | undefined, dq: string | undefined, tail: string) => {
     const raw = sq ?? (dq ?? "").replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
-    const declared: { repository: string | null; baseBranch: string | null } = JSON.parse(raw);
+    const declared: { nodeId?: string; repository: string | null; baseBranch: string | null } = JSON.parse(raw);
     // `repoless` → strip the block entirely (no isolation envelope, the launch-dir fallback).
     if (repoless) return "";
     const effRepo = trimOrNull(declared.repository) ?? runRepo;
     const effBase = trimOrNull(declared.baseBranch) ?? runBase;
+    // The deterministic per-node isolation branch (issue #776): the harness cuts `feat/<node.id>` itself
+    // so a cell can never leave its agent committing on the checked-out base branch (a non-ff push that
+    // strands the run — merlin job 20974). The node id rides the marker so it survives into this
+    // per-block rewrite; delivery-graph agent cells are single-instance, so the static per-node branch
+    // never collides across siblings. Omitted when the marker predates the id (a blank id degrades to the
+    // pre-#776 agent-cuts-its-own-branch behaviour rather than an ill-formed `feat/`).
+    // A graph node id is only constrained by `^[A-Za-z_][A-Za-z0-9_.-]*$` (deliveryGraph.ts), which is
+    // laxer than git's ref rules: ids like `a..b`, `a.`, or `a.lock` pass id validation yet produce an
+    // ill-formed `feat/...` ref the harness cannot create — turning the isolation guarantee into a
+    // launch/checkout failure. Validate the DERIVED branch with the same `isPlausibleBranchName` gate the
+    // dispatch doors use and degrade to null (the pre-#776 agent-cuts-its-own-branch behaviour) rather
+    // than emit an unusable branch.create.
+    const nodeId = trimOrNull(declared.nodeId);
+    const derivedBranch = nodeId ? `feat/${nodeId}` : null;
+    const branchCreate = derivedBranch !== null && isPlausibleBranchName(derivedBranch) ? derivedBranch : null;
     // The unresolved invariant above guarantees a resolvable repo here on a non-repoless run.
-    const envelope = agentNodeRepoEnvelope(effRepo ?? "", effBase);
+    const envelope = agentNodeRepoEnvelope(effRepo ?? "", effBase, branchCreate);
     const flat = flattenAgentTaskEnvelope(envelope);
     const headerLines = Object.entries(flat).map(([k, v]) => `${indent}  <zeebe:header key="${xmlAttr(k)}" value="${xmlAttr(v)}" />`);
     if (headerLines.length === 0) return "";

package/app/repoEnvelope.ts

@@ -211,13 +211,26 @@ export function repoEnvelopeVars(
  * `ref`): a cross-repo graph node carries only its `owner/repo` (an issue ref names no branch), so when
  * neither the node nor the run declares a base the cell must still provision an isolated clone — of the
  * repository's DEFAULT branch. The harness `provisionRepo` omits `--branch` when `ref` is blank, so a
- * `ref`-less envelope clones the default branch (each agent then cuts its own `feat/<node.id>` branch
- * inside the isolated clone, unchanged). Returns `{}` for a `repo` that is not a plain `owner/repo` (an
- * unresolved cell — the runner's invariant rejects the run before this degrades to a launch-dir share).
- * Blobless single-branch shaping + `cloneTimeoutMs` (issues #287/#694) are emitted on every cell. */
-export function agentNodeRepoEnvelope(repo: string, base: string | null): Record<string, unknown> {
+ * `ref`-less envelope clones the default branch. Returns `{}` for a `repo` that is not a plain
+ * `owner/repo` (an unresolved cell — the runner's invariant rejects the run before this degrades to a
+ * launch-dir share). Blobless single-branch shaping + `cloneTimeoutMs` (issues #287/#694) are emitted on
+ * every cell.
+ *
+ * Deterministic isolation branch (issue #776): `branchCreate` (the per-node `feat/<node.id>`) is emitted
+ * as `branch.create` so the harness cuts the isolation branch ITSELF — mirroring the single-feature path
+ * (`repoEnvelopeVars`/`feature.ts`) — instead of delegating branch-cutting to agent prompt discipline. A
+ * forgetful agent that never branched used to commit on the checked-out BASE branch; its `git push
+ * origin <base>` was then rejected non-fast-forward and the whole run's work was stranded (merlin job
+ * 20974; harness counterpart jwulf/c8ctl-plugin-nano#231). Emitting `branch.create` makes it impossible
+ * for a cell to leave its agent committing on the base. Emitted independently of `ref`: when the base is
+ * unknown the harness cuts the branch off the cloned default tip; when known, off `ref`. Omitted for a
+ * blank `branchCreate` (falls back to the pre-#776 agent-cuts-its-own-branch behaviour). Delivery-graph
+ * agent cells are single-instance, so a static per-node `feat/<node.id>` never collides across siblings
+ * (the MI-child collision the issue flags does not arise in the current single-instance cells). */
+export function agentNodeRepoEnvelope(repo: string, base: string | null, branchCreate: string | null = null): Record<string, unknown> {
   if (!isPlainOwnerRepo(repo)) return {};
   const ref = typeof base === "string" && base.trim() !== "" ? base.trim() : null;
+  const create = typeof branchCreate === "string" && branchCreate.trim() !== "" ? branchCreate.trim() : null;
   return {
     [AGENT_TASK_NS]: {
       repository: {
@@ -226,9 +239,12 @@ export function agentNodeRepoEnvelope(repo: string, base: string | null): Record
         singleBranch: true,
         filter: "blob:none",
         cloneTimeoutMs: cloneTimeoutMs(),
-        // A per-node base (declared, or defaulted from the run level) — the branch the agent cuts its
+        // A per-node base (declared, or defaulted from the run level) — the branch the harness cuts its
         // `feat/<node.id>` off. Omitted when unknown so the harness clones the repo's default branch.
         ...(ref ? { ref, baseRef: ref } : {}),
+        // The deterministic isolation branch the harness cuts (issue #776), so the agent can never be
+        // left committing on the checked-out base branch. Off `ref` when known, else off the default tip.
+        ...(create ? { branch: { create } } : {}),
       },
       // Repo-provisioning auth gate (issue #770): as in `repoEnvelopeVars`, a repo-backed cell must
       // opt the harness into git-credential resolution (`task.allowPr`) or the clone fails with

package/openapi.yaml

@@ -2112,8 +2112,9 @@ components:
                   pattern: '^(?![/.-])(?!.*[/.]$)(?!.*\.\.)(?!.*//)(?!.*/\.)(?!.*\.lock(?:/|$))[A-Za-z0-9._/-]+$'
                   description: >-
                     OPTIONAL per-node base branch this agent node branches off (#739) — the `ref` the
-                    harness checks out in the isolated clone (the pre-PR shape: the agent cuts its own
-                    `feat/<node.id>` branch off this base). Absent → the run-level dispatch `baseBranch`
+                    harness checks out in the isolated clone (the pre-PR shape: the harness cuts the
+                    deterministic `feat/<node.id>` branch off this base itself, per #776, so a forgetful
+                    agent can never be left committing on the base branch). Absent → the run-level dispatch `baseBranch`
                     (else the node's repository default branch). A value that is not a plausible git
                     branch name is rejected at submit; the pattern mirrors the authoritative server-side
                     gate (`isPlausibleBranchName`, app/baseBranch.ts).
@@ -5005,7 +5006,7 @@ paths:
                                 type: string
                                 maxLength: 255
                                 pattern: ^(?![/.-])(?!.*[/.]$)(?!.*\.\.)(?!.*//)(?!.*/\.)(?!.*\.lock(?:/|$))[A-Za-z0-9._/-]+$
-                                description: "OPTIONAL per-node base branch this agent node branches off (#739) — the `ref` the harness checks out in the isolated clone (the pre-PR shape: the agent cuts its own `feat/<node.id>` branch off this base). Absent → the run-level dispatch `baseBranch` (else the node's repository default branch). A value that is not a plausible git branch name is rejected at submit; the pattern mirrors the authoritative server-side gate (`isPlausibleBranchName`, app/baseBranch.ts)."
+                                description: "OPTIONAL per-node base branch this agent node branches off (#739) — the `ref` the harness checks out in the isolated clone (the pre-PR shape: the harness cuts the deterministic `feat/<node.id>` branch off this base itself, per #776, so a forgetful agent can never be left committing on the base branch). Absent → the run-level dispatch `baseBranch` (else the node's repository default branch). A value that is not a plausible git branch name is rejected at submit; the pattern mirrors the authoritative server-side gate (`isPlausibleBranchName`, app/baseBranch.ts)."
                               converge:
                                 type: boolean
                                 description: 'OPTIONAL first-class CONVERGE policy (ADR 0006 §3 / S5) — a DECLARED, compiler- validated completion-policy flag on this cell node. It declares that the node''s opened PR is to be driven through the review-convergence loop to green as an edge-gated completion policy; this slice adds and validates the flag, with the delivery-graph execution wiring that consumes it landing in a follow-up slice. It supersedes (in intent) the emergent `feature.bpmn` `gw-converge` gateway and the "un-draft + merge #B" prompt prose a delivery-graph `agent` node used to smuggle. Converge and merge are SEPARABLE phases; a node may converge without merging (stop at green and gate the landing behind a downstream node).'

package/package.json

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