@nanobpm/nano-workforce 0.208.2 → 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,15 @@
+## [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
+
+* **merge:** never retire a merge loop into nothing on the convergence hand-off ([#944](https://github.com/nanobpm/nano-workforce/issues/944)) ([ff42e2a](https://github.com/nanobpm/nano-workforce/commit/ff42e2a6fa77fd780949822adf3d4f2b9caefc38)), closes [nanobpm/nano-bpm#1452](https://github.com/nanobpm/nano-bpm/issues/1452) [#939](https://github.com/nanobpm/nano-workforce/issues/939) [#943](https://github.com/nanobpm/nano-workforce/issues/943)
+
 ## [0.208.2](https://github.com/nanobpm/nano-workforce/compare/v0.208.1...v0.208.2) (2026-11-10)
 
 ### 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