@nanobpm/nano-workforce 0.201.2 → 0.201.3

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.201.3](https://github.com/nanobpm/nano-workforce/compare/v0.201.2...v0.201.3) (2026-10-10)
+
+### Bug Fixes
+
+* **repo-envelope:** emit branch.create as a top-level sibling of repository ([#885](https://github.com/nanobpm/nano-workforce/issues/885)) ([abb7b1c](https://github.com/nanobpm/nano-workforce/commit/abb7b1cc8439229724668fa85ffac22afd95c470)), closes [nanobpm/nano-bpm#1344](https://github.com/nanobpm/nano-bpm/issues/1344) [#227](https://github.com/nanobpm/nano-workforce/issues/227) [#882](https://github.com/nanobpm/nano-workforce/issues/882)
+
 ## [0.201.2](https://github.com/nanobpm/nano-workforce/compare/v0.201.1...v0.201.2) (2026-10-08)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -448,9 +448,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`. 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).",
+      "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). PLACEMENT (issue #882): `branch` is emitted as a TOP-LEVEL sibling of `repository` (and of `task`) under the namespace — the harness `normalizeTaskEnvelope` reads `branch` from the envelope ROOT (`isPlainObject(raw.branch)`), never from `repository.branch`, so the producer must not nest it there (nesting was the #227 two-sides-of-one-contract drift that left `branch.create` silently unread — nanobpm/nano-bpm#1344). The round-trip contract test `app/repoEnvelope.test.ts` pins producer and consumer together.",
     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 } }',
+      '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 } }  — `branch` is a TOP-LEVEL sibling of `repository` (issue #882): the harness `normalizeTaskEnvelope` reads it from the envelope root (`isPlainObject(raw.branch)`), NOT from `repository.branch`, so the flattened header is `io.nanobpm.agentTask.branch.create` (never `…repository.branch.create`).',
   },
   "epicSet.submit": {
     category: "wire",

package/app/deliveryRunner.test.ts

@@ -533,7 +533,7 @@ test("prepareDeliveryGraph injects the repository envelope PER agent cell from t
   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)}`);
+  assert(headers.some((h) => h.includes('io.nanobpm.agentTask.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.
@@ -590,7 +590,7 @@ test("a declared repository WITHOUT a base branch omits ref/baseRef — the harn
   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)}`);
+  assert(headers.some((h) => h.includes('io.nanobpm.agentTask.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 () => {
@@ -603,7 +603,7 @@ test("each agent cell gets its OWN deterministic feat/<node.id> branch.create
     edges: [{ from: "impl-a", to: "impl-b" }],
   };
   const p = await prepareOk(graph, {});
-  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("repository.branch.create"));
+  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("io.nanobpm.agentTask.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)}`);
@@ -612,7 +612,7 @@ test("each agent cell gets its OWN deterministic feat/<node.id> branch.create
 
 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");
+  assert(!p.bpmn.includes("io.nanobpm.agentTask.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 () => {
@@ -630,7 +630,7 @@ test("a node id that derives an invalid git ref degrades to NO branch.create —
     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"));
+  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("io.nanobpm.agentTask.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)}`);
@@ -638,16 +638,19 @@ test("a node id that derives an invalid git ref degrades to NO branch.create —
 });
 
 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");
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the
+  // envelope root, NOT from `repository.branch`.
+  const withBase = (agentNodeRepoEnvelope("acme/one", "main", "feat/n1") as any)["io.nanobpm.agentTask"];
+  assertEquals(withBase.repository.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("branch" in withBase.repository, false, "branch must NOT be nested under repository");
+  const noBase = (agentNodeRepoEnvelope("acme/one", null, "feat/n2") as any)["io.nanobpm.agentTask"];
+  assertEquals("ref" in noBase.repository, 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");
+  assertEquals((agentNodeRepoEnvelope("acme/one", "main", "  feat/n3  ") as any)["io.nanobpm.agentTask"].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;
+    const r = (agentNodeRepoEnvelope("acme/one", "main", blank as any) as any)["io.nanobpm.agentTask"];
     assertEquals("branch" in r, false, `expected no branch key for ${JSON.stringify(blank)}`);
   }
 });

package/app/feature.test.ts

@@ -196,11 +196,13 @@ test("startFeature: seeds the pre-PR repository envelope so the harness provisio
   // 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;
+  const ns = (captured.variables as Record<string, any>)["io.nanobpm.agentTask"];
+  const repo = ns.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)}`);
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the root.
+  assertEquals(ns.branch.create, "feat/issue-42");
+  assertEquals(ns.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");

package/app/plan.test.ts

@@ -244,10 +244,13 @@ test("startPlan pins the base branch: persisted on the row + seeded as baseBranc
   // 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;
+  const ns = seen["io.nanobpm.agentTask"];
+  const repo = ns.repository;
   assertEquals(repo.url, "https://github.com/owner/repo.git");
   assertEquals(repo.ref, "epic/agent-protocol");
-  assertEquals("branch" in repo, false);
+  // No isolation branch on the epic seed — `branch` is a top-level sibling of `repository` (#882),
+  // and it is omitted entirely here.
+  assertEquals("branch" in ns, false);
   assertEquals(repo.singleBranch, true);
   assertEquals(repo.filter, "blob:none");
 });

package/app/repoEnvelope.test.ts

@@ -0,0 +1,139 @@
+// Contract test for the agent-task repository envelope (issue #882): the producer
+// (`app/repoEnvelope.ts`) and the consumer (the c8ctl nano worker harness's
+// `normalizeTaskEnvelope`, c8ctl-plugin.js) must agree on WHERE the deterministic
+// `branch.create` lives. The harness reads it from the TOP LEVEL of the envelope
+// (`raw.branch`), NOT nested under `repository`. The producer once nested it under
+// `repository.branch` — a shape the consumer never reads — so `branch.create`
+// silently never took effect (retries couldn't resume their WIP checkpoint, pushes
+// were refused off the work branch; nanobpm/nano-bpm#1344). This is the
+// two-sides-of-one-contract drift #227 guards against, so this test round-trips the
+// emitted envelope through a faithful mirror of the harness's normalizer shape and
+// asserts the consumer actually recovers `branch.create` — pinning producer and
+// consumer together so they cannot drift again.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, repoEnvelopeVars } from "./repoEnvelope.ts";
+
+// ─── A faithful mirror of the harness's consumer shape ───────────────────────────────
+// These mirror the EXACT semantics of c8ctl-plugin-nano `normalizeTaskEnvelope`
+// (c8ctl-plugin.js): `collectEnvelopeFrom` reassembles the reserved
+// `io.nanobpm.agentTask` namespace out of BOTH a whole-object/JSON value AND flattened
+// dotpath keys, `deepMerge`s the two sources, and `normalizeTaskEnvelope` then reads
+// `branch` from the TOP LEVEL of the merged envelope (`isPlainObject(raw.branch)`),
+// NOT from `raw.repository.branch`. Keeping this mirror in lock-step with the harness
+// is the point of the test: if the producer emits a shape the consumer doesn't read,
+// the round-trip below drops `branch.create` and fails.
+const AGENT_TASK_NS = "io.nanobpm.agentTask";
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+function deepMerge(base: unknown, over: unknown): unknown {
+  if (!isPlainObject(base)) return isPlainObject(over) ? deepMerge({}, over) : over;
+  const out: Record<string, unknown> = { ...base };
+  if (!isPlainObject(over)) return out;
+  for (const [k, v] of Object.entries(over)) {
+    if (v === undefined) continue;
+    out[k] = isPlainObject(v) && isPlainObject(out[k]) ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+function setPath(obj: Record<string, unknown>, path: string[], value: unknown): void {
+  let cur = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const k = path[i];
+    if (!isPlainObject(cur[k])) cur[k] = {};
+    cur = cur[k] as Record<string, unknown>;
+  }
+  cur[path[path.length - 1]] = value;
+}
+
+/** Mirror of the harness's `collectEnvelopeFrom`: reassemble the reserved namespace from a
+ * whole-object/JSON value AND flattened dotpath keys (element templates / task headers emit the
+ * latter). */
+function collectEnvelopeFrom(source: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!isPlainObject(source)) return out;
+  const whole = source[AGENT_TASK_NS];
+  if (whole != null) {
+    let val: unknown = whole;
+    if (typeof whole === "string") {
+      try {
+        val = JSON.parse(whole);
+      } catch {
+        val = undefined;
+      }
+    }
+    if (isPlainObject(val)) Object.assign(out, deepMerge(out, val));
+  }
+  const prefix = `${AGENT_TASK_NS}.`;
+  for (const [key, value] of Object.entries(source)) {
+    if (!key.startsWith(prefix)) continue;
+    const rest = key.slice(prefix.length);
+    if (!rest) continue;
+    setPath(out, rest.split("."), value);
+  }
+  return out;
+}
+
+/** Mirror of the harness's `normalizeTaskEnvelope` branch slice: it reads `branch` from the TOP
+ * LEVEL of the merged envelope — `isPlainObject(raw.branch) ? raw.branch : {}` — never from
+ * `raw.repository.branch`. Returns the consumer's recovered `branch.create` (undefined when the
+ * producer put it somewhere the consumer doesn't look). */
+function harnessReadsBranchCreate(customHeaders: Record<string, unknown>, variables: Record<string, unknown>): string | undefined {
+  const raw = deepMerge(collectEnvelopeFrom(customHeaders), collectEnvelopeFrom(variables)) as Record<string, unknown>;
+  const branch = isPlainObject(raw.branch) ? raw.branch : {};
+  const create = branch.create;
+  return create == null ? undefined : String(create);
+}
+
+// ─── The round-trip contract ──────────────────────────────────────────────────────────
+
+test("contract: repoEnvelopeVars emits branch.create where the harness reads it (envelope TOP LEVEL, not repository.branch) (#882)", () => {
+  // The pre-PR implementation path: a deterministic feat/<task.id> branch the harness must cut.
+  const vars = repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7");
+  // Round-trip the emitted PROCESS-VARIABLE envelope through the harness normalizer shape.
+  const recovered = harnessReadsBranchCreate({}, vars);
+  assertEquals(
+    recovered,
+    "feat/issue-7",
+    "the harness reads branch.create from the envelope top level — nesting it under repository.branch drops it",
+  );
+});
+
+test("contract: repoEnvelopeVars PR path (ref == create == head) round-trips branch.create to the harness (#882/#231)", () => {
+  const vars = repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12");
+  assertEquals(harnessReadsBranchCreate({}, vars), "feat/issue-12");
+});
+
+test("contract: agentNodeRepoEnvelope round-trips the deterministic per-node branch through the harness (#882/#776)", () => {
+  const vars = agentNodeRepoEnvelope("acme/one", "main", "feat/n1");
+  assertEquals(harnessReadsBranchCreate({}, vars), "feat/n1");
+});
+
+test("contract: the FLATTENED per-cell task headers round-trip branch.create to the harness (#882/#739)", () => {
+  // The delivery-graph path delivers the envelope as FLAT dotted task headers, which the harness
+  // reassembles via collectEnvelopeFrom's dotpath branch. Round-trip the flattened headers through
+  // the same normalizer shape so the header channel can't drift from the consumer either.
+  const envelope = agentNodeRepoEnvelope("acme/one", "main", "feat/open-b");
+  const flat = flattenAgentTaskEnvelope(envelope);
+  // The flattened key must be the TOP-LEVEL `branch.create`, NOT `repository.branch.create`.
+  assert(
+    "io.nanobpm.agentTask.branch.create" in flat,
+    `expected a top-level io.nanobpm.agentTask.branch.create header, got ${JSON.stringify(Object.keys(flat))}`,
+  );
+  assert(
+    !("io.nanobpm.agentTask.repository.branch.create" in flat),
+    "branch.create must NOT be nested under repository — the harness never reads it there",
+  );
+  const recovered = harnessReadsBranchCreate(flat, {});
+  assertEquals(recovered, "feat/open-b", "the harness reassembles the flattened header into branch.create");
+});
+
+test("contract: an envelope with NO branch round-trips to undefined (the consumer's default), never a bogus value (#882)", () => {
+  // A blank branchCreate omits the key entirely; the harness must then see no branch.create.
+  const vars = repoEnvelopeVars("owner/repo", "main", null, null, null);
+  assertEquals(harnessReadsBranchCreate({}, vars), undefined);
+});

package/app/repoEnvelope.ts

@@ -187,19 +187,25 @@ export function repoEnvelopeVars(
         // 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) ? { sha: 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.
-        // 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() } }
-          : {}),
       },
+      // 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.
+      // 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.
+      //
+      // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness's
+      // `normalizeTaskEnvelope` reads it from the envelope root (`isPlainObject(raw.branch)`), NOT from
+      // `repository.branch`. Nesting it under `repository` was the two-sides-of-one-contract drift
+      // (#227) that left `branch.create` silently unread (retries couldn't resume, pushes were
+      // refused — nanobpm/nano-bpm#1344).
+      ...(typeof branchCreate === "string" && branchCreate.trim() !== ""
+        ? { branch: { create: branchCreate.trim() } }
+        : {}),
       // Repo-provisioning auth gate (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the
       // git credential (GITHUB_TOKEN, or the `gh` default when it's absent) for repository
       // provisioning when `task.allowPr` is truthy — `resolveJobSecrets` pulls the token behind that
@@ -251,10 +257,13 @@ export function agentNodeRepoEnvelope(repo: string, base: string | null, branchC
         // 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 } } : {}),
       },
+      // 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.
+      // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness's
+      // `normalizeTaskEnvelope` reads it from the envelope root, NOT from `repository.branch`, so the
+      // flattened per-cell header is `io.nanobpm.agentTask.branch.create` (not `…repository.branch.create`).
+      ...(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
       // `unable to get password from user`. Emitted on every resolved cell (past the `owner/repo`

package/app/service.test.ts

@@ -1415,27 +1415,30 @@ test("repoEnvelopeVars emits the push-checkpoint under the harness-read `sha` ke
 // 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;
+  const envelope = repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7") as any;
+  const ns = envelope["io.nanobpm.agentTask"];
+  const repo = ns.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");
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the
+  // envelope root, NOT from `repository.branch`.
+  assertEquals(ns.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch off the base");
+  assertEquals("branch" in repo, false, "branch must NOT be nested under repository — the harness never reads it there");
   // 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
+    (repoEnvelopeVars("owner/repo", "main", null, null, "  feat/issue-9  ") as any)["io.nanobpm.agentTask"]
       .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;
+    const r = (repoEnvelopeVars("owner/repo", "main", null, null, blank as any) as any)["io.nanobpm.agentTask"];
     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);
+  assertEquals("branch" in (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"], false);
 });
 
 // PR-path provisioning (jwulf/c8ctl-plugin-nano#231): the review-round / fix-ci / rebase call sites
@@ -1445,11 +1448,13 @@ test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#
 // `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)[
+  const ns = (repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12") as any)[
     "io.nanobpm.agentTask"
-  ].repository;
+  ];
+  const repo = ns.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");
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882), read by the harness from the root.
+  assertEquals(ns.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");
@@ -1496,9 +1501,9 @@ test("submitPr threads the resolved PR head into the envelope branch.create (#23
       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");
+    const ns = get()?.["io.nanobpm.agentTask"] as any;
+    assertEquals(ns?.repository?.ref, "feat/issue-12", "submitPr checks out the PR head branch");
+    assertEquals(ns?.branch?.create, "feat/issue-12", "submitPr passes headRef as branch.create, not a fallback");
   });
 });
 
@@ -1521,9 +1526,9 @@ test("startMerge threads the resolved PR head into the envelope branch.create (#
       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");
+    const ns = get()?.["io.nanobpm.agentTask"] as any;
+    assertEquals(ns?.repository?.ref, "feat/issue-13", "startMerge checks out the PR head branch");
+    assertEquals(ns?.branch?.create, "feat/issue-13", "startMerge passes headRef as branch.create, not a fallback");
   });
 });
 

package/e2e/feature-run.e2e.ts

@@ -133,11 +133,11 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
     // 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;
+    let agentTask: any = null;
     await withApp(
       {
         "senior:feature": (job) => {
-          agentRepo = (job.variables as Record<string, any>)["io.nanobpm.agentTask"]?.repository ?? null;
+          agentTask = (job.variables as Record<string, any>)["io.nanobpm.agentTask"] ?? null;
           return { status: "opened", pr: "owner/repo#101", summary: "built it" };
         },
       },
@@ -150,10 +150,12 @@ 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.ok(agentTask, "the senior:feature job carried the io.nanobpm.agentTask repository envelope");
+        const agentRepo = agentTask.repository;
         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");
+        // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the root.
+        assert.equal(agentTask.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");

package/e2e/plan-fanout.e2e.ts

@@ -131,22 +131,24 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
     // 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;
+    let agentTask: 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;
+          agentTask = (job.variables as Record<string, any>)["io.nanobpm.agentTask"] ?? 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.ok(agentTask, "the epic slice's senior:feature job carried the io.nanobpm.agentTask envelope");
+        const agentRepo = agentTask.repository;
         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");
+        // `branch` is a top-level sibling of `repository` (#882); the epic seed omits it entirely.
+        assert.equal("branch" in agentTask, 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");
       },

package/package.json

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