@nanobpm/nano-workforce 0.208.3 → 0.208.4

package/AGENTS.md

@@ -253,6 +253,23 @@ Two different `nano:dataEnvelope` uses have different rules — don't conflate t
   it as a process variable: besides being unnecessary, seeding a var an
   in-subprocess gateway reads re-introduces the multi-instance `=null`-shadow
   gotcha above.
+- **A per-MI-child value reaches an agent job's reserved `io.nanobpm.agentTask`
+  envelope via a worker result key literally NAMED with the dotted path — never a
+  dotted `ioMapping` target.** The whole-run seed can only set the
+  `io.nanobpm.agentTask` object ONCE at the root (uniform for every cell), so a
+  per-slice field (e.g. the implement-cell's deterministic `branch.create =
+  feat/<task.id>`, issue #945) can't ride it. A `<zeebe:output
+  target="io.nanobpm.agentTask.branch.create">` does NOT work — a dotted ioMapping
+  target builds a NESTED `{io:{nanobpm:{agentTask:…}}}` object the flat-key harness
+  never reads. The working channel: a worker running in a per-slice process instance (e.g.
+  `pr.slice-branch`, the first step of each implement-cell instance — NOT a task in the shared MI body, whose undeclared result keys land on the shared root where a sibling overwrites them) returns a result key literally named
+  `"io.nanobpm.agentTask.branch.create"`; the engine propagates worker result
+  variables verbatim (mapped or not), materialising a FLAT dotted process variable
+  that the harness's `collectEnvelopeFrom` deep-merges with the whole-object seed.
+  Derive the value from the ONE canonical `sliceBranchCreate` (app/repoEnvelope.ts)
+  so the envelope, the prompt's branch instruction, and the reconcile lookup share a
+  single source. `recoverBranchCreate(headers, variables)` (same module) is the ONE
+  consumer-side mirror tests use to assert "the harness sees this branch".
 
 ## Urban page runtime: rendering primitives are not JS-truthy
 

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.208.4](https://github.com/nanobpm/nano-workforce/compare/v0.208.3...v0.208.4) (2026-11-11)
+
+### Bug Fixes
+
+* **plan-fanout:** emit deterministic branch.create on the implement-cell envelope ([#945](https://github.com/nanobpm/nano-workforce/issues/945)) ([#946](https://github.com/nanobpm/nano-workforce/issues/946)) ([0977243](https://github.com/nanobpm/nano-workforce/commit/097724344a2f3942af5b1796e2e0a7e8363b44f9))
+
 ## [0.208.3](https://github.com/nanobpm/nano-workforce/compare/v0.208.2...v0.208.3) (2026-11-11)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -479,7 +479,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`. 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.",
+      "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's per-slice `feat/<task.id>` differs per MI child and so can't ride the whole-epic seed — instead the `pr.slice-branch` worker — the first step of EACH implement-cell process instance, so the value is instance-local and sibling slices cannot overwrite it — stamps it as a FLAT dotted `io.nanobpm.agentTask.branch.create` process variable (issue #945, derived via the ONE canonical `sliceBranchCreate`), which the harness's `collectEnvelopeFrom` deep-merges with the whole-object seed so a retry re-derives the SAME branch and the durable WIP checkpoint restore matches). 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 } }  — `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`).',
   },

package/app/feature.ts

@@ -21,7 +21,7 @@ import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { derivedTrackingTable } from "./instanceTracking.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
 import type { ReadinessProbe } from "./readiness.ts";
-import { requireRepoEnvelopeVars } from "./repoEnvelope.ts";
+import { requireRepoEnvelopeVars, sliceBranchCreate } from "./repoEnvelope.ts";
 
 /** Optional intake-time readiness gate for a feature run (issue #295): the `capability`/`command`/…
  * probes the run must ALL satisfy before its implementation agent is dispatched (parked, durably, at
@@ -503,7 +503,10 @@ export async function startFeature(
   const taskId = featureTaskId(parsed.number);
   // Pre-PR feature branch (issue #684): the deterministic `feat/<task.id>` the harness creates off the
   // base for the implementation agent (the agent-guide's `feat/*` convention), matching `task.id`.
-  const prePrBranch = `feat/${taskId}`;
+  // Derived via the ONE canonical `sliceBranchCreate` (issue #945) so the whole-run feature seed and the
+  // epic plan-fanout's per-slice emission can never drift into two branch-naming sources. A single-issue
+  // task id is always `issue-<number>`, so the derivation is never null here.
+  const prePrBranch = sliceBranchCreate(taskId) ?? `feat/${taskId}`;
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: FEATURE_PROCESS_ID,
     variables: {

package/app/implementBranchContract.test.ts

@@ -0,0 +1,168 @@
+// DEFECT-CLASS GUARD (issue #945): every process path that activates an agent job backed by a
+// repository envelope MUST name a deterministic `branch.create`, and that branch MUST be the one the
+// agent's prompt tells it to use — `feat/<task.id>` (resources/prompts/feature.md). Before #945 the
+// plan-fanout implement-cell carried NO `branch.create`: the deterministic branch existed only as
+// prose in the prompt, so every c8ctl retry cut a random `nano/agent-work/*` fallback branch and the
+// durable WIP checkpoint (keyed on `feat/<task.id>`) was never restored — each retry discarded the
+// prior session's work. The root cause was a DRIFT SURFACE: two sources of truth (the prompt text and
+// the envelope) for one fact.
+//
+// This guard pins the single source of truth (`sliceBranchCreate`, app/repoEnvelope.ts) and asserts
+// every consumer derives the SAME branch from it, so a new agent-job-with-repo path — or an edit that
+// re-introduces a hand-written branch — fails CI:
+//
+//  1. The ONE derivation: `sliceBranchCreate(taskId)` is `feat/<taskId>`, validated as a plausible git
+//     ref (an ill-formed id degrades to omission, never an unusable branch.create).
+//  2. Every consumer delegates to it: the whole-run feature seed (`feature.ts`), the implement-cell
+//     reconcile lookup (`implementReconcile.ts` `implementCellBranch`), and the per-slice envelope
+//     emission (`workers/caps-prepare`).
+//  3. The prompt's branch instruction is the SAME `feat/<task.id>` the envelope cuts — the two read
+//     off one value, not two.
+//  4. Every execution path into the `implement-task` agent job passes through the `pr.slice-branch`
+//     emitter, which runs INSIDE each implement-cell process instance (so siblings can't clobber it) —
+//     checked on the sourceRef/targetRef graph, not on XML declaration order.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import { implementCellBranch } from "./implementReconcile.ts";
+import { AGENT_TASK_BRANCH_CREATE_VAR, sliceBranchCreate } from "./repoEnvelope.ts";
+
+const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../resources/processes");
+const PROMPTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "../resources/prompts");
+
+function flat(rel: string): string {
+  return readFileSync(join(PROCESSES_DIR, rel), "utf8").replace(/\s+/g, " ");
+}
+
+test("contract: sliceBranchCreate is the ONE canonical feat/<task.id> derivation (#945)", () => {
+  // The deterministic branch for a real task id.
+  assertEquals(sliceBranchCreate("issue-7"), "feat/issue-7");
+  assertEquals(sliceBranchCreate("tool-metadata-engine"), "feat/tool-metadata-engine");
+  assertEquals(sliceBranchCreate("t1"), "feat/t1");
+  // A blank / missing id yields NO branch (the caller degrades to omission, never a bare `feat/`).
+  assertEquals(sliceBranchCreate(""), null);
+  assertEquals(sliceBranchCreate("   "), null);
+  assertEquals(sliceBranchCreate(null), null);
+  assertEquals(sliceBranchCreate(undefined), null);
+  // An id whose derived branch is not a plausible git ref degrades to null (no unusable branch.create).
+  assertEquals(sliceBranchCreate("bad..id"), null);
+  assertEquals(sliceBranchCreate("has space"), null);
+});
+
+test("contract: every implement-cell branch consumer derives from the ONE source (#945)", () => {
+  // The reconcile lookup (`implementCellBranch`) — which finds the adoptable PR on the slice's branch —
+  // MUST name the same branch the harness cuts (the envelope) and the prompt instructs. It delegates to
+  // `sliceBranchCreate`, so the two can never drift.
+  for (const taskId of ["issue-7", "tool-metadata-engine", "t1"]) {
+    assertEquals(
+      implementCellBranch(taskId),
+      sliceBranchCreate(taskId),
+      `implementCellBranch(${taskId}) must equal the canonical sliceBranchCreate (one source)`,
+    );
+  }
+});
+
+test("contract: the agent prompt's branch instruction is the SAME feat/<task.id> the envelope cuts (#945)", () => {
+  // The implement-cell's base prompt (feature.md) tells the agent to branch `feat/<task.id>`. That
+  // prose is the SECOND half of the contract — it must name the very branch `sliceBranchCreate`
+  // derives for the envelope, so the agent's self-cut branch (pre-#945 fallback) and the harness-cut
+  // branch (post-#945) are identical. Pin the literal placeholder so a prompt edit that renames the
+  // branch convention fails here.
+  const prompt = readFileSync(join(PROMPTS_DIR, "feature.md"), "utf8");
+  assert(
+    prompt.includes("feat/<task.id>"),
+    "feature.md must instruct the agent to branch `feat/<task.id>` — the same branch sliceBranchCreate derives",
+  );
+  // And the derivation of a concrete id must slot into that placeholder exactly.
+  assertEquals(`feat/<task.id>`.replace("<task.id>", "t1"), sliceBranchCreate("t1"));
+});
+
+/** Parse the `<bpmn:sequenceFlow>` graph (sourceRef → targetRef) and the boundary-event attachments
+ * (host → boundary, an implicit edge) of one process file. */
+function flowGraph(xml: string): Map<string, string[]> {
+  const g = new Map<string, string[]>();
+  const add = (from: string, to: string): void => {
+    g.set(from, [...(g.get(from) ?? []), to]);
+  };
+  for (const m of xml.matchAll(/<bpmn:sequenceFlow\b[^>]*>/g)) {
+    const src = /sourceRef="([^"]+)"/.exec(m[0])?.[1];
+    const tgt = /targetRef="([^"]+)"/.exec(m[0])?.[1];
+    if (src && tgt) add(src, tgt);
+  }
+  for (const m of xml.matchAll(/<bpmn:boundaryEvent\b[^>]*>/g)) {
+    const id = /\bid="([^"]+)"/.exec(m[0])?.[1];
+    const host = /attachedToRef="([^"]+)"/.exec(m[0])?.[1];
+    if (id && host) add(host, id);
+  }
+  return g;
+}
+
+/** Can `to` be reached from any of `from` without visiting `avoid`? */
+function reachableAvoiding(g: Map<string, string[]>, from: string[], to: string, avoid: string): boolean {
+  const seen = new Set<string>();
+  const stack = from.filter((f) => f !== avoid);
+  while (stack.length > 0) {
+    const n = stack.pop();
+    if (n === undefined || seen.has(n)) continue;
+    if (n === to) return true;
+    seen.add(n);
+    for (const next of g.get(n) ?? []) if (next !== avoid) stack.push(next);
+  }
+  return false;
+}
+
+function startEvents(xml: string): string[] {
+  return [...xml.matchAll(/<bpmn:startEvent\b[^>]*\bid="([^"]+)"/g)].map((m) => m[1] ?? "");
+}
+
+test("contract: every path into the implement-task agent job passes through the slice-branch emitter (#945)", () => {
+  const xml = flat("implement-cell.bpmn");
+  assert(
+    /<bpmn:serviceTask id="slice-branch"[^>]*> <bpmn:extensionElements> <zeebe:taskDefinition type="pr\.slice-branch"/.test(xml),
+    "implement-cell must declare the slice-branch task backed by the pr.slice-branch worker",
+  );
+  const g = flowGraph(xml);
+  const starts = startEvents(xml);
+  assert(starts.length > 0, "implement-cell must have a start event");
+  assert(reachableAvoiding(g, starts, "implement-task", "__none__"), "implement-task must be reachable at all");
+  assert(
+    !reachableAvoiding(g, starts, "implement-task", "slice-branch"),
+    "no execution path may reach implement-task without first passing the slice-branch emitter",
+  );
+});
+
+test("contract: the path checker detects a bypass of the emitter (guards the guard) (#945)", () => {
+  const bypass = flat("implement-cell.bpmn").replace(
+    /<bpmn:sequenceFlow id="ic_toSliceBranch" sourceRef="Start" targetRef="slice-branch" \/>/,
+    '<bpmn:sequenceFlow id="ic_toSliceBranch" sourceRef="Start" targetRef="implement-task" />',
+  );
+  assert(bypass.includes('sourceRef="Start" targetRef="implement-task"'), "fixture rewrite must apply");
+  assert(reachableAvoiding(flowGraph(bypass), startEvents(bypass), "implement-task", "slice-branch"));
+});
+
+test("contract: plan-fanout composes the implement step as a callActivity to implement-cell (#945)", () => {
+  // The emitter must run in a SEPARATE process instance per slice (its result keys land on that
+  // instance's root, never the shared epic root), so the MI body must call implement-cell rather than
+  // inline the agent task.
+  const xml = flat("plan-fanout.bpmn");
+  assert(
+    /<bpmn:callActivity[^>]*id="implement-cell-call"/.test(xml) &&
+      /<zeebe:calledElement processId="implement-cell"/.test(xml),
+    "plan-fanout must compose the per-wave implement step as a callActivity to implement-cell",
+  );
+  assert(!xml.includes('type="senior:feature"'), "plan-fanout must not inline the implement agent task");
+});
+
+test("contract: the per-slice branch.create rides the FLAT dotted variable the harness reads (#945)", () => {
+  // The emission channel is a process variable literally NAMED `io.nanobpm.agentTask.branch.create` —
+  // the dotted key the harness's `collectEnvelopeFrom` reassembles and deep-merges with the whole-object
+  // seed envelope. Pin the constant to that exact dotted name so a refactor can't silently move it to a
+  // nested object (a `<zeebe:ioMapping>` dotted target) the harness never reads.
+  assertEquals(AGENT_TASK_BRANCH_CREATE_VAR, "io.nanobpm.agentTask.branch.create");
+  assert(
+    AGENT_TASK_BRANCH_CREATE_VAR.startsWith("io.nanobpm.agentTask."),
+    "the per-slice branch.create variable must live under the reserved io.nanobpm.agentTask namespace",
+  );
+});

package/app/implementReconcile.ts

@@ -22,6 +22,7 @@ import { hasAnswerableQuestion } from "./escalationTaxonomy.ts";
 import type { HeadPr } from "./github.ts";
 import { isClaimedCompletion } from "./implementEscalationReason.ts";
 import { parsePr } from "./prParse.ts";
+import { sliceBranchCreate } from "./repoEnvelope.ts";
 
 /** The escalate-arm inputs the reconcile step reads from the implement-cell scope. `subjectKey` is the
  *  cell's `owner/repo#N` subject (a feature run's `feature_key`, or a wave slice's epic `plan_key`) —
@@ -99,9 +100,14 @@ export function retryNudgeFor(status: string): string {
   return `\n\n---\n\n**Automatic retry — your previous attempt claimed completion but no adoptable pull request was found.** You reported status "${status}", yet a GitHub lookup confirmed there is no adoptable pull request for this slice on its base branch. Your work may NOT be lost: if you already pushed the \`feat/<task.id>\` branch, recover it — check the remote with \`git ls-remote --heads origin feat/<task.id>\`, and if a pull request exists but targets the WRONG base, retarget it onto this run's base branch with \`gh pr edit --base <base>\`. Otherwise you likely worked OUTSIDE your run workspace (e.g. \`cd /tmp\`), and those edits were discarded on teardown. This is your FINAL automatic retry; the next failure escalates to a human. Work ONLY inside your run workspace, then \`git commit -s\`, push \`feat/<task.id>\`, and open a PR on the correct base with \`gh pr create\`. Report \`status: "opened"\` with the \`pr\` key — not "${status}".`;
 }
 
-/** The cell's deterministic implement branch — `feat/<task.id>` (resources/prompts/feature.md). */
+/** The cell's deterministic implement branch — `feat/<task.id>` (resources/prompts/feature.md).
+ *  Delegates to the ONE canonical `sliceBranchCreate` (issue #945) so the reconcile lookup, the
+ *  repository-envelope `branch.create` the harness cuts, and the prompt's branch instruction all share
+ *  a single derivation — they can never drift into two branch-naming sources. A task id reaching the
+ *  reconcile step is always a real id, so the derivation is never null here; the `?? `` fallback is
+ *  defensive only (an implausible id would simply find no adoptable PR, the pre-existing behaviour). */
 export function implementCellBranch(taskId: string): string {
-  return `feat/${taskId}`;
+  return sliceBranchCreate(taskId) ?? `feat/${taskId}`;
 }
 
 /** The adoptable PR from a head-branch listing: the first OPEN one (a merged/closed PR on the branch is

package/app/repoEnvelope.test.ts

@@ -12,82 +12,18 @@
 // 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";
+import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, recoverBranchCreate, 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 consumer mirror ─────────────────────────────────────────────────────────────
+// `recoverBranchCreate` (app/repoEnvelope.ts) is the ONE canonical mirror of the c8ctl harness's
+// consumer shape (`collectEnvelopeFrom` + `normalizeTaskEnvelope`): it reassembles the reserved
+// `io.nanobpm.agentTask` namespace out of BOTH a whole-object/JSON value AND flattened dotpath keys,
+// `deepMerge`s the two sources (variables over headers), and reads `branch` from the TOP LEVEL of the
+// merged envelope (`isPlainObject(raw.branch)`), NOT from `raw.repository.branch`. Keeping that mirror
+// in lock-step with the harness is the point of this test: if the producer emits a shape the consumer
+// doesn't read, the round-trip below drops `branch.create` and fails. Aliased here under the
+// harness-centric name the assertions read naturally with.
+const harnessReadsBranchCreate = recoverBranchCreate;
 
 // ─── The round-trip contract ──────────────────────────────────────────────────────────
 

package/app/repoEnvelope.ts

@@ -8,6 +8,7 @@
 // rebase) and the PRE-PR implementation dispatch (`feature.ts`: `startFeature`; `plan.ts`:
 // `startPlan` → the epic's `implement-cell`) derive from this single implementation without a
 // `plan.ts ↔ service.ts` import cycle (AGENTS.md "derivation over duplication — no drift surfaces").
+import { isPlausibleBranchName } from "./baseBranch.ts";
 import { readEnvOr } from "./contracts.ts";
 import { isCommitSha } from "./world/index.ts";
 
@@ -34,6 +35,43 @@ export function isResolvableRepo(repo: unknown): repo is string {
   return typeof repo === "string" && isPlainOwnerRepo(repo.trim());
 }
 
+/** The FLAT, dotted process-variable NAME a per-slice worker emits to attach the deterministic
+ * `branch.create` to the implement-cell's agent-job envelope (issue #945). The c8ctl harness's
+ * `collectEnvelopeFrom` reassembles the reserved namespace from BOTH the whole-object
+ * `io.nanobpm.agentTask` variable (the whole-epic seed, which carries `repository` + `task` but no
+ * per-slice `branch`) AND any dotted `io.nanobpm.agentTask.*` variables in scope, deep-merging them —
+ * so a dotted-name variable set in the MI-child scope lands on the SAME envelope the seed started,
+ * and `normalizeTaskEnvelope` then reads `branch.create` from the merged top level. A
+ * `<zeebe:ioMapping>` target with dots canNOT produce this: it builds a NESTED
+ * `{io:{nanobpm:{agentTask:…}}}` object the flat-key harness never reads (see {@link
+ * flattenAgentTaskEnvelope}). Only a worker result key literally NAMED with this dotted string (the
+ * engine propagates worker result variables verbatim, mapped or not) materialises the dotted
+ * variable. */
+export const AGENT_TASK_BRANCH_CREATE_VAR = `${AGENT_TASK_NS}.branch.create`;
+
+/** The ONE canonical derivation of an implementation slice's deterministic pre-PR branch —
+ * `feat/<taskId>` (the agent-guide's `feat/*` convention, resources/prompts/feature.md). This is the
+ * single source of truth for BOTH the whole-run feature seed (`feature.ts` `startFeature`, where the
+ * branch is known at seed time and rides the envelope's `branch.create` directly) AND the epic
+ * plan-fanout's per-slice emission (`workers/slice-branch`, run inside each implement-cell instance, which stamps it onto the implement-cell
+ * envelope via {@link AGENT_TASK_BRANCH_CREATE_VAR} because each slice's `task.id` differs per child
+ * and can't be named at the whole-epic seed). Issue #945: the plan-fanout implement-cell previously
+ * carried NO `branch.create`, so every c8ctl retry cut a random `nano/agent-work/*` fallback branch
+ * and the durable WIP checkpoint (keyed on `feat/<task.id>`) was never restored — each retry discarded
+ * the prior session's work. Deriving it here once keeps the envelope and the prompt's branch
+ * instruction (which tells the agent to use `feat/<task.id>`) from drifting into two sources.
+ *
+ * Returns `null` for a `taskId` whose derived branch is not a plausible git ref (mirrors the
+ * delivery-runner's `feat/<node.id>` guard, #776): an ill-formed `branch.create` would turn the
+ * isolation guarantee into a launch/checkout failure, so a blank/implausible id degrades to omission
+ * (the pre-#945 agent-cuts-its-own-branch behaviour) rather than emit an unusable value. */
+export function sliceBranchCreate(taskId: string | null | undefined): string | null {
+  const id = typeof taskId === "string" ? taskId.trim() : "";
+  if (id === "") return null;
+  const branch = `feat/${id}`;
+  return isPlausibleBranchName(branch) ? branch : null;
+}
+
 /** Flatten a repository-isolation envelope object (as built by {@link repoEnvelopeVars} —
  * `{ "io.nanobpm.agentTask": { repository: { … } } }`) into the FLAT, dotted `io.nanobpm.agentTask.*`
  * key → string-value pairs the c8ctl worker harness reads from a service task's `<zeebe:taskHeaders>`
@@ -66,6 +104,90 @@ export function flattenAgentTaskEnvelope(envelope: Record<string, unknown>): Rec
   return out;
 }
 
+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];
+    const next = cur[k];
+    // After the ensure-object step the slot is always a plain object; narrow via the type guard
+    // (no `as` — the ban-`as` gate) so the descent stays type-safe.
+    if (!isPlainObject(next)) {
+      const fresh: Record<string, unknown> = {};
+      cur[k] = fresh;
+      cur = fresh;
+    } else {
+      cur = next;
+    }
+  }
+  cur[path[path.length - 1]] = value;
+}
+
+/** Mirror of the c8ctl harness's `collectEnvelopeFrom`: reassemble the reserved namespace out of BOTH
+ * a whole-object/JSON `io.nanobpm.agentTask` value AND flattened dotted `io.nanobpm.agentTask.*` keys
+ * (the channel a per-slice worker's dotted-name result variable uses, issue #945), deep-merging the
+ * two. This is the ONE consumer-side mirror shared by the round-trip contract tests
+ * (`app/repoEnvelope.test.ts`) and the e2e fan-out proof (`e2e/plan-fanout.e2e.ts`) so producer and
+ * consumer can never drift into two readings of where `branch.create` lives. */
+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 c8ctl harness's `normalizeTaskEnvelope` branch slice: deep-merge the envelope
+ * recovered from `customHeaders` under that recovered from `variables` (variables win), then read
+ * `branch` from the TOP LEVEL of the merged envelope (`isPlainObject(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, or omitted it). This is the ONE place tests
+ * assert "the harness sees this branch" — keeping producer (`repoEnvelopeVars` / the per-slice dotted
+ * variable) and consumer pinned together (issues #882/#945). */
+export function recoverBranchCreate(
+  customHeaders: Record<string, unknown>,
+  variables: Record<string, unknown>,
+): string | undefined {
+  const merged = deepMerge(collectEnvelopeFrom(customHeaders), collectEnvelopeFrom(variables));
+  // deepMerge of two plain-object envelope slices is always a plain object; narrow via the type guard
+  // (no `as` — the ban-`as` gate). A non-object merge (impossible here) reads as "no branch".
+  const raw = isPlainObject(merged) ? merged : {};
+  const branch = isPlainObject(raw.branch) ? raw.branch : {};
+  const create = branch.create;
+  return create == null ? undefined : String(create);
+}
+
 /** Raised by `requireRepoEnvelopeVars` when the repository-isolation envelope is REQUIRED on a fan-out
  * path but its inputs are unresolved (a blank base/head `ref`, or a `repo` that is not a plain
  * `owner/repo`). Issue #729: the fan-out dispatch paths must fail loudly here rather than let

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.208.3",
-  "gitSha": "ff42e2a6fa77fd780949822adf3d4f2b9caefc38",
-  "gitTag": "v0.208.3",
-  "builtAt": "2026-11-11T02:35:58.462Z"
+  "version": "0.208.4",
+  "gitSha": "097724344a2f3942af5b1796e2e0a7e8363b44f9",
+  "gitTag": "v0.208.4",
+  "builtAt": "2026-11-11T03:16:35.107Z"
 }

package/e2e/feature-preflight.e2e.ts

@@ -159,7 +159,7 @@ describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)"
       assert.ok(
         flows.includes("ensure-base-branch->record-feature-implementing") &&
           flows.includes("record-feature-implementing->implement") &&
-          flows.includes("Start->implement-task"),
+          flows.includes("slice-branch->implement-task"),
         `the run reaches the implement agent (via the implement cell) only after the gate (flows: ${flows.join(", ")})`,
       );
       // A green probe never escalates.
@@ -192,7 +192,7 @@ describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)"
       assert.ok(!flows.includes("gw-readiness->readiness-preflight"), "an ungated feature never enters the preflight");
       assert.ok(
         flows.includes("record-feature-implementing->implement") &&
-          flows.includes("Start->implement-task"),
+          flows.includes("slice-branch->implement-task"),
         "an ungated feature reaches the implement agent (via the implement cell)",
       );
     } finally {

package/e2e/plan-fanout.e2e.ts

@@ -21,6 +21,7 @@ import { after, before, describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { recoverBranchCreate } from "../app/repoEnvelope.ts";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
 import { advancePastTimer, settleFully } from "./support/time.ts";
 
@@ -127,32 +128,127 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
   const singleTaskPlan: Stub = () => ({ tasks: [{ id: "t1", title: "T1", prompt: "do t1" }] });
   const approveReview: Stub = () => ({ approved: true, findings: "" });
 
-  test("host-git provisioning: each slice's implement-cell agent job carries the repository envelope (#684)", async () => {
+  test("host-git provisioning: each slice's implement-cell agent job carries the repository envelope AND the deterministic branch.create (#684/#945)", async () => {
     // The whole-epic seed emits `io.nanobpm.agentTask.repository` so every slice's `senior:feature`
     // agent gets an ISOLATED clone instead of clobbering the worker's launch dir. The process variable
     // 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 agentTask: any = null;
+    // `feat/<task.id>` differs per MI child, so it can't be named at seed time. Issue #945: the
+    // per-instance `slice-branch` worker (first step of each implement-cell) now stamps the deterministic `branch.create` (`feat/<task.id>`)
+    // onto the envelope as a FLAT dotted process variable (`io.nanobpm.agentTask.branch.create`), which
+    // the c8ctl harness deep-merges with the whole-object seed — so a retry re-derives the SAME branch
+    // and the durable WIP checkpoint restore matches (previously every retry cut a random
+    // `nano/agent-work/*` fallback and discarded the prior session's work).
+    let agentVars: Record<string, unknown> = {};
     await withApp(
       {
         "senior:plan": singleTaskPlan,
         "senior:plan-review": approveReview,
         "senior:feature": (job) => {
-          agentTask = (job.variables as Record<string, any>)["io.nanobpm.agentTask"] ?? null;
+          agentVars = job.variables as Record<string, unknown>;
           return { status: "blocked", summary: "n/a" };
         },
       },
       async ({ app }) => {
         await app.settle();
+        const agentTask = agentVars["io.nanobpm.agentTask"] as Record<string, any> | undefined;
         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");
-        // `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");
+        // The whole-object seed still omits `branch` (it can't name a per-child branch)…
+        assert.equal("branch" in agentTask, false, "the whole-object seed carries no per-slice branch");
+        // …but the per-instance slice-branch worker stamps it as a FLAT dotted variable, which the harness
+        // merges onto the SAME envelope. Assert the dotted variable is present and names the
+        // deterministic `feat/<task.id>` branch (the single task here is `t1`).
+        assert.equal(
+          agentVars["io.nanobpm.agentTask.branch.create"],
+          "feat/t1",
+          "slice-branch stamps the deterministic per-slice branch.create as a flat dotted variable (#945)",
+        );
+        // Round-trip through the harness normalizer shape: the merged envelope must recover
+        // `branch.create` from the top level (proving the dotted variable and the whole-object seed
+        // merge into one envelope the harness reads).
+        assert.equal(
+          recoverBranchCreate({}, agentVars),
+          "feat/t1",
+          "the harness merges the dotted branch.create with the whole-object seed envelope (#945)",
+        );
+      },
+    );
+  });
+
+  test("sibling isolation: two parallel slices each see their OWN branch.create, never a sibling's (#945)", async () => {
+    // A per-slice branch emitted into the SHARED plan-fanout MI body lands on the epic root, so a
+    // sibling's emission overwrites it and a slice can inherit `feat/<sibling>` — sending its work and
+    // checkpoint to the wrong branch. The emitter runs inside each implement-cell instance instead, so
+    // every activation's recovered branch must be `feat/<its own task.id>`.
+    const seen: Array<{ id: unknown; branch: string | undefined }> = [];
+    await withApp(
+      {
+        "senior:plan": () => ({
+          tasks: [
+            { id: "t1", title: "T1", prompt: "do t1" },
+            { id: "t2", title: "T2", prompt: "do t2" },
+          ],
+        }),
+        "senior:plan-review": approveReview,
+        "senior:feature": (job) => {
+          const vars = job.variables as Record<string, any>;
+          seen.push({ id: vars.task?.id, branch: recoverBranchCreate({}, vars) });
+          return { status: "blocked", summary: "n/a" };
+        },
+      },
+      async ({ app }) => {
+        await app.settle();
+        assert.deepEqual(
+          seen.map((s) => s.id).sort(),
+          ["t1", "t2"],
+          "both sibling slices activated their implement-task",
+        );
+        for (const s of seen) {
+          assert.equal(s.branch, `feat/${String(s.id)}`, `slice ${String(s.id)} must see its OWN branch.create`);
+        }
+      },
+    );
+  });
+
+  test("retry determinism: a re-dispatched implement-task names the SAME branch.create, so the WIP checkpoint restore matches (#945)", async () => {
+    // Issue #945's field failure: every c8ctl retry of an implement-cell slice cut a NEW random
+    // `nano/agent-work/*` fallback branch, so the durable WIP checkpoint (keyed on the deterministic
+    // `feat/<task.id>`) was NEVER restored — each retry started from the epic base and discarded the
+    // prior session's work. The fix makes `branch.create` a pure function of `task.id`, so a retry
+    // re-derives the SAME branch and the checkpoint restore matches. Drive the implement-task through
+    // TWO activations of the SAME slice (an escalation parks it; answering re-dispatches it — the same
+    // re-activation an idle-kill retry produces) and assert both carry the identical recovered
+    // `branch.create`.
+    const seenBranches: Array<string | undefined> = [];
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": (job) => {
+          seenBranches.push(recoverBranchCreate({}, job.variables as Record<string, unknown>));
+          // First activation escalates (parks for a human); the resume (second activation) blocks.
+          return seenBranches.length === 1
+            ? { status: "escalated", question: "Which API should I use?", summary: "parked for a human" }
+            : { status: "blocked", summary: "resumed after answer" };
+        },
+      },
+      async ({ app, processKey }) => {
+        // First activation parked on the human-escalation task; answer it to re-dispatch the SAME slice.
+        const task = await openTask(app, processKey, "escalation");
+        await app.engine.completeUserTask(task.userTaskKey, { resolution: "answer", answer: "use v2" });
+        await app.settle();
+        assert.equal(seenBranches.length, 2, "the implement-task was activated twice (initial + retry)");
+        assert.equal(seenBranches[0], "feat/t1", "the FIRST activation carries the deterministic branch.create");
+        assert.equal(
+          seenBranches[1],
+          seenBranches[0],
+          "the RETRY activation re-derives the SAME branch.create — the WIP checkpoint restore matches (#945)",
+        );
       },
     );
   });
@@ -532,7 +628,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("wait-caps-resolved->implement-cell-call") && flows.includes("Start->implement-task"),
+          flows.includes("wait-caps-resolved->implement-cell-call") && flows.includes("slice-branch->implement-task"),
           `caps-resolved released the barrier into the implement cell (flows: ${flows.join(", ")})`,
         );
         assert.equal(
@@ -614,7 +710,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
         assert.ok(
           answered.includes("w_gw_answer->record-task-implementing") &&
             answered.includes("record-task-implementing->implement-cell-call") &&
-            answered.includes("Start->implement-task"),
+            answered.includes("slice-branch->implement-task"),
           `answering the caps escalation reset the stale question and released the barrier into the implement cell (flows: ${answered.join(", ")})`,
         );
         assert.equal(featureRan, true, "the agent was dispatched once the operator answered the caps escalation");
@@ -668,7 +764,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
         assert.ok(
           entered.includes("w_gw_answer->record-task-implementing") &&
             entered.includes("record-task-implementing->implement-cell-call") &&
-            entered.includes("Start->implement-task"),
+            entered.includes("slice-branch->implement-task"),
           `answering the caps escalation reset the stale question and released the barrier into the implement cell (flows: ${entered.join(", ")})`,
         );
 

package/nano.app.json

@@ -180,6 +180,10 @@
       "taskType": "pr.select-wave",
       "handler": "workers/select-wave/worker.ts"
     },
+    {
+      "taskType": "pr.slice-branch",
+      "handler": "workers/slice-branch/worker.ts"
+    },
     {
       "taskType": "pr.caps-prepare",
       "handler": "workers/caps-prepare/worker.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.208.3",
+  "version": "0.208.4",
   "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/resources/processes/implement-cell.bpmn

@@ -17,8 +17,15 @@
       </nano:shapes>
     </bpmn:extensionElements>
     <bpmn:startEvent id="Start" name="Task">
-      <bpmn:outgoing>ic_toImplement</bpmn:outgoing>
+      <bpmn:outgoing>ic_toSliceBranch</bpmn:outgoing>
     </bpmn:startEvent>
+    <bpmn:serviceTask id="slice-branch" name="Stamp slice branch">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.slice-branch" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>ic_toSliceBranch</bpmn:incoming>
+      <bpmn:outgoing>ic_toImplement</bpmn:outgoing>
+    </bpmn:serviceTask>
     <bpmn:serviceTask id="implement-task" name="Implement (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:feature" />
@@ -143,7 +150,8 @@
       <bpmn:incoming>ic_reconciled</bpmn:incoming>
       <bpmn:incoming>ic_abandon</bpmn:incoming>
     </bpmn:endEvent>
-    <bpmn:sequenceFlow id="ic_toImplement" sourceRef="Start" targetRef="implement-task" />
+    <bpmn:sequenceFlow id="ic_toSliceBranch" sourceRef="Start" targetRef="slice-branch" />
+    <bpmn:sequenceFlow id="ic_toImplement" sourceRef="slice-branch" targetRef="implement-task" />
     <bpmn:sequenceFlow id="ic_toGw" sourceRef="implement-task" targetRef="ic_gw" />
     <bpmn:sequenceFlow id="ic_done" name="done" sourceRef="ic_gw" targetRef="ic_end">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "opened" or status = "blocked" or status = "skipped"</bpmn:conditionExpression>
@@ -175,149 +183,156 @@
           <dc:Bounds x="81" y="143" width="34" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
-      <bpmndi:BPMNShape id="BPMNShape_implement-task" bpmnElement="implement-task">
+      <bpmndi:BPMNShape id="BPMNShape_slice-branch" bpmnElement="slice-branch">
         <dc:Bounds x="216" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_implement-task" bpmnElement="implement-task">
+        <dc:Bounds x="416" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_ic_gw" bpmnElement="ic_gw" isMarkerVisible="true">
-        <dc:Bounds x="441" y="95" width="50" height="50" />
+        <dc:Bounds x="641" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="431" y="62" width="70" height="28" />
+          <dc:Bounds x="631" y="62" width="70" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_reconcile-implement" bpmnElement="reconcile-implement">
-        <dc:Bounds x="616" y="80" width="100" height="80" />
+        <dc:Bounds x="816" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_ic_reconcile_gw" bpmnElement="ic_reconcile_gw" isMarkerVisible="true">
-        <dc:Bounds x="816" y="95" width="50" height="50" />
+        <dc:Bounds x="1016" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="801" y="76" width="81" height="14" />
+          <dc:Bounds x="1001" y="76" width="81" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_escalate" bpmnElement="escalate">
-        <dc:Bounds x="1166" y="80" width="100" height="80" />
+        <dc:Bounds x="1366" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-escalation" bpmnElement="record-escalation">
-        <dc:Bounds x="966" y="80" width="100" height="80" />
+        <dc:Bounds x="1166" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-escalation-sla" bpmnElement="record-escalation-sla">
-        <dc:Bounds x="416" y="400" width="100" height="80" />
+        <dc:Bounds x="616" y="400" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_ic_gw_answer" bpmnElement="ic_gw_answer" isMarkerVisible="true">
-        <dc:Bounds x="1366" y="95" width="50" height="50" />
+        <dc:Bounds x="1566" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1323" y="150" width="56" height="14" />
+          <dc:Bounds x="1523" y="150" width="56" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-implementing" bpmnElement="record-implementing">
-        <dc:Bounds x="1516" y="240" width="100" height="80" />
+        <dc:Bounds x="1716" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_ic_end" bpmnElement="ic_end">
-        <dc:Bounds x="1548" y="102" width="36" height="36" />
+        <dc:Bounds x="1748" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1493" y="143" width="66" height="14" />
+          <dc:Bounds x="1693" y="143" width="66" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_be_implement_sla" bpmnElement="be_implement_sla">
-        <dc:Bounds x="248" y="142" width="36" height="36" />
+        <dc:Bounds x="448" y="142" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="170" y="183" width="72" height="28" />
+          <dc:Bounds x="370" y="183" width="72" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
-      <bpmndi:BPMNEdge id="BPMNEdge_ic_toImplement" bpmnElement="ic_toImplement">
+      <bpmndi:BPMNEdge id="BPMNEdge_ic_toSliceBranch" bpmnElement="ic_toSliceBranch">
         <di:waypoint x="116" y="120" />
         <di:waypoint x="216" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_ic_toGw" bpmnElement="ic_toGw">
+      <bpmndi:BPMNEdge id="BPMNEdge_ic_toImplement" bpmnElement="ic_toImplement">
         <di:waypoint x="316" y="120" />
-        <di:waypoint x="441" y="120" />
+        <di:waypoint x="416" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_ic_toGw" bpmnElement="ic_toGw">
+        <di:waypoint x="516" y="120" />
+        <di:waypoint x="641" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_escalate" bpmnElement="ic_escalate">
-        <di:waypoint x="491" y="120" />
-        <di:waypoint x="616" y="120" />
+        <di:waypoint x="691" y="120" />
+        <di:waypoint x="816" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="520" y="98" width="67" height="14" />
+          <dc:Bounds x="720" y="98" width="67" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_toReconcileGw" bpmnElement="ic_toReconcileGw">
-        <di:waypoint x="716" y="120" />
-        <di:waypoint x="816" y="120" />
+        <di:waypoint x="916" y="120" />
+        <di:waypoint x="1016" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_toRecordEscalation" bpmnElement="ic_toRecordEscalation">
-        <di:waypoint x="866" y="120" />
-        <di:waypoint x="966" y="120" />
+        <di:waypoint x="1066" y="120" />
+        <di:waypoint x="1166" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="883" y="128" width="67" height="14" />
+          <dc:Bounds x="1083" y="128" width="67" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_toEscalate" bpmnElement="ic_toEscalate">
-        <di:waypoint x="1066" y="120" />
-        <di:waypoint x="1166" y="120" />
-      </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_ic_toAnswerGw" bpmnElement="ic_toAnswerGw">
         <di:waypoint x="1266" y="120" />
         <di:waypoint x="1366" y="120" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_ic_toAnswerGw" bpmnElement="ic_toAnswerGw">
+        <di:waypoint x="1466" y="120" />
+        <di:waypoint x="1566" y="120" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_abandon" bpmnElement="ic_abandon">
-        <di:waypoint x="1416" y="120" />
-        <di:waypoint x="1548" y="120" />
+        <di:waypoint x="1616" y="120" />
+        <di:waypoint x="1748" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1456" y="98" width="53" height="14" />
+          <dc:Bounds x="1656" y="98" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_retry" bpmnElement="ic_retry">
-        <di:waypoint x="841" y="145" />
-        <di:waypoint x="841" y="280" />
-        <di:waypoint x="1516" y="280" />
+        <di:waypoint x="1041" y="145" />
+        <di:waypoint x="1041" y="280" />
+        <di:waypoint x="1716" y="280" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="846" y="223" width="39" height="14" />
+          <dc:Bounds x="1046" y="223" width="39" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_answerLoop" bpmnElement="ic_answerLoop">
-        <di:waypoint x="1391" y="145" />
-        <di:waypoint x="1391" y="280" />
-        <di:waypoint x="1516" y="280" />
+        <di:waypoint x="1591" y="145" />
+        <di:waypoint x="1591" y="280" />
+        <di:waypoint x="1716" y="280" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1396" y="206" width="49" height="14" />
+          <dc:Bounds x="1596" y="206" width="49" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_done" bpmnElement="ic_done">
-        <di:waypoint x="466" y="145" />
-        <di:waypoint x="466" y="200" />
-        <di:waypoint x="1566" y="200" />
-        <di:waypoint x="1566" y="138" />
+        <di:waypoint x="666" y="145" />
+        <di:waypoint x="666" y="200" />
+        <di:waypoint x="1766" y="200" />
+        <di:waypoint x="1766" y="138" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1000" y="208" width="32" height="14" />
+          <dc:Bounds x="1200" y="208" width="32" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_reconciled" bpmnElement="ic_reconciled">
-        <di:waypoint x="841" y="145" />
-        <di:waypoint x="841" y="180" />
-        <di:waypoint x="1566" y="180" />
-        <di:waypoint x="1566" y="138" />
+        <di:waypoint x="1041" y="145" />
+        <di:waypoint x="1041" y="180" />
+        <di:waypoint x="1766" y="180" />
+        <di:waypoint x="1766" y="138" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1097" y="158" width="53" height="14" />
+          <dc:Bounds x="1297" y="158" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_slaToEscalate" bpmnElement="ic_slaToEscalate">
-        <di:waypoint x="516" y="440" />
-        <di:waypoint x="1636" y="440" />
-        <di:waypoint x="1636" y="82" />
-        <di:waypoint x="1266" y="82" />
+        <di:waypoint x="716" y="440" />
+        <di:waypoint x="1836" y="440" />
+        <di:waypoint x="1836" y="82" />
+        <di:waypoint x="1466" y="82" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_sla" bpmnElement="ic_sla">
-        <di:waypoint x="266" y="178" />
-        <di:waypoint x="266" y="440" />
-        <di:waypoint x="416" y="440" />
+        <di:waypoint x="466" y="178" />
+        <di:waypoint x="466" y="440" />
+        <di:waypoint x="616" y="440" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="271" y="295" width="70" height="28" />
+          <dc:Bounds x="471" y="295" width="70" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_ic_reImplement" bpmnElement="ic_reImplement">
-        <di:waypoint x="1516" y="280" />
+        <di:waypoint x="1716" y="280" />
         <di:waypoint x="60" y="280" />
         <di:waypoint x="60" y="60" />
-        <di:waypoint x="266" y="60" />
-        <di:waypoint x="266" y="80" />
+        <di:waypoint x="466" y="60" />
+        <di:waypoint x="466" y="80" />
       </bpmndi:BPMNEdge>
     </bpmndi:BPMNPlane>
   </bpmndi:BPMNDiagram>

package/workers/caps-prepare/worker.test.ts

@@ -60,3 +60,14 @@ test("caps-prepare: a malformed need is dropped — only a valid remainder gates
   );
   assertEquals(mixed.hasNeeds, true, "a valid need still gates even alongside a malformed one");
 });
+
+// Issue #945: caps-prepare runs in the plan-fanout MI body, whose un-declared result keys land on the
+// SHARED epic root — so it must NOT stamp the per-slice branch.create (a sibling would overwrite it).
+// The emitter lives in each implement-cell instance (`pr.slice-branch`) instead.
+test("caps-prepare: does NOT emit the per-slice branch.create (it would leak across MI siblings) (#945)", async () => {
+  const out = await handler(
+    { variables: { planKey: "owner/repo#7", taskId: "t1", needs: [] } } as any,
+    {} as any,
+  );
+  assertEquals(Object.keys(out).filter((k) => k.startsWith("io.nanobpm.agentTask")), []);
+});

package/workers/slice-branch/worker.test.ts

@@ -0,0 +1,31 @@
+// Unit coverage for `pr.slice-branch` (issue #945): the per-slice deterministic `branch.create`,
+// emitted as the FLAT dotted variable the c8ctl harness reads, derived from the ONE canonical
+// `sliceBranchCreate`.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { AGENT_TASK_BRANCH_CREATE_VAR, sliceBranchCreate } from "../../app/repoEnvelope.ts";
+import handler from "./worker.ts";
+
+async function run(task: unknown): Promise<Record<string, unknown>> {
+  return (await handler({ variables: { task } } as any, {} as any)) ?? {};
+}
+
+test("slice-branch: stamps feat/<task.id> as the flat dotted branch.create (#945)", async () => {
+  const out = await run({ id: "t1", prompt: "x" });
+  assertEquals(out[AGENT_TASK_BRANCH_CREATE_VAR], "feat/t1");
+  assertEquals(out[AGENT_TASK_BRANCH_CREATE_VAR], sliceBranchCreate("t1"));
+});
+
+test("slice-branch: distinct slices derive distinct branches (sibling isolation is per-instance) (#945)", async () => {
+  const a = await run({ id: "t1" });
+  const b = await run({ id: "t2" });
+  assertEquals(a[AGENT_TASK_BRANCH_CREATE_VAR], "feat/t1");
+  assertEquals(b[AGENT_TASK_BRANCH_CREATE_VAR], "feat/t2");
+});
+
+test("slice-branch: a missing/blank/implausible/non-string id emits nothing (#945)", async () => {
+  for (const task of [undefined, null, "t1", [], {}, { id: "" }, { id: "  " }, { id: "bad..id" }, { id: 7 }]) {
+    const out = await run(task);
+    assertEquals(AGENT_TASK_BRANCH_CREATE_VAR in out, false, `no branch.create for ${JSON.stringify(task)}`);
+  }
+});

package/workers/slice-branch/worker.ts

@@ -0,0 +1,39 @@
+// pr.slice-branch — stamp the implement-cell agent job's deterministic per-slice `branch.create`
+// (issue #945).
+//
+// Runs as the FIRST step of the `implement-cell` process, i.e. inside each slice's OWN called process
+// instance. That is what makes the value child-local: a worker result key is propagated to the root
+// of the process instance the job belongs to, and every implement-cell call is a separate instance —
+// so sibling slices of one plan-fanout wave can never overwrite one another's branch (a key emitted
+// from the plan-fanout MI body would land on the shared epic root, where a sibling's prepare could
+// clobber it while this slice waits at its capability barrier).
+//
+// The value rides a result key literally NAMED `io.nanobpm.agentTask.branch.create`, which the engine
+// materialises as a FLAT dotted process variable the c8ctl harness's `collectEnvelopeFrom` deep-merges
+// with the whole-object seed envelope. A `<zeebe:ioMapping>` dotted target canNOT do this (it builds a
+// nested object the harness never reads). It is derived via the ONE canonical `sliceBranchCreate`, so
+// the envelope, the prompt's `feat/<task.id>` instruction, and the reconcile lookup share one source;
+// a retry (record-implementing → implement-task) stays in the same instance and re-reads the SAME
+// value, so the durable WIP checkpoint restore matches.
+//
+// PURE: no I/O. An implausible/missing `task.id` emits nothing (degrades to the agent cutting its own
+// branch) rather than an unusable branch.create.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { AGENT_TASK_BRANCH_CREATE_VAR, sliceBranchCreate } from "../../app/repoEnvelope.ts";
+
+interface In {
+  task?: unknown;
+}
+
+export function sliceTaskId(task: unknown): string | null {
+  if (task === null || typeof task !== "object" || Array.isArray(task)) return null;
+  const id: unknown = Reflect.get(task, "id");
+  return typeof id === "string" ? id : null;
+}
+
+const handler: AppJobHandler<In, Record<string, unknown>> = async (job) => {
+  const branchCreate = sliceBranchCreate(sliceTaskId(job.variables.task));
+  return branchCreate !== null ? { [AGENT_TASK_BRANCH_CREATE_VAR]: branchCreate } : {};
+};
+
+export default handler;